mem0-mcp

Self-hosted agent memory: a thin stdio MCP bridge to a mem0 OSS server, plus the shared-memory skill that teaches agents how to use it.

Two parts:

• src/ — the MCP bridge (mem0-bridge-mcp), a small TypeScript/Bun stdio server.

• skills/shared-memory/ — the discipline skill (recall before re-deriving, store durable facts).

Spec-driven development (SDD), coded with Claude Fable.

Backend

The bridge talks to any self-hosted mem0 OSS server (FastAPI + Postgres/pgvector), configured via MEM0_API_URL / MEM0_API_KEY. Memories are namespaced by mem0's run_id: an auto-derived project scope (git remote repo name, else git top-level / cwd) plus a reserved global scope for cross-project facts. Default search merges project + global.

For the reconcile-on-add and question-rewrite features the server needs an LLM and an embedder (any OpenAI-compatible endpoint). To keep fact extraction from rewriting technical facts into third-person prose, set a custom_instructions prompt on the mem0 server (see mem0 docs).

Related MCP server: GroundMemory

Tools

Destructive safety: memory_id is validated as a UUID before any request, and redirects are never followed (a trailing-slash 307 could otherwise reroute a DELETE onto the server's delete-all route). memory_reset only works with a secret reset token sent as X-Reset-Token; the token is known to the human user alone, so an agent must ask for it before every reset and can never wipe the store on its own. Requests time out after 10s (adds after 45s, since infer:true runs two LLM calls).

Search/list hits render as one tab-separated line per memory: id score age text. The age (<1h, 5h, 3d, 2mo, from updated_at/created_at) makes staleness visible at recall time. Results are re-ranked by a recency-weighted score (half-life 90d, floor 0.6), so a fresh fact outranks an equally-relevant stale one without hiding a strongly matching old entry.

Question-style recall (HyDE-lite): before searching, a question query is rewritten by an LLM into one short declarative statement and searched alongside the raw query (answer-to-answer match). Best-effort: if the LLM is disabled, unreachable, or slow, search silently falls back to the raw query and never blocks.

Config (env)

Install & run

Requires Bun (the optional MEM0_INSECURE_TLS uses Bun's fetch tls extension; plain Node is not supported). Dependencies are declared in package.json / bun.lock (there is no Python requirements.txt — this is a Bun project).

bun install            # installs @modelcontextprotocol/sdk and dev types
bun run src/index.ts   # stdio MCP server

Register in Claude Code

claude mcp add mem0 \
  --env MEM0_API_URL=https://your-mem0-host \
  --env MEM0_API_KEY=your-key \
  -- bun run /path/to/mem0-mcp/src/index.ts

Verify (hits the configured server)

MEM0_API_URL=… MEM0_API_KEY=… bun run src/selftest.ts        # live smoke test
MEM0_API_URL=… MEM0_API_KEY=… bun run src/retrieval-eval.ts  # hit@k for question-style queries

The skill

skills/shared-memory/SKILL.md is symlinked into each agent's skill directory (Claude Code: ~/.claude/skills/shared-memory; Pi: ~/.pi/agent/skills/shared-memory). It documents when to recall, how to write self-contained facts, and that the server reconciles contradictions on add.