agent-memory

<p align="center"> <img src="docs/assets/banner.svg" alt="agent-memory — git-native memory for AI coding agents" width="640"> </p>

Local, git-native project memory for AI coding agents. One MCP call in, structured memory updates out — current task state, decisions, conventions, pitfalls, per-module facts. Branch-aware. Secret-safe. Byte-preserving. No cloud, no vector DB — Markdown is the source of truth and git is the sync. Three MCP tools + a full CLI.

Why it's different: memory is plain Markdown committed to your repo, so you can read and git diff it; durable changes stage for human review (review --diff → apply) instead of landing silently; and secrets/PII are scanned out before anything is written. See ROADMAP.md for where this is headed (system-level / multi-repo memory).

Demo

<p align="center"> <img src="docs/demo/demo.gif" alt="agent-memory: an agent proposes a decision, it stages, you review the diff and apply, a later fetch surfaces it" width="820"> </p>

An agent records a durable decision; it stages for review; you see the exact diff, apply it, and a later fetch surfaces it — local, git-native, reviewable, secret-safe. The clip is reproducible: docs/demo/demo.sh is the runnable flow and docs/demo/demo.tape renders the gif with vhs — see docs/demo/.

How it compares

| Capability | AGENTS.md / CLAUDE.md | Vendor memory (e.g. Claude) | Vector / DB memory (mem0, Zep) | agent-memory | |---|---|---|---|---| | Plain-text, git-versioned source of truth | ✓ flat file | ✗ vendor-managed | ✗ DB / cloud | ✓ Markdown in your repo | | Structured, section-level updates | ✗ | ✗ | ~ | ✓ | | Human review gate (see the diff first) | ✗ free edit | ✗ | ✗ | ✓ stage → review --diff → apply | | Vendor-neutral (MCP — any agent) | ~ broad convention | ✗ one vendor | ~ varies | ✓ Claude · Cursor · Codex · Gemini | | Secret / PII scan on write | ✗ | ✗ | ~ varies | ✓ | | Team merge for concurrent edits | ✗ text conflicts | ✗ | ✗ | ✓ section merge driver | | Runs fully local (no cloud) | ✓ | ✗ | ~ varies | ✓ |

These are general characterizations and the tools evolve fast — see something inaccurate? Open an issue and I'll fix the row. agent-memory is complementary to instruction files like AGENTS.md/CLAUDE.md (it even installs one): those say how to behave; agent-memory is the durable, searchable, reviewed knowledge behind it.

Status

Release 0.5 — the federation release: a repo can now reference shared, git-pinned, read-only "landscape" stores, so an agent designing a cross-service feature sees the surrounding system map — blended into fetch_context with per-store-fair ranking, provenance, and a trust boundary. Built behind an opt-in invariant: with no stores declared, behaviour is byte-for-byte the single-repo path.

Federation (PR1–PR6):

• Store-format versioning — a store_format_version with a fail-closed load guard, so a too-new store is never misread.
• Referenced stores — a manifest stores block + a committed, go.sum-style meta/stores.lock pinning each store to an exact commit.
• agent-memory sync — clone → validate → sandbox-copy (symlink-safe) → secret/PII scan → atomic swap into the gitignored cache.
• Store-keyed index — one FTS5 index holds local + every cached store (SearchPerStore), migrated by rebuild-on-version-bump.
• Multi-store fetch — per-store-fair merge + priority_multiplier + cross-store dedup + provenance / trust-boundary rendering.
• Federation eval — a deterministic, CI-guarded multi-store retrieval eval (recall@5 with store-origin correctness; ranking + starvation guards).

It builds on 0.4 (the team-and-launch release: section-aware git merge driver, an offline retrieval-quality eval at recall@5 0.98, Apache-2.0 open-source packaging) and the unchanged Core Contract from v0.1.0 (MCP server, structured operations, drift-checked staging, secret scanning) — every release since has been additive. The behavioural eval harness remains the main deferred item — see ROADMAP.md.

See CHANGELOG.md for the full changelist.

| Document | Purpose | |---|---| | ROADMAP.md | Where the project is going, principles, and non-goals. | | CHANGELOG.md | Per-release feature list and known limitations. | | Design Doc v0.4.1 | Canonical design this binary implements. | | Implementation Plan | Historical MVP build log (M0–M8); see ROADMAP for what's next. | | Retrieval eval | Offline recall/MRR/nDCG benchmark of fetch (method + numbers). | | Patterns | Reusable design patterns documented per subsystem. | | Spikes | Pre-M1 spike outcomes (byte-preserving engine, MCP SDK, flock, FTS5). |

Quick start

Install — download a prebuilt binary (recommended): grab the archive for your OS/arch from the latest release, extract it, and put agent-memory on your PATH. No toolchain needed.

# npx (no Go, no manual download): fetches the verified release binary on
# first run and caches it — also usable straight from an MCP client config.
npx -y @xchucx/agent-memory --help

# Go toolchain alternative (Go 1.25+)
go install github.com/xChuCx/agent-memory/cmd/agent-memory@latest

# from source
go build -o agent-memory ./cmd/agent-memory

Homebrew, Scoop, and winget packages are planned. agent-memory is also listed on the MCP Registry.

Then, inside the repo you want to give a memory:

# Scaffold .agent-memory/ in a repo
agent-memory init --name my-project

# Install the Claude Code skill + register the project MCP server
# (writes .claude/skills/agent-memory/SKILL.md and merges .mcp.json)
agent-memory install claude

# Verify (prints the release tag, the go-install version, or dev+vcs locally)
agent-memory version

# Read context
agent-memory fetch                # bootstrap pack
agent-memory fetch "auth"         # FTS query

# Start MCP server (your agent spawns this automatically once configured)
agent-memory mcp

install claude registers the MCP server for you: it merges a project-scoped .mcp.json at the repo root that runs agent-memory mcp --root ${CLAUDE_PROJECT_DIR:-.}. Claude Code expands CLAUDE_PROJECT_DIR to the repo at spawn, so the server always serves this repo — the config is portable across clones and (by Claude Code's scope precedence, local > project > user) overrides any stray user-scoped server. Commit .mcp.json so your team shares it.

⚠️ Do not register a single user-scoped server with a hardcoded root (claude mcp add -s user agent-memory -- agent-memory mcp --root /some/repo): it serves every project from that one repo, so memory you write in project B silently lands in project A. Per-project registration (what install writes) is the correct model; agent-memory doctor flags a mis-rooted registration.

The server resolves its repo from --root, then $CLAUDE_PROJECT_DIR, then the working directory. Other runtimes (Cursor, Gemini CLI, anything reading AGENTS.md) use the same server — install their adapter (see below).

Adopt on an existing project

init scaffolds empty memory. To seed it from a real codebase, let your coding agent do the analysis — that's the whole point. After init + install <adapter> + registering the MCP server (above), restart the agent so the memory.* tools load, then paste the prompt below.

What happens: the agent reads the repo and calls memory.propose_update. Working notes and pitfalls apply immediately; durable categories (conventions, decisions, modules) stage for your review — inspect each with agent-memory review --diff and land it with agent-memory apply (or reject). Nothing durable is written without your approval.

You now have agent-memory MCP tools (memory.fetch_context,
memory.propose_update, memory.status) backed by this repository's
.agent-memory/ store. Bootstrap the project's memory from the codebase.

1. Call memory.fetch_context with an empty query to see the current
   (mostly empty) state and the conventions/decisions/pitfalls/modules
   layout.

2. Analyze THIS repository — read the build files, CI config, entry
   points, and the main packages/modules. Identify:
   - build / test / run / lint commands and the toolchain;
   - conventions: code style, branching, commit rules, review practices;
   - architecture: the major modules/components and what each is for;
   - durable decisions: notable choices and WHY (only ones that are real
     and stable — not speculation);
   - pitfalls: footguns, sharp edges, "don't do X because Y" you can infer
     from the code, tests, or docs.

3. Persist what you found via memory.propose_update, choosing the intent
   per kind:
   - update_conventions  → conventions.md (build/test/style/workflow)
   - refresh_module      → modules/<name>.md (one per major component)
   - record_decision     → decisions.md (Date / Status / Confidence +
                           sources; type ∈ file|test|user, NOT external)
   - add_pitfall         → pitfalls.md
   - update_shared       → local/current.shared.md (a short "current
                           state / where things stand" summary)

Rules:
- Cite provenance: pass sources as file references you actually read
  (e.g. {"type":"file","ref":"internal/auth/session.go"}). Use
  confidence=confirmed for facts from code, inferred for deductions.
- Every section needs a unique "<!-- @id: ... -->" anchor; keep entries
  concise — this is working knowledge, not a wiki. Decisions need
  **Date**, **Status** (active|superseded|deprecated|proposed), and
  **Confidence** fields.
- NEVER put secrets, tokens, or credentials in memory (the server will
  reject them anyway).
- Work in a few focused passes (conventions + architecture first, then
  modules, then decisions/pitfalls). Report what you proposed and what
  staged for review.

No MCP server handy? The agent (or you) can use the CLI instead — same validation/secret-scan/routing pipeline:

agent-memory propose --intent update_conventions --op append_section \
  --path conventions.md --heading "Build & test" --heading-level 2 \
  --source file:Makefile --confidence confirmed \
  --content-file - <<'MD'
## Build & test
<!-- @id: build-test -->
Run `go build ./...` and `go test ./...`. ...
MD
# add --apply to land it immediately (you are the reviewer);
# or omit it and review the staged proposal with `review --diff` + `apply`.

Build

Requires Go 1.25+ (the MCP SDK transitively requires it).

go build -o agent-memory ./cmd/agent-memory   # binary
go