Summary

• Add a lightweight FastMCP stdio server (mcp-servers/hermes-memory-mcp.py) that exposes Hermes memory stores (MEMORY.md, USER.md) and session history (state.db) to any MCP-compatible client
• Enables Claude Code, Cursor, VS Code, and other MCP clients to read and write Hermes memory directly — bridging the gap that hermes mcp serve doesn't cover (conversation browsing only, no memory access)
• Aligned with Hermes internals: atomic writes (os.replace + fsync), file locking (fcntl.flock), prompt-injection scanning, §-delimited sections, char limits

Motivation

hermes mcp serve exposes 10 conversation/messaging tools but zero memory tools. Users running Hermes alongside Claude Code (or other MCP clients) have no way to share persistent memory between agents. This server fills that gap with 7 tools covering memory CRUD + session browsing for dream-consolidation workflows.

Tools (7)

Memory

Session (Dream Workflow)

Safety (aligned with tools/memory_tool.py)

• Atomic writes — temp file + os.replace() + fsync, no corruption on crash
• File locking — fcntl.flock() prevents race conditions with concurrent Hermes writes
• Prompt-injection scanning — blocks role hijacking, instruction override, chat-template tokens, invisible Unicode
• Read-only state.db — all session queries use ?mode=ro

Dream Workflow

Inspired by Honcho's on_session_end and Holographic's auto-extraction:

1. recent_sessions() → review what happened
2. session_read(id) → read the transcript
3. LLM extracts key insights
4. add_memory_entry() / remove_memory_entry() → consolidate
5. memory_status() → verify capacity

Automatable via Claude Code hooks, cron, or manual commands.

Files

mcp-servers/
├── hermes-memory-mcp.py      # FastMCP server (7 tools, ~440 lines)
└── hermes-memory-runner.sh    # Shell wrapper for `uv run`
skills/mcp/hermes-memory-bridge/
└── SKILL.md                   # Setup guide (Hermes + Claude Code dual registration)
tests/
└── test_hermes_memory_mcp.py  # 43 tests, all passing

Test Plan

43 pytest tests covering all tools and safety features:

• Security scanning: injection, chat templates, invisible Unicode, role hijack (5 tests)
• Memory CRUD: read/add/replace/remove, char limits, store validation (16 tests)
• Session tools: FTS5 search, transcript read, recent list, edge cases (15 tests)
• Safety primitives: atomic write, file locking (4 tests)
• Edge cases: empty stores, nonexistent sessions, overflow, truncation (3 tests)
• Uses tmp_path isolation with real SQLite — no mocks, matching repo test patterns

43 passed in 0.70s