{
  "item": "Hermes",
  "fields": {
    "project_name": "Hermes Agent",
    "official_repo_url": "https://github.com/nousresearch/hermes-agent",
    "documentation_url": "https://hermes-agent.nousresearch.com/docs/",
    "what_it_does": "Hermes Agent is a full-featured AI assistant framework by Nous Research that provides an interactive CLI, multi-platform messaging gateway, skills system, cron scheduling, MCP integration, and IDE editor integration (VS Code/Zed/JetBrains via ACP). It acts as a unified layer connecting LLMs to messaging platforms, development tools, filesystems, browsers, and external APIs.",
    "license": "MIT (Copyright 2025 Nous Research)",
    "language_tech_stack": "Python (core: run_agent.py ~10,700 lines, cli.py ~10,000 lines, gateway/run.py ~9,000 lines, hermes_cli/main.py ~6,000 lines); SQLite with FTS5 for session/state storage; uv as package manager; Docusaurus for documentation site",
    "architecture_runtime_model": "Synchronous orchestration engine (AIAgent in run_agent.py) — single Python process that handles provider selection, prompt construction, tool execution, retries, fallback, callbacks, compression, and persistence. Three API modes: chat_completions, codex_responses, anthropic_messages. Gateway runs as separate background process connecting all messaging platforms. ACP adapter for IDE integration. Batch runner for trajectory generation.",
    "architecture_channel_support": "18 messaging platforms: Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, WeCom Callback, Weixin, BlueBubbles (iMessage), QQ, browser (webhook/API server). Platform adapters receive messages, route through per-chat session store, dispatch to AIAgent.",
    "architecture_persistence": "SQLite with FTS5 for session/state storage (hermes_state.py, gateway/session.py). Sessions persist across messages until reset. Configurable reset policies: daily (default 4:00 AM) or idle (default 1440 min), with per-platform overrides. Session lineage tracked.",
    "architecture_extensibility": "Skills system (SKILL.md format, agentskills.io compatible) in ~/.hermes/skills/; external skill directories via config.yaml; MCP client for external tool servers (stdio and HTTP); plugin system for memory providers and context engines; dynamic webhook subscriptions for event-driven activation; credential pools for key rotation; multiple profiles for isolated instances.",
    "features_agent_capabilities": "18+ LLM provider support (OpenRouter, Anthropic, OpenAI, Google, Nous Portal, DeepSeek, Claude Code/Copilot, Ollama, vLLM, SGLang, etc.); 47 registered tools across 19 toolsets; subagent delegation via delegate_tool; RL training via Atropos environments; voice mode (TTS/STT, Discord voice channels); context compression with summarization; Anthropic prompt caching; background sessions; filesystem checkpoints; progressive disclosure for token efficiency.",
    "features_skills_plugin_system": "SKILL.md format with progressive disclosure (3 levels: skills_list ~3k tokens, skill_view full content, skill_view with path for specific references). Bundled skills catalog, optional skills catalog (install explicitly). Agent can create/update/delete skills via skill_manage tool. External skill directories (read-only, local precedence). Platform-specific skills (macos/linux/windows). Conditional activation via fallback_for_toolsets/requires_toolsets. Secure setup on load (declared env vars asked only in local CLI, not messaging surfaces). Config settings in config.yaml. Slash commands: /skill-name.",
    "features_webhook_api": "Webhook platform adapter for inbound events; API server platform adapter for REST API access; dynamic webhook subscriptions via hermes webhook command; MCP protocol support for external tool servers (stdio and HTTP with headers auth).",
    "features_cron_scheduling": "Natural language and cron expression support; pause/resume/edit/trigger/remove jobs; attach skills to jobs; jobs.json storage; tick every 60 seconds; deliver results to target platform; cron scheduler inspectable via hermes cron; background job notifications to messaging (all/result/error/off).",
    "features_message_logging": "Sessions persist in SQLite with FTS5 full-text search; hermes sessions command to browse/export/prune/rename/delete sessions; hermes insights for token/cost/activity analytics; usage tracking per session.",
    "prerequisites_system_requirements": "Linux (native), macOS, WSL2 (Windows Subsystem for Linux 2), Termux (Android). Python 3.11 or newer required.",
    "prerequisites_required_accounts_tokens": "LLM API key required (at least one of: OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, or custom endpoint). Platform-specific tokens for messaging: Telegram (bot token), Discord (bot token), Slack (bot token), WhatsApp (phone number pairing), Signal (phone number + linked device), etc. OAuth flows supported for: Anthropic, Copilot, Codex, Nous Portal, Google Gemini CLI, Qwen OAuth.",
    "prerequisites_system_dependencies": "uv package manager (installed automatically by installer script); SQLite (built into Python); git (for installation); Node.js/npx (for MCP stdio servers). Optional: Chrome DevTools Protocol browser for browserbase; whisper for local STT.",
    "prerequisites_network_requirements": "Outbound HTTPS to LLM provider APIs; outbound HTTPS to messaging platform APIs; outbound HTTPS for web search/tools; inbound for gateway API server if enabled; specific ports for some platforms.",
    "installation_docker_method": "Use hermes gateway run (foreground) inside Docker/WSL2/Termux; no official Docker image documented — runs as standard Python application. Docker deployment is manual (pip install + environment configuration).",
    "installation_binary_method": "No standalone binary — installer script adds hermes to PATH: curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash. Installs to ~/.local/bin/hermes. Supports Linux, macOS, WSL2, Termux.",
    "installation_source_method": "git clone https://github.com/NousResearch/hermes-agent.git && cd hermes-agent && pip install -e \".[mcp]\" (or full extras). Requires uv: curl -LsSf https://astral.sh/uv/install.sh | sh.",
    "installation_post_install_steps": "hermes setup (interactive wizard for model/terminal/gateway/tools/agent); hermes model (select provider + enter API key); hermes gateway setup (configure messaging platforms); source shell profile (bashrc/zshrc); verify: hermes --version.",
    "configuration_config_file_format_location": "~/.hermes/ directory contains: config.yaml (main settings), .env (API keys and secrets), auth.json (credentials), SOUL.md (personality), memories/ (memory files), skills/ (installed skills), cron/ (scheduled jobs), sessions/ (session data), gateway.json (messaging platform configs), jobs.json (cron jobs). HERMES_HOME env var overrides default ~/.hermes/ for multiple installations.",
    "configuration_channel_setup_steps": "hermes gateway setup (interactive wizard with arrow-key selection); hermes whatsapp (WhatsApp pairing/setup flow with QR code); hermes pairing approve <platform> <code> (approve DM pairing requests); configure ALLOWED_USERS per platform in .env (recommended); hermes gateway start to start service.",
    "configuration_key_environment_variables": "LLM: OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, and 30+ other provider keys; HERMES_HOME (override config dir); HERMES_MODEL (process-level override); HERMES_INFERENCE_PROVIDER (auto/openrouter/anthropic/etc.); Tools: FIRECRAWL_API_KEY, TAVILY_API_KEY, EXA_API_KEY, BROWSERBASE_API_KEY, FAL_KEY, ELEVENLABS_API_KEY, etc.; Gateway: GATEWAY_ALLOWED_USERS, GATEWAY_ALLOW_ALL_USERS, HERMES_BACKGROUND_NOTIFICATIONS; MCP: per-server env vars in config.yaml; Platform: TELEGRAM_ALLOWED_USERS, DISCORD_ALLOWED_USERS, etc.",
    "configuration_security_settings": "7-layer defense: (1) user authorization allowlists per platform, (2) dangerous command approval prompts, (3) container isolation for code execution, (4) MCP credential filtering (env vars not leaked to sandboxes unless explicitly configured), (5) DM pairing with cryptographic codes (1-hour expiry, rate-limited), (6) session allowlisting, (7) terminal sandbox environments (local, docker, ssh, modal, daytona, singularity). Default deny-all in gateway. terminal.env_passthrough config option. Skill-declared env vars securely prompted in CLI only.",
    "operations_start_stop_restart_commands": "hermes gateway run (foreground, for Docker/WSL2/Termux); hermes gateway start (start systemd/launchd service); hermes gateway stop; hermes gateway restart; hermes gateway status [--system]; hermes gateway install (install as user service); sudo hermes gateway install --system (Linux boot-time system service).",
    "operations_auto_start_on_boot": "hermes gateway install (user-level service, Linux systemd or macOS launchd); sudo hermes gateway install --system (system-level, Linux only). For WSL2: use tmux + hermes gateway run (WSL systemd unreliable).",
    "operations_log_locations": "hermes logs (view/tail/filter agent/gateway/error logs); log files stored in ~/.hermes/logs/ (inferred from directory structure). hermes doctor for config/diagnostic issues.",
    "operations_update_procedure": "hermes update (pull latest code + reinstall dependencies); hermes --version to check current version.",
    "operations_backup_guidance": "hermes backup (back up ~/.hermes/ to zip file); hermes import (restore from backup zip). Also: MANUAL: zip -r ~/.hermes/ heremes-backup-$(date +%Y%m%d).zip.",
    "coexistence_openclaw_port_conflicts": "Unlikely conflict — OpenClaw gateway on ws://127.0.0.1:18789 (loopback), Hermes gateway uses internal port allocation (http server on variable port or configured port). Hermes also has an api_server platform adapter that would need a distinct port if enabled. No documented port conflicts with OpenClaw's default configuration.",
    "coexistence_openclaw_resource_planning": "Both Python applications with similar memory footprint; both run as background services; Hermes gateway is CPU-light except during active agent turns. On a VPS with 2GB+ RAM, both can run comfortably. Monitor with top/htop if running many concurrent sessions.",
    "coexistence_openclaw_whatsapp_multi_device": "Hermes WhatsApp uses a QR-code pairing/linking mechanism (like WhatsApp Web). OpenClaw WhatsApp uses a different linked device. Both would appear as separate devices on the same WhatsApp account — WhatsApp allows multiple linked devices (typically up to 4). This should work, though it means two separate AI assistants respond on the same account. No known conflicts.",
    "coexistence_openclaw_architecture_recommendations": "Run both on same VPS: separate HERMES_HOME (~/.hermes) and OpenClaw workspace. Use different ports for any exposed services. Consider: Hermes as primary AI + messaging hub; OpenClaw for specific additional channels or workflows. Both support Telegram, Discord, Slack, WhatsApp — they can coexist on the same platforms as independent bot instances with different bot tokens. Alternatively, use Hermes for developer/CLI work and OpenClaw for specific integrations.",
    "best_for": "Users wanting a unified AI assistant across 18+ messaging platforms with a full CLI; strong open-source ethos (MIT, Nous Research); deep terminal/code development integration (ACP for IDE, code execution, browser automation); local/offline operation with Ollama/vLLM; complex multi-step agentic workflows with skills and cron; researchers needing RL training environments (Atropos).",
    "weaknesses": "No native Windows support (WSL2 required); Python 3.11+ required; relatively new (active development, API may change); documentation primarily in English; WhatsApp uses QR linking (less stable than official WhatsApp Business API); no built-in Docker deployment (manual); resource-intensive for heavy concurrent use; security model requires careful allowlist configuration.",
    "same_vps_compatibility": "High — both are Python apps that can run on the same Linux VPS with independent configs. Key considerations: use different messaging bot tokens per platform to avoid confusion; be aware both will respond if configured identically; WhatsApp multi-device works but both appear as separate linked devices; no documented port conflicts; separate HERMES_HOME and OpenClaw workspace directories prevent config collision."
  },
  "sources": [
    "https://github.com/nousresearch/hermes-agent (repo)",
    "https://hermes-agent.nousresearch.com/docs/ (documentation site)",
    "https://hermes-agent.nousresearch.com/docs/getting-started/installation",
    "https://hermes-agent.nousresearch.com/docs/user-guide/configuration",
    "https://hermes-agent.nousresearch.com/docs/user-guide/messaging",
    "https://hermes-agent.nousresearch.com/docs/user-guide/features/skills",
    "https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp",
    "https://hermes-agent.nousresearch.com/docs/developer-guide/architecture",
    "https://hermes-agent.nousresearch.com/docs/reference/environment-variables",
    "https://hermes-agent.nousresearch.com/docs/reference/cli-commands",
    "https://hermes-agent.nousresearch.com/docs/reference/faq",
    "https://raw.githubusercontent.com/NousResearch/hermes-agent/main/LICENSE"
  ],
  "uncertain": [
    "Hermes gateway default HTTP port for api_server platform [uncertain]",
    "Hermes exact memory footprint under load [uncertain]",
    "Maximum concurrent sessions Hermes supports on a given VPS [uncertain]",
    "Hermes voice mode technical implementation details (STT engine, TTS provider) [uncertain]",
    "Hermes systemd service exact unit file location when installed [uncertain]",
    "WhatsApp multi-device stability over extended runtimes [uncertain]"
  ]
}