hybrid-memory-mcp

Universal FastMCP bridge into a hybrid memory stack. Any MCP-capable agent harness (Claude Code, Codex, RooCode, OpenClaw, Pi) adds one streamable-HTTP URL + bearer token and gains four tools against the SAME memory the host agent uses.

• OpenViking (primary, read+write) — mem_save, mem_search, mem_read
• Honcho (secondary, read-only reasoning) — mem_recall

Endpoint

URL:    http://<HOST>:8899/mcp        (bind a private LAN/VPN IP — not public)
Auth:   Authorization: Bearer <HMCP_BEARER_TOKEN from .env>
Transport: streamable-http

<HOST> is set via HMCP_BIND_HOST in .env (defaults to 127.0.0.1). Bind it to a private tailnet/LAN IP so only trusted machines on your network can reach it — this server is not designed for public internet exposure.

Tools

tool	args	backend
mem_save	content (req), category, source_agent	OV disk-write + async index
mem_search	query (req), limit=8	OV /search/search
mem_read	uri (req, must start viking://user/<user>/)	OV /content/read
mem_recall	query (req)	Honcho /chat (read-only)

category enum: pattern | entity | event (default) | preference. Every saved fact is footer-tagged [via: <source_agent>] for cross-harness attribution.

Configuration (.env, chmod 0600)

HMCP_BEARER_TOKEN=<generate: python3 -c "import secrets;print('hmcp_'+secrets.token_urlsafe(32))">
HMCP_BIND_HOST=127.0.0.1        # set to your private tailnet/LAN IP
HMCP_BIND_PORT=8899
OPENVIKING_ENDPOINT=http://127.0.0.1:1933
HONCHO_BASE_URL=http://localhost:8000
HONCHO_WORKSPACE=hermes
HONCHO_PEER=<your-peer-id>

Client config

Replace <TOKEN> with the value of HMCP_BEARER_TOKEN, and <HOST> with your bind IP.

Claude Code

claude mcp add --transport http hybrid-memory http://<HOST>:8899/mcp \
  --header "Authorization: Bearer <TOKEN>"

Codex (~/.codex/config.toml)

[mcp_servers.hybrid_memory]
url = "http://<HOST>:8899/mcp"
http_headers = { Authorization = "Bearer <TOKEN>" }

Generic streamable-http (RooCode / OpenClaw / Pi / any MCP client)

{
  "mcpServers": {
    "hybrid-memory": {
      "type": "streamable-http",
      "url": "http://<HOST>:8899/mcp",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}

Run

python3 -m venv venv && ./venv/bin/pip install -r requirements.txt
./venv/bin/python server.py     # binds $HMCP_BIND_HOST:$HMCP_BIND_PORT, mounts /mcp

For production, run under a supervisor with restart-on-failure (systemd unit, Restart=always).

Checks

bash specs/hybrid-memory-mcp/checks/roundtrip.sh    # C3 save->search->read (server stopped)
bash specs/hybrid-memory-mcp/checks/validation.sh   # C6 input-validation (server stopped)
bash specs/hybrid-memory-mcp/checks/auth.sh         # C4 bearer enforced (spins ephemeral server)
bash specs/hybrid-memory-mcp/checks/mcp_handshake.sh # C8 MCP initialize handshake
bash specs/hybrid-memory-mcp/checks/restart.sh      # C7 supervised persistence (after unit installed)

Design notes

• Async index waiting-list. OV's content/write runs the semantic+vector index inline behind one global write lock (~40s/write). mem_save does the durable part synchronously (write the file to disk — the memory is persisted and recoverable immediately) and hands the slow index to a background worker that drains one job at a time. Saves return in <10ms; search visibility follows asynchronously.
• Crash-durable queue. Each queued index job drops a pending-marker on disk; the worker deletes it after a successful index; on startup any survivors are re-queued. A kill -9 with items in flight loses nothing — markers reconcile on restart, and the worker also re-enqueues on transient failure so it self-heals once OV recovers.
• OV 0.3.8 create-mode bug. content/write cannot CREATE new files, so mem_save writes the file to the local store first, then content/write mode=replace to index.
• Graceful degradation. mem_recall returns {"status": "honcho unavailable", ...} instead of crashing when Honcho is down or slow.