|
|
|
|
@@ -1,477 +0,0 @@
|
|
|
|
|
# Hermes Agent — Feature Census
|
|
|
|
|
|
|
|
|
|
**Epic:** [#290 — Know Thy Agent: Hermes Feature Census](https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent/issues/290)
|
|
|
|
|
**Date:** 2026-04-11
|
|
|
|
|
**Source:** Timmy_Foundation/hermes-agent (fork of NousResearch/hermes-agent)
|
|
|
|
|
**Upstream:** NousResearch/hermes-agent (last sync: 2026-04-07, 499 commits merged in PR #201)
|
|
|
|
|
**Codebase:** ~200K lines Python (335 source files), 470 test files
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 1. Feature Matrix
|
|
|
|
|
|
|
|
|
|
### 1.1 Memory System
|
|
|
|
|
|
|
|
|
|
| Feature | Status | File:Line | Notes |
|
|
|
|
|
|---------|--------|-----------|-------|
|
|
|
|
|
| **`add` action** | ✅ Exists | `tools/memory_tool.py:457` | Append entry to MEMORY.md or USER.md |
|
|
|
|
|
| **`replace` action** | ✅ Exists | `tools/memory_tool.py:466` | Find by substring, replace content |
|
|
|
|
|
| **`remove` action** | ✅ Exists | `tools/memory_tool.py:475` | Find by substring, delete entry |
|
|
|
|
|
| **Dual stores (memory + user)** | ✅ Exists | `tools/memory_tool.py:43-45` | MEMORY.md (2200 char limit) + USER.md (1375 char limit) |
|
|
|
|
|
| **Entry deduplication** | ✅ Exists | `tools/memory_tool.py:128-129` | Exact-match dedup on load |
|
|
|
|
|
| **Injection/exfiltration scanning** | ✅ Exists | `tools/memory_tool.py:85` | Blocks prompt injection, role hijacking, secret exfil |
|
|
|
|
|
| **Frozen snapshot pattern** | ✅ Exists | `tools/memory_tool.py:119-135` | Preserves LLM prefix cache across session |
|
|
|
|
|
| **Atomic writes** | ✅ Exists | `tools/memory_tool.py:417-436` | tempfile.mkstemp + os.replace |
|
|
|
|
|
| **File locking (fcntl)** | ✅ Exists | `tools/memory_tool.py:137-153` | Exclusive lock for concurrent safety |
|
|
|
|
|
| **External provider plugin** | ✅ Exists | `agent/memory_manager.py` | Supports 1 external provider (Honcho, Mem0, Hindsight, etc.) |
|
|
|
|
|
| **Provider lifecycle hooks** | ✅ Exists | `agent/memory_provider.py:55-66` | on_memory_write, prefetch, sync_turn, on_session_end, on_pre_compress, on_delegation |
|
|
|
|
|
| **Session search (past conversations)** | ✅ Exists | `tools/session_search_tool.py:492` | FTS5 search across SQLite message store |
|
|
|
|
|
| **Holographic memory** | 🔌 Plugin slot | Config `memory.provider` | Accepted as external provider name, not built-in |
|
|
|
|
|
| **Engram integration** | ❌ Not present | — | Not in codebase; Engram is a Timmy Foundation project |
|
|
|
|
|
| **Trust system** | ❌ Not present | — | No trust scoring on memory entries |
|
|
|
|
|
|
|
|
|
|
### 1.2 Tool System
|
|
|
|
|
|
|
|
|
|
| Feature | Status | File:Line | Notes |
|
|
|
|
|
|---------|--------|-----------|-------|
|
|
|
|
|
| **Central registry** | ✅ Exists | `tools/registry.py:290` | Module-level singleton, all tools self-register |
|
|
|
|
|
| **47 static tools** | ✅ Exists | See full list below | Organized in 21+ toolsets |
|
|
|
|
|
| **Dynamic MCP tools** | ✅ Exists | `tools/mcp_tool.py` | Runtime registration from MCP servers (17 in live instance) |
|
|
|
|
|
| **Tool approval system** | ✅ Exists | `tools/approval.py` | Manual/smart/off modes, dangerous command detection |
|
|
|
|
|
| **Toolset composition** | ✅ Exists | `toolsets.py:404` | Composite toolsets (e.g., `debugging = terminal + web + file`) |
|
|
|
|
|
| **Per-platform toolsets** | ✅ Exists | `toolsets.py` | `hermes-cli`, `hermes-telegram`, `hermes-discord`, etc. |
|
|
|
|
|
| **Skill management** | ✅ Exists | `tools/skill_manager_tool.py:747` | Create, patch, delete skill documents |
|
|
|
|
|
| **Mixture of Agents** | ✅ Exists | `tools/mixture_of_agents_tool.py:553` | Route through 4+ frontier LLMs |
|
|
|
|
|
| **Subagent delegation** | ✅ Exists | `tools/delegate_tool.py:963` | Isolated contexts, up to 3 parallel |
|
|
|
|
|
| **Code execution sandbox** | ✅ Exists | `tools/code_execution_tool.py:1360` | Python scripts with tool access |
|
|
|
|
|
| **Image generation** | ✅ Exists | `tools/image_generation_tool.py:694` | FLUX 2 Pro |
|
|
|
|
|
| **Vision analysis** | ✅ Exists | `tools/vision_tools.py:606` | Multi-provider vision |
|
|
|
|
|
| **Text-to-speech** | ✅ Exists | `tools/tts_tool.py:974` | Edge TTS, ElevenLabs, OpenAI, NeuTTS |
|
|
|
|
|
| **Speech-to-text** | ✅ Exists | Config `stt.*` | Local Whisper, Groq, OpenAI, Mistral Voxtral |
|
|
|
|
|
| **Home Assistant** | ✅ Exists | `tools/homeassistant_tool.py:456-483` | 4 HA tools (list, state, services, call) |
|
|
|
|
|
| **RL training** | ✅ Exists | `tools/rl_training_tool.py:1376-1394` | 10 Tinker-Atropos tools |
|
|
|
|
|
| **Browser automation** | ✅ Exists | `tools/browser_tool.py:2137-2211` | 10 tools (navigate, click, type, scroll, screenshot, etc.) |
|
|
|
|
|
| **Gitea client** | ✅ Exists | `tools/gitea_client.py` | Gitea API integration |
|
|
|
|
|
| **Cron job management** | ✅ Exists | `tools/cronjob_tools.py:508` | Scheduled task CRUD |
|
|
|
|
|
| **Send message** | ✅ Exists | `tools/send_message_tool.py:1036` | Cross-platform messaging |
|
|
|
|
|
|
|
|
|
|
#### Complete Tool List (47 static)
|
|
|
|
|
|
|
|
|
|
| # | Tool | Toolset | File:Line |
|
|
|
|
|
|---|------|---------|-----------|
|
|
|
|
|
| 1 | `read_file` | file | `tools/file_tools.py:832` |
|
|
|
|
|
| 2 | `write_file` | file | `tools/file_tools.py:833` |
|
|
|
|
|
| 3 | `patch` | file | `tools/file_tools.py:834` |
|
|
|
|
|
| 4 | `search_files` | file | `tools/file_tools.py:835` |
|
|
|
|
|
| 5 | `terminal` | terminal | `tools/terminal_tool.py:1783` |
|
|
|
|
|
| 6 | `process` | terminal | `tools/process_registry.py:1039` |
|
|
|
|
|
| 7 | `web_search` | web | `tools/web_tools.py:2082` |
|
|
|
|
|
| 8 | `web_extract` | web | `tools/web_tools.py:2092` |
|
|
|
|
|
| 9 | `vision_analyze` | vision | `tools/vision_tools.py:606` |
|
|
|
|
|
| 10 | `image_generate` | image_gen | `tools/image_generation_tool.py:694` |
|
|
|
|
|
| 11 | `text_to_speech` | tts | `tools/tts_tool.py:974` |
|
|
|
|
|
| 12 | `skills_list` | skills | `tools/skills_tool.py:1357` |
|
|
|
|
|
| 13 | `skill_view` | skills | `tools/skills_tool.py:1367` |
|
|
|
|
|
| 14 | `skill_manage` | skills | `tools/skill_manager_tool.py:747` |
|
|
|
|
|
| 15 | `browser_navigate` | browser | `tools/browser_tool.py:2137` |
|
|
|
|
|
| 16 | `browser_snapshot` | browser | `tools/browser_tool.py:2145` |
|
|
|
|
|
| 17 | `browser_click` | browser | `tools/browser_tool.py:2154` |
|
|
|
|
|
| 18 | `browser_type` | browser | `tools/browser_tool.py:2162` |
|
|
|
|
|
| 19 | `browser_scroll` | browser | `tools/browser_tool.py:2170` |
|
|
|
|
|
| 20 | `browser_back` | browser | `tools/browser_tool.py:2178` |
|
|
|
|
|
| 21 | `browser_press` | browser | `tools/browser_tool.py:2186` |
|
|
|
|
|
| 22 | `browser_get_images` | browser | `tools/browser_tool.py:2195` |
|
|
|
|
|
| 23 | `browser_vision` | browser | `tools/browser_tool.py:2203` |
|
|
|
|
|
| 24 | `browser_console` | browser | `tools/browser_tool.py:2211` |
|
|
|
|
|
| 25 | `todo` | todo | `tools/todo_tool.py:260` |
|
|
|
|
|
| 26 | `memory` | memory | `tools/memory_tool.py:544` |
|
|
|
|
|
| 27 | `session_search` | session_search | `tools/session_search_tool.py:492` |
|
|
|
|
|
| 28 | `clarify` | clarify | `tools/clarify_tool.py:131` |
|
|
|
|
|
| 29 | `execute_code` | code_execution | `tools/code_execution_tool.py:1360` |
|
|
|
|
|
| 30 | `delegate_task` | delegation | `tools/delegate_tool.py:963` |
|
|
|
|
|
| 31 | `cronjob` | cronjob | `tools/cronjob_tools.py:508` |
|
|
|
|
|
| 32 | `send_message` | messaging | `tools/send_message_tool.py:1036` |
|
|
|
|
|
| 33 | `mixture_of_agents` | moa | `tools/mixture_of_agents_tool.py:553` |
|
|
|
|
|
| 34 | `ha_list_entities` | homeassistant | `tools/homeassistant_tool.py:456` |
|
|
|
|
|
| 35 | `ha_get_state` | homeassistant | `tools/homeassistant_tool.py:465` |
|
|
|
|
|
| 36 | `ha_list_services` | homeassistant | `tools/homeassistant_tool.py:474` |
|
|
|
|
|
| 37 | `ha_call_service` | homeassistant | `tools/homeassistant_tool.py:483` |
|
|
|
|
|
| 38-47 | `rl_*` (10 tools) | rl | `tools/rl_training_tool.py:1376-1394` |
|
|
|
|
|
|
|
|
|
|
### 1.3 Session System
|
|
|
|
|
|
|
|
|
|
| Feature | Status | File:Line | Notes |
|
|
|
|
|
|---------|--------|-----------|-------|
|
|
|
|
|
| **Session creation** | ✅ Exists | `gateway/session.py:676` | get_or_create_session with auto-reset |
|
|
|
|
|
| **Session keying** | ✅ Exists | `gateway/session.py:429` | platform:chat_type:chat_id[:thread_id][:user_id] |
|
|
|
|
|
| **Reset policies** | ✅ Exists | `gateway/session.py:610` | none / idle / daily / both |
|
|
|
|
|
| **Session switching (/resume)** | ✅ Exists | `gateway/session.py:825` | Point key at a previous session ID |
|
|
|
|
|
| **Session branching (/branch)** | ✅ Exists | CLI commands.py | Fork conversation history |
|
|
|
|
|
| **SQLite persistence** | ✅ Exists | `hermes_state.py:41-94` | sessions + messages + FTS5 search |
|
|
|
|
|
| **JSONL dual-write** | ✅ Exists | `gateway/session.py:891` | Backward compatibility with legacy format |
|
|
|
|
|
| **WAL mode concurrency** | ✅ Exists | `hermes_state.py:157` | Concurrent read/write with retry |
|
|
|
|
|
| **Context compression** | ✅ Exists | Config `compression.*` | Auto-compress when context exceeds ratio |
|
|
|
|
|
| **Memory flush on reset** | ✅ Exists | `gateway/run.py:632` | Reviews old transcript before auto-reset |
|
|
|
|
|
| **Token/cost tracking** | ✅ Exists | `hermes_state.py:41` | input, output, cache_read, cache_write, reasoning tokens |
|
|
|
|
|
| **PII redaction** | ✅ Exists | Config `privacy.redact_pii` | Hash user IDs, strip phone numbers |
|
|
|
|
|
|
|
|
|
|
### 1.4 Plugin System
|
|
|
|
|
|
|
|
|
|
| Feature | Status | File:Line | Notes |
|
|
|
|
|
|---------|--------|-----------|-------|
|
|
|
|
|
| **Plugin discovery** | ✅ Exists | `hermes_cli/plugins.py:5-11` | User (~/.hermes/plugins/), project, pip entry-points |
|
|
|
|
|
| **Plugin manifest (plugin.yaml)** | ✅ Exists | `hermes_cli/plugins.py` | name, version, requires_env, provides_tools, provides_hooks |
|
|
|
|
|
| **Lifecycle hooks** | ✅ Exists | `hermes_cli/plugins.py:55-66` | 9 hooks (pre/post tool_call, llm_call, api_request; on_session_start/end/finalize/reset) |
|
|
|
|
|
| **PluginContext API** | ✅ Exists | `hermes_cli/plugins.py:124-233` | register_tool, inject_message, register_cli_command, register_hook |
|
|
|
|
|
| **Plugin management CLI** | ✅ Exists | `hermes_cli/plugins_cmd.py:1-690` | install, update, remove, enable, disable |
|
|
|
|
|
| **Project plugins (opt-in)** | ✅ Exists | `hermes_cli/plugins.py` | Requires HERMES_ENABLE_PROJECT_PLUGINS env var |
|
|
|
|
|
| **Pip plugins** | ✅ Exists | `hermes_cli/plugins.py` | Entry-point group: hermes_agent.plugins |
|
|
|
|
|
|
|
|
|
|
### 1.5 Config System
|
|
|
|
|
|
|
|
|
|
| Feature | Status | File:Line | Notes |
|
|
|
|
|
|---------|--------|-----------|-------|
|
|
|
|
|
| **YAML config** | ✅ Exists | `hermes_cli/config.py:259-619` | ~120 config keys across 25 sections |
|
|
|
|
|
| **Schema versioning** | ✅ Exists | `hermes_cli/config.py` | `_config_version: 14` with migration support |
|
|
|
|
|
| **Provider config** | ✅ Exists | Config `providers.*`, `fallback_providers` | Per-provider overrides, fallback chains |
|
|
|
|
|
| **Credential pooling** | ✅ Exists | Config `credential_pool_strategies` | Key rotation strategies |
|
|
|
|
|
| **Auxiliary model config** | ✅ Exists | Config `auxiliary.*` | 8 separate side-task models (vision, compression, etc.) |
|
|
|
|
|
| **Smart model routing** | ✅ Exists | Config `smart_model_routing.*` | Route simple prompts to cheap model |
|
|
|
|
|
| **Env var management** | ✅ Exists | `hermes_cli/config.py:643-1318` | ~80 env vars across provider/tool/messaging/setting categories |
|
|
|
|
|
| **Interactive setup wizard** | ✅ Exists | `hermes_cli/setup.py` | Guided first-run configuration |
|
|
|
|
|
| **Config migration** | ✅ Exists | `hermes_cli/config.py` | Auto-migrates old config versions |
|
|
|
|
|
|
|
|
|
|
### 1.6 Gateway
|
|
|
|
|
|
|
|
|
|
| Feature | Status | File:Line | Notes |
|
|
|
|
|
|---------|--------|-----------|-------|
|
|
|
|
|
| **18 platform adapters** | ✅ Exists | `gateway/platforms/` | Telegram, Discord, Slack, WhatsApp, Signal, Mattermost, Matrix, HomeAssistant, Email, SMS, DingTalk, API Server, Webhook, Feishu, Wecom, Weixin, BlueBubbles |
|
|
|
|
|
| **Message queuing** | ✅ Exists | `gateway/run.py:507` | Queue during agent processing, media placeholder support |
|
|
|
|
|
| **Agent caching** | ✅ Exists | `gateway/run.py:515` | Preserve AIAgent instances per session for prompt caching |
|
|
|
|
|
| **Background reconnection** | ✅ Exists | `gateway/run.py:527` | Exponential backoff for failed platforms |
|
|
|
|
|
| **Authorization** | ✅ Exists | `gateway/run.py:1826` | Per-user allowlists, DM pairing codes |
|
|
|
|
|
| **Slash command interception** | ✅ Exists | `gateway/run.py` | Commands handled before agent (not billed) |
|
|
|
|
|
| **ACP server** | ✅ Exists | `acp_adapter/server.py:726` | VS Code / Zed / JetBrains integration |
|
|
|
|
|
| **Cron scheduler** | ✅ Exists | `cron/scheduler.py:850` | Full job scheduler with cron expressions |
|
|
|
|
|
| **Batch runner** | ✅ Exists | `batch_runner.py:1285` | Parallel batch processing |
|
|
|
|
|
| **API server** | ✅ Exists | `gateway/platforms/api_server.py` | OpenAI-compatible HTTP API |
|
|
|
|
|
|
|
|
|
|
### 1.7 Providers (20 supported)
|
|
|
|
|
|
|
|
|
|
| Provider | ID | Key Env Var |
|
|
|
|
|
|----------|----|-------------|
|
|
|
|
|
| Nous Portal | `nous` | `NOUS_BASE_URL` |
|
|
|
|
|
| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` |
|
|
|
|
|
| Anthropic | `anthropic` | (standard) |
|
|
|
|
|
| Google AI Studio | `gemini` | `GOOGLE_API_KEY`, `GEMINI_API_KEY` |
|
|
|
|
|
| OpenAI Codex | `openai-codex` | (standard) |
|
|
|
|
|
| GitHub Copilot | `copilot` / `copilot-acp` | (OAuth) |
|
|
|
|
|
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` |
|
|
|
|
|
| Kimi / Moonshot | `kimi-coding` | `KIMI_API_KEY` |
|
|
|
|
|
| Z.AI / GLM | `zai` | `GLM_API_KEY`, `ZAI_API_KEY` |
|
|
|
|
|
| MiniMax | `minimax` | `MINIMAX_API_KEY` |
|
|
|
|
|
| MiniMax (China) | `minimax-cn` | `MINIMAX_CN_API_KEY` |
|
|
|
|
|
| Alibaba / DashScope | `alibaba` | `DASHSCOPE_API_KEY` |
|
|
|
|
|
| Hugging Face | `huggingface` | `HF_TOKEN` |
|
|
|
|
|
| OpenCode Zen | `opencode-zen` | `OPENCODE_ZEN_API_KEY` |
|
|
|
|
|
| OpenCode Go | `opencode-go` | `OPENCODE_GO_API_KEY` |
|
|
|
|
|
| Qwen OAuth | `qwen-oauth` | (Portal) |
|
|
|
|
|
| AI Gateway | `ai-gateway` | (Nous) |
|
|
|
|
|
| Kilo Code | `kilocode` | (standard) |
|
|
|
|
|
| Ollama (local) | — | First-class via auxiliary wiring |
|
|
|
|
|
| Custom endpoint | `custom` | user-provided URL |
|
|
|
|
|
|
|
|
|
|
### 1.8 UI / UX
|
|
|
|
|
|
|
|
|
|
| Feature | Status | File:Line | Notes |
|
|
|
|
|
|---------|--------|-----------|-------|
|
|
|
|
|
| **Skin/theme engine** | ✅ Exists | `hermes_cli/skin_engine.py` | 7 built-in skins, user YAML skins |
|
|
|
|
|
| **Kawaii spinner** | ✅ Exists | `agent/display.py` | Animated faces, configurable verbs/wings |
|
|
|
|
|
| **Rich banner** | ✅ Exists | `banner.py` | Logo, hero art, system info |
|
|
|
|
|
| **Prompt_toolkit input** | ✅ Exists | `cli.py` | Autocomplete, history, syntax |
|
|
|
|
|
| **Streaming output** | ✅ Exists | Config `display.streaming` | Optional streaming |
|
|
|
|
|
| **Reasoning display** | ✅ Exists | Config `display.show_reasoning` | Show/hide chain-of-thought |
|
|
|
|
|
| **Cost display** | ✅ Exists | Config `display.show_cost` | Show $ in status bar |
|
|
|
|
|
| **Voice mode** | ✅ Exists | Config `voice.*` | Ctrl+B record, auto-TTS, silence detection |
|
|
|
|
|
| **Human delay simulation** | ✅ Exists | Config `human_delay.*` | Simulated typing delay |
|
|
|
|
|
|
|
|
|
|
### 1.9 Security
|
|
|
|
|
|
|
|
|
|
| Feature | Status | File:Line | Notes |
|
|
|
|
|
|---------|--------|-----------|-------|
|
|
|
|
|
| **Tirith security scanning** | ✅ Exists | `tools/tirith_security.py` | Pre-exec code scanning |
|
|
|
|
|
| **Secret redaction** | ✅ Exists | Config `security.redact_secrets` | Auto-strip secrets from output |
|
|
|
|
|
| **Memory injection scanning** | ✅ Exists | `tools/memory_tool.py:85` | Blocks prompt injection in memory |
|
|
|
|
|
| **URL safety** | ✅ Exists | `tools/url_safety.py` | URL reputation checking |
|
|
|
|
|
| **Command approval** | ✅ Exists | `tools/approval.py` | Manual/smart/off modes |
|
|
|
|
|
| **OSV vulnerability check** | ✅ Exists | `tools/osv_check.py` | Open Source Vulnerabilities DB |
|
|
|
|
|
| **Conscience validator** | ✅ Exists | `tools/conscience_validator.py` | SOUL.md alignment checking |
|
|
|
|
|
| **Shield detector** | ✅ Exists | `tools/shield/detector.py` | Jailbreak/crisis detection |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 2. Architecture Overview
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
┌─────────────────────────────────────────────────────────┐
|
|
|
|
|
│ Entry Points │
|
|
|
|
|
├──────────┬──────────┬──────────┬──────────┬─────────────┤
|
|
|
|
|
│ CLI │ Gateway │ ACP │ Cron │ Batch Runner│
|
|
|
|
|
│ cli.py │gateway/ │acp_apt/ │ cron/ │batch_runner │
|
|
|
|
|
│ 8620 ln │ run.py │server.py │sched.py │ 1285 ln │
|
|
|
|
|
│ │ 7905 ln │ 726 ln │ 850 ln │ │
|
|
|
|
|
└────┬─────┴────┬─────┴──────────┴──────┬───┴─────────────┘
|
|
|
|
|
│ │ │
|
|
|
|
|
▼ ▼ ▼
|
|
|
|
|
┌─────────────────────────────────────────────────────────┐
|
|
|
|
|
│ AIAgent (run_agent.py, 9423 ln) │
|
|
|
|
|
│ ┌──────────────────────────────────────────────────┐ │
|
|
|
|
|
│ │ Core Conversation Loop │ │
|
|
|
|
|
│ │ while iterations < max: │ │
|
|
|
|
|
│ │ response = client.chat(tools, messages) │ │
|
|
|
|
|
│ │ if tool_calls: handle_function_call() │ │
|
|
|
|
|
│ │ else: return response │ │
|
|
|
|
|
│ └──────────────────────┬───────────────────────────┘ │
|
|
|
|
|
│ │ │
|
|
|
|
|
│ ┌──────────────────────▼───────────────────────────┐ │
|
|
|
|
|
│ │ model_tools.py (577 ln) │ │
|
|
|
|
|
│ │ _discover_tools() → handle_function_call() │ │
|
|
|
|
|
│ └──────────────────────┬───────────────────────────┘ │
|
|
|
|
|
└─────────────────────────┼───────────────────────────────┘
|
|
|
|
|
│
|
|
|
|
|
┌────────────────────▼────────────────────┐
|
|
|
|
|
│ tools/registry.py (singleton) │
|
|
|
|
|
│ ToolRegistry.register() → dispatch() │
|
|
|
|
|
└────────────────────┬────────────────────┘
|
|
|
|
|
│
|
|
|
|
|
┌─────────┬───────────┼───────────┬────────────────┐
|
|
|
|
|
▼ ▼ ▼ ▼ ▼
|
|
|
|
|
┌────────┐┌────────┐┌──────────┐┌──────────┐ ┌──────────┐
|
|
|
|
|
│ file ││terminal││ web ││ browser │ │ memory │
|
|
|
|
|
│ tools ││ tool ││ tools ││ tool │ │ tool │
|
|
|
|
|
│ 4 tools││2 tools ││ 2 tools ││ 10 tools │ │ 3 actions│
|
|
|
|
|
└────────┘└────────┘└──────────┘└──────────┘ └────┬─────┘
|
|
|
|
|
│
|
|
|
|
|
┌──────────▼──────────┐
|
|
|
|
|
│ agent/memory_manager │
|
|
|
|
|
│ ┌──────────────────┐│
|
|
|
|
|
│ │BuiltinProvider ││
|
|
|
|
|
│ │(MEMORY.md+USER.md)│
|
|
|
|
|
│ ├──────────────────┤│
|
|
|
|
|
│ │External Provider ││
|
|
|
|
|
│ │(optional, 1 max) ││
|
|
|
|
|
│ └──────────────────┘│
|
|
|
|
|
└─────────────────────┘
|
|
|
|
|
|
|
|
|
|
┌─────────────────────────────────────────────────┐
|
|
|
|
|
│ Session Layer │
|
|
|
|
|
│ SessionStore (gateway/session.py, 1030 ln) │
|
|
|
|
|
│ SessionDB (hermes_state.py, 1238 ln) │
|
|
|
|
|
│ ┌───────────┐ ┌─────────────────────────────┐ │
|
|
|
|
|
│ │sessions.js│ │ state.db (SQLite + FTS5) │ │
|
|
|
|
|
│ │ JSONL │ │ sessions │ messages │ fts │ │
|
|
|
|
|
│ └───────────┘ └─────────────────────────────┘ │
|
|
|
|
|
└─────────────────────────────────────────────────┘
|
|
|
|
|
|
|
|
|
|
┌─────────────────────────────────────────────────┐
|
|
|
|
|
│ Gateway Platform Adapters │
|
|
|
|
|
│ telegram │ discord │ slack │ whatsapp │ signal │
|
|
|
|
|
│ matrix │ email │ sms │ mattermost│ api │
|
|
|
|
|
│ homeassistant │ dingtalk │ feishu │ wecom │ ... │
|
|
|
|
|
└─────────────────────────────────────────────────┘
|
|
|
|
|
|
|
|
|
|
┌─────────────────────────────────────────────────┐
|
|
|
|
|
│ Plugin System │
|
|
|
|
|
│ User ~/.hermes/plugins/ │ Project .hermes/ │
|
|
|
|
|
│ Pip entry-points (hermes_agent.plugins) │
|
|
|
|
|
│ 9 lifecycle hooks │ PluginContext API │
|
|
|
|
|
└─────────────────────────────────────────────────┘
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Key dependency chain:**
|
|
|
|
|
```
|
|
|
|
|
tools/registry.py (no deps — imported by all tool files)
|
|
|
|
|
↑
|
|
|
|
|
tools/*.py (each calls registry.register() at import time)
|
|
|
|
|
↑
|
|
|
|
|
model_tools.py (imports tools/registry + triggers tool discovery)
|
|
|
|
|
↑
|
|
|
|
|
run_agent.py, cli.py, batch_runner.py, environments/
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 3. Recent Development Activity (Last 30 Days)
|
|
|
|
|
|
|
|
|
|
### Activity Summary
|
|
|
|
|
|
|
|
|
|
| Metric | Value |
|
|
|
|
|
|--------|-------|
|
|
|
|
|
| Total commits (since 2026-03-12) | ~1,750 |
|
|
|
|
|
| Top contributor | Teknium (1,169 commits) |
|
|
|
|
|
| Timmy Foundation commits | ~55 (Alexander Whitestone: 21, Timmy Time: 22, Bezalel: 12) |
|
|
|
|
|
| Key upstream sync | PR #201 — 499 commits from NousResearch/hermes-agent (2026-04-07) |
|
|
|
|
|
|
|
|
|
|
### Top Contributors (Last 30 Days)
|
|
|
|
|
|
|
|
|
|
| Contributor | Commits | Focus Area |
|
|
|
|
|
|-------------|---------|------------|
|
|
|
|
|
| Teknium | 1,169 | Core features, bug fixes, streaming, browser, Telegram/Discord |
|
|
|
|
|
| teknium1 | 238 | Supplementary work |
|
|
|
|
|
| 0xbyt4 | 117 | Various |
|
|
|
|
|
| Test | 61 | Testing |
|
|
|
|
|
| Allegro | 49 | Fleet ops, CI |
|
|
|
|
|
| kshitijk4poor | 30 | Features |
|
|
|
|
|
| SHL0MS | 25 | Features |
|
|
|
|
|
| Google AI Agent | 23 | MemPalace plugin |
|
|
|
|
|
| Timmy Time | 22 | CI, fleet config, merge coordination |
|
|
|
|
|
| Alexander Whitestone | 21 | Memory fixes, browser PoC, docs, CI, provider config |
|
|
|
|
|
| Bezalel | 12 | CI pipeline, devkit, health checks |
|
|
|
|
|
|
|
|
|
|
### Key Upstream Changes (Merged in Last 30 Days)
|
|
|
|
|
|
|
|
|
|
| Change | PR | Impact |
|
|
|
|
|
|--------|----|--------|
|
|
|
|
|
| Browser provider switch (Browserbase → Browser Use) | upstream #5750 | Breaking change in browser tooling |
|
|
|
|
|
| notify_on_complete for background processes | upstream #5779 | New feature for async workflows |
|
|
|
|
|
| Interactive model picker (Telegram + Discord) | upstream #5742 | UX improvement |
|
|
|
|
|
| Streaming fix after tool boundaries | upstream #5739 | Bug fix |
|
|
|
|
|
| Delegate: share credential pools with subagents | upstream | Security improvement |
|
|
|
|
|
| Permanent command allowlist on startup | upstream #5076 | Bug fix |
|
|
|
|
|
| Paginated model picker for Telegram | upstream | UX improvement |
|
|
|
|
|
| Slack thread replies without @mentions | upstream | Gateway improvement |
|
|
|
|
|
| Supermemory memory provider (added then removed) | upstream | Experimental, rolled back |
|
|
|
|
|
| Background process management overhaul | upstream | Major feature |
|
|
|
|
|
|
|
|
|
|
### Timmy Foundation Contributions (Our Fork)
|
|
|
|
|
|
|
|
|
|
| Change | PR | Author |
|
|
|
|
|
|--------|----|--------|
|
|
|
|
|
| Memory remove action bridge fix | #277 | Alexander Whitestone |
|
|
|
|
|
| Browser integration PoC + analysis | #262 | Alexander Whitestone |
|
|
|
|
|
| Memory budget enforcement tool | #256 | Alexander Whitestone |
|
|
|
|
|
| Memory sovereignty verification | #257 | Alexander Whitestone |
|
|
|
|
|
| Memory Architecture Guide | #263, #258 | Alexander Whitestone |
|
|
|
|
|
| MemPalace plugin creation | #259, #265 | Google AI Agent |
|
|
|
|
|
| CI: duplicate model detection | #235 | Alexander Whitestone |
|
|
|
|
|
| Kimi model config fix | #225 | Bezalel |
|
|
|
|
|
| Ollama provider wiring fix | #223 | Alexander Whitestone |
|
|
|
|
|
| Deep Self-Awareness Epic | #215 | Bezalel |
|
|
|
|
|
| BOOT.md for repo | #202 | Bezalel |
|
|
|
|
|
| Upstream sync (499 commits) | #201 | Alexander Whitestone |
|
|
|
|
|
| Forge CI pipeline | #154, #175, #187 | Bezalel |
|
|
|
|
|
| Gitea PR & Issue automation skill | #181 | Bezalel |
|
|
|
|
|
| Development tools for wizard fleet | #166 | Bezalel |
|
|
|
|
|
| KNOWN_VIOLATIONS justification | #267 | Manus AI |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 4. Overlap Analysis
|
|
|
|
|
|
|
|
|
|
### What We're Building That Already Exists
|
|
|
|
|
|
|
|
|
|
| Timmy Foundation Planned Work | Hermes-Agent Already Has | Verdict |
|
|
|
|
|
|------------------------------|--------------------------|---------|
|
|
|
|
|
| **Memory system (add/remove/replace)** | `tools/memory_tool.py` with all 3 actions | **USE IT** — already exists, we just needed the `remove` fix (PR #277) |
|
|
|
|
|
| **Session persistence** | SQLite + JSONL dual-write system | **USE IT** — battle-tested, FTS5 search included |
|
|
|
|
|
| **Gateway platform adapters** | 18 adapters including Telegram, Discord, Matrix | **USE IT** — don't rebuild, contribute fixes |
|
|
|
|
|
| **Config management** | Full YAML config with migration, env vars | **USE IT** — extend rather than replace |
|
|
|
|
|
| **Plugin system** | Complete with lifecycle hooks, PluginContext API | **USE IT** — write plugins, not custom frameworks |
|
|
|
|
|
| **Tool registry** | Centralized registry with self-registration | **USE IT** — register new tools via existing pattern |
|
|
|
|
|
| **Cron scheduling** | `cron/scheduler.py` + `cronjob` tool | **USE IT** — integrate rather than duplicate |
|
|
|
|
|
| **Subagent delegation** | `delegate_task` with isolated contexts | **USE IT** — extend for fleet coordination |
|
|
|
|
|
|
|
|
|
|
### What We Need That Doesn't Exist
|
|
|
|
|
|
|
|
|
|
| Timmy Foundation Need | Hermes-Agent Status | Action |
|
|
|
|
|
|----------------------|---------------------|--------|
|
|
|
|
|
| **Engram integration** | Not present | Build as external memory provider plugin |
|
|
|
|
|
| **Holographic fact store** | Accepted as provider name, not implemented | Build as external memory provider |
|
|
|
|
|
| **Fleet orchestration** | Not present (single-agent focus) | Build on top, contribute patterns upstream |
|
|
|
|
|
| **Trust scoring on memory** | Not present | Build as extension to memory tool |
|
|
|
|
|
| **Multi-agent coordination** | delegate_tool supports parallel (max 3) | Extend for fleet-wide dispatch |
|
|
|
|
|
| **VPS wizard deployment** | Not present | Timmy Foundation domain — build independently |
|
|
|
|
|
| **Gitea CI/CD integration** | Minimal (gitea_client.py exists) | Extend existing client |
|
|
|
|
|
|
|
|
|
|
### Duplication Risk Assessment
|
|
|
|
|
|
|
|
|
|
| Risk | Level | Details |
|
|
|
|
|
|------|-------|---------|
|
|
|
|
|
| Memory system duplication | 🟢 LOW | We were almost duplicating memory removal (PR #278 vs #277). Now resolved. |
|
|
|
|
|
| Config system duplication | 🟢 LOW | Using hermes config directly via fork |
|
|
|
|
|
| Gateway duplication | 🟡 MEDIUM | Our fleet-ops patterns may partially overlap with gateway capabilities |
|
|
|
|
|
| Session management duplication | 🟢 LOW | Using hermes sessions directly |
|
|
|
|
|
| Plugin system duplication | 🟢 LOW | We write plugins, not a parallel system |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 5. Contribution Roadmap
|
|
|
|
|
|
|
|
|
|
### What to Build (Timmy Foundation Own)
|
|
|
|
|
|
|
|
|
|
| Item | Rationale | Priority |
|
|
|
|
|
|------|-----------|----------|
|
|
|
|
|
| **Engram memory provider** | Sovereign local memory (Go binary, SQLite+FTS). Must be ours. | 🔴 HIGH |
|
|
|
|
|
| **Holographic fact store** | Our architecture for knowledge graph memory. Unique to Timmy. | 🔴 HIGH |
|
|
|
|
|
| **Fleet orchestration layer** | Multi-wizard coordination (Allegro, Bezalel, Ezra, Claude). Not upstream's problem. | 🔴 HIGH |
|
|
|
|
|
| **VPS deployment automation** | Sovereign wizard provisioning. Timmy-specific. | 🟡 MEDIUM |
|
|
|
|
|
| **Trust scoring system** | Evaluate memory entry reliability. Research needed. | 🟡 MEDIUM |
|
|
|
|
|
| **Gitea CI/CD integration** | Deep integration with our forge. Extend gitea_client.py. | 🟡 MEDIUM |
|
|
|
|
|
| **SOUL.md compliance tooling** | Conscience validator exists (`tools/conscience_validator.py`). Extend it. | 🟢 LOW |
|
|
|
|
|
|
|
|
|
|
### What to Contribute Upstream
|
|
|
|
|
|
|
|
|
|
| Item | Rationale | Difficulty |
|
|
|
|
|
|------|-----------|------------|
|
|
|
|
|
| **Memory remove action fix** | Already done (PR #277). ✅ | Done |
|
|
|
|
|
| **Browser integration analysis** | Useful for all users (PR #262). ✅ | Done |
|
|
|
|
|
| **CI stability improvements** | Reduce deps, increase timeout (our commit). ✅ | Done |
|
|
|
|
|
| **Duplicate model detection** | CI check useful for all forks (PR #235). ✅ | Done |
|
|
|
|
|
| **Memory sovereignty patterns** | Verification scripts, budget enforcement. Useful broadly. | Medium |
|
|
|
|
|
| **Engram provider adapter** | If Engram proves useful, offer as memory provider option. | Medium |
|
|
|
|
|
| **Fleet delegation patterns** | If multi-agent coordination patterns generalize. | Hard |
|
|
|
|
|
| **Wizard health monitoring** | If monitoring patterns generalize to any agent fleet. | Medium |
|
|
|
|
|
|
|
|
|
|
### Quick Wins (Next Sprint)
|
|
|
|
|
|
|
|
|
|
1. **Verify memory remove action** — Confirm PR #277 works end-to-end in our fork
|
|
|
|
|
2. **Test browser tool after upstream switch** — Browserbase → Browser Use (upstream #5750) may break our PoC
|
|
|
|
|
3. **Update provider config** — Kimi model references updated (PR #225), verify no remaining stale refs
|
|
|
|
|
4. **Engram provider prototype** — Start implementing as external memory provider plugin
|
|
|
|
|
5. **Fleet health integration** — Use gateway's background reconnection patterns for wizard fleet
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Appendix A: File Counts by Directory
|
|
|
|
|
|
|
|
|
|
| Directory | Files | Lines |
|
|
|
|
|
|-----------|-------|-------|
|
|
|
|
|
| `tools/` | 70+ .py files | ~50K |
|
|
|
|
|
| `gateway/` | 20+ .py files | ~25K |
|
|
|
|
|
| `agent/` | 10 .py files | ~10K |
|
|
|
|
|
| `hermes_cli/` | 15 .py files | ~20K |
|
|
|
|
|
| `acp_adapter/` | 9 .py files | ~8K |
|
|
|
|
|
| `cron/` | 3 .py files | ~2K |
|
|
|
|
|
| `tests/` | 470 .py files | ~80K |
|
|
|
|
|
| **Total** | **335 source + 470 test** | **~200K + ~80K** |
|
|
|
|
|
|
|
|
|
|
## Appendix B: Key File Index
|
|
|
|
|
|
|
|
|
|
| File | Lines | Purpose |
|
|
|
|
|
|------|-------|---------|
|
|
|
|
|
| `run_agent.py` | 9,423 | AIAgent class, core conversation loop |
|
|
|
|
|
| `cli.py` | 8,620 | CLI orchestrator, slash command dispatch |
|
|
|
|
|
| `gateway/run.py` | 7,905 | Gateway main loop, platform management |
|
|
|
|
|
| `tools/terminal_tool.py` | 1,783 | Terminal orchestration |
|
|
|
|
|
| `tools/web_tools.py` | 2,082 | Web search + extraction |
|
|
|
|
|
| `tools/browser_tool.py` | 2,211 | Browser automation (10 tools) |
|
|
|
|
|
| `tools/code_execution_tool.py` | 1,360 | Python sandbox |
|
|
|
|
|
| `tools/delegate_tool.py` | 963 | Subagent delegation |
|
|
|
|
|
| `tools/mcp_tool.py` | ~1,050 | MCP client |
|
|
|
|
|
| `tools/memory_tool.py` | 560 | Memory CRUD |
|
|
|
|
|
| `hermes_state.py` | 1,238 | SQLite session store |
|
|
|
|
|
| `gateway/session.py` | 1,030 | Session lifecycle |
|
|
|
|
|
| `cron/scheduler.py` | 850 | Job scheduler |
|
|
|
|
|
| `hermes_cli/config.py` | 1,318 | Config system |
|
|
|
|
|
| `hermes_cli/plugins.py` | 611 | Plugin system |
|
|
|
|
|
| `hermes_cli/skin_engine.py` | 500+ | Theme engine |
|
