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).

Related MCP server: memex

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.

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.