# 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 |