agent-memory-mcp

Long-term memory and project-docs search for coding agents, in one local MCP server backed by SQLite.

Your agent remembers why a decision was made, finds the runbook that matches an incident, and notices when what it remembers no longer matches the repo. It works with Claude Code, Codex, Cursor, Gemini CLI, OpenCode, VS Code and Windsurf.

What sets it apart

• Semantic search over memory and docs at once. Typed memories (decisions, facts, procedures, working notes) and your indexed docs, ADRs, changelogs and runbooks are ranked together: embeddings plus keyword matching, recency and source type. Every hit carries its trust data: confidence, freshness, owner, last verification.
• A steward that keeps memory clean. steward_run finds duplicates, contradictions and stale entries and puts anything risky in a review inbox instead of silently rewriting history.
• Drift detection against the repo. drift_scan compares what memory says with the files it refers to and flags entries whose source changed or disappeared.
• Canonical knowledge, confirmed by a human. Raw notes become canonical only through promote_to_canonical; canonical entries rank first and are what the agent leans on. An agent cannot mark its own notes as verified or canonical.
• Local first. One binary, one SQLite file, stdio transport. Embeddings can stay on your machine (Ollama or llama.cpp). An HTTP mode is there when a team wants a shared instance.

Install

brew tap ipiton/tap
brew install agent-memory-mcp

Without Homebrew: go install github.com/ipiton/agent-memory-mcp/cmd/agent-memory-mcp@latest, or a binary from Releases. The server needs one embedding provider (Jina, OpenAI, Ollama or llama.cpp); Installation covers the .env and local-only setups.

Connect your agent

Run this from the repository the agent should remember:

Without --yes the command is a dry run and prints the entry it would add:

$ agent-memory-mcp setup claude-code
Claude Code: would create the file with server "memory" in /Users/you/.claude.json
+ {
+   "args": [
+     "-lc",
+     "cd '/path/to/repo' && MCP_HTTP_MODE=stdio exec '/opt/homebrew/bin/agent-memory-mcp'"
+   ],
+   "command": "/bin/sh",
+   "type": "stdio"
+ }
Dry run: nothing written. Re-run with --yes to apply.

The existing config is kept as it is, other servers and keys included, and a timestamped backup is written next to it. Running the command again changes nothing. If a server with the same name already launches something else, the command stops; --force replaces only its launch command. Other flags: --name, --root, --command. Restart the agent afterwards.

For Claude Code, agent-memory-mcp setup (no agent name) also installs the session hooks that capture knowledge automatically; see Hooks.

What it looks like

Real output from a demo repository with one runbook, one deploy/values.yaml, and one stored decision. Excerpts are trimmed.

"How many replicas should payments-api run, and why?" → recall_memory

1. **Why payments-api runs 4 replicas** (relevance: 0.79)
   Type: Semantic
   Tags: [decision payments capacity]
   Trust: layer=raw source=decision confidence=0.96 freshness=1.00 owner=engineering
   Content: Decision 2026-09-12: payments-api runs 4 replicas, not 2. Two replicas dropped
   requests during the September card-network spike; the HPA reacts too slowly for
   30-second bursts. Source: ./deploy/values.yaml. Revisit when queue-based retry lands.

"How do I roll back a bad payments deploy?" → semantic_search over the indexed docs. The query shares almost no words with the runbook.

1. **payments-api rollback** (relevance: 0.94)
   Path: docs/runbooks/payments-rollback.md
   Source type: runbook
   1. Find the last good revision: `helm history payments-api -n prod`.
   2. Roll back: `helm rollback payments-api <rev> -n prod`.
   3. Verify: `kubectl rollout status deploy/paymen...

"Is what you remember about payments still true?" → drift_scan, after someone changed replicas: 4 to 2 in deploy/values.yaml

Drift Scan: 3 memories scanned, 1 findings

1. [source_changed] Why payments-api runs 4 replicas
   Evidence: File ./deploy/values.yaml modified 2026-10-31 (memory verified 2026-10-31)
   Suggested: verify (confidence: 0.70)

The steward tools (drift_scan, steward_run, the review inbox) switch on by themselves only in HTTP mode. For an agent connected through setup, add MCP_STEWARD_ENABLED=true to the project's .env. See Stewardship.

How it compares

A comparison with other memory servers, measured on a public corpus, is in preparation.

Documentation

Development

# Build
make build

# Run
make run

# Test
make test

# Full quality gate (lint + tests + smoke)
make quality-gates

For repo layout, code style, and PR conventions see docs/CONTRIBUTING.md.

License

MIT