mcp-memory-gateway

A FastAPI + FastMCP shared-memory gateway in front of Honcho v3 — a single shared brain that multiple AI agents read from and write to. It exposes a small, curated, bearer-authenticated surface so every agent can recall context and log changes against one learning memory and stay in sync.

What it does

Endpoints / MCP tools (all bearer-authenticated):

• recall(query) — dialectic / similarity recall over the shared representation in Honcho
• remember(text, agent, tags) — store a durable observation
• log_change(summary, agent, area, …) — append a change to the shared, git-versioned ledger
• profile_card() — a compact profile/context card for session priming
• recent_changes(n) — the latest entries from the change ledger

The MCP server is mounted at /mcp; equivalent JSON routes are exposed for headless callers (shell scripts, other agent runtimes).

Design notes

• One curated front door over Honcho. The underlying Honcho v3 instance stays untouched and private; this gateway is the only thing agents talk to, which keeps the surface small and auditable.
• Two write paths, one source of truth. A change is written to Honcho and appended to a git-versioned Markdown ledger (EXTERNAL-CHANGES.md), so logging stays reliable even if the memory backend is slow — and the ledger is human-readable history.
• Auth that is SSE-safe. The /mcp mount is guarded by a raw-ASGI bearer middleware (not BaseHTTPMiddleware) so it authenticates without buffering the Server-Sent-Events stream.
• Structured, leak-free logging. Every request emits one compact JSON log line with a request id; payload text and the bearer token are never logged (there are tests that assert this).

Layout

• app/ — the service
  • app.py — FastAPI + FastMCP app, the 5 tools/routes, and bearer auth
  • honcho_client.py — thin client for a local Honcho v3 instance
  • ledger.py — git-versioned change-ledger writer
  • memory_mirror.py — mirrors recent changes into a delimited block of a memory file
  • structured_logging.py — JSON request/audit logging with a request-id context var
• bin/memory — a small memory CLI for headless callers (recall | card | recent | log)
• tests/ — pytest suite (test_app.py, test_honcho_client.py, test_ledger.py)
• .github/workflows/ci.yml — the CI pipeline
• requirements.txt, conftest.py — deps and test config
• .env.example — the environment variables the service reads

Running it

python -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env          # then set MEMORY_GATEWAY_TOKEN
export MEMORY_GATEWAY_TOKEN=...
uvicorn app.app:app --host 127.0.0.1 --port 8910

Run the tests:

pip install -r requirements.txt
python -m pytest -q

Configuration

All configuration is via environment variables (see .env.example).

The gateway centers on a single configurable primary peer — the Honcho peer whose profile card and recall it focuses on (set PRIMARY_PEER, default user). Point it at whichever identity your agents share context about.

Variable	Purpose	Default
MEMORY_GATEWAY_TOKEN	Bearer token required on every authed route and on /mcp	(required)
HONCHO_BASE	Base URL of the local Honcho v3 instance	http://127.0.0.1:8000
HONCHO_WORKSPACE	Honcho workspace id	agents
HONCHO_API_KEY	Optional bearer for Honcho	(unset)
PRIMARY_PEER	The Honcho peer the gateway centers on (profile card + recall)	user
FACTS_SESSION	Honcho session holding observations about the primary peer	facts
AGENT_MEMORY_MD	Plain-text memory file recent changes are mirrored into	data/MEMORY.md
BRAIN_DIR	Directory holding the EXTERNAL-CHANGES.md ledger	data

What's excluded & why (secrets never enter the repo)

Secrets, virtualenvs, and local runtime data are kept out of the repo by .gitignore and never committed:

• .env / *.env (except .env.example) — the bearer token lives only in an environment file (mode 0600) on the host and is never committed
• .venv/, __pycache__/, *.pyc — environment / build artifacts
• *.log, *.db — runtime logs and local data
• *.bak* — local backup files

This is a clean, self-contained extract of a larger private deployment: the business-specific modules and the production host details are intentionally not part of this public repo. What remains is the reusable core — the MCP/HTTP gateway, the Honcho client, the ledger, and their tests.

CI

CI runs on every push and pull request and performs:

1. Secret scan — gitleaks over the full git history
2. Lint + compile — ruff check and compileall
3. Tests — pytest

License

MIT — see LICENSE.