Agent Memory

agent-memory

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

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

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.6.1 — the Swarm Audit Hardening & Metamorphic Rebase release: bridges durable memory with verifiable autonomous execution and strict fail-closed security invariants:

• Astra Pro Audit Hardening (AM-001..AM-008) — Category-enforced approval routing (DecideRoutingWithCategory), whole-file pre-state CAS (proposal.PreHashes), polarity/negation qualifier preservation in Jaccard dedup (criticalQualifiers), idempotent pure read-only fetch_context, and canonical 3-way merge deletion semantics.
• Metamorphic Rebase & Drift Detection (`internal/memory/rebase.go`) — Detects whole-file pre-hash drift during rebase, preventing silent clobber when adjacent sections are concurrently edited, verified by metamorphic composition tests.
• Control-Plane Manifest Isolation — Enforces fail-closed protection of .agent-memory/meta/manifest.yaml against direct modification, symlink bypass, or path traversal attacks.
• RFC 8785 (JCS) Determinism (`internal/vtp`) — Strict JSON Canonicalization Scheme compliance passing all 26 official RFC 8785 Appendix B test vectors, ECMAScript float formatting (1e+21), lone surrogate rejection, and recursive UTF-8 validation.
• Fail-Closed Cross-Process SQLite NonceStore (`internal/memory/nonce.go`) — Persistent repo-scoped store using the withDB pattern to eliminate Windows file descriptor locks, providing zero-drift atomic validation and auto-sweeping expired nonces.
• Two-Phase Staging & Compound Rollback (`internal/memory/staging.go`) — Strict path traversal sanitization (ValidateStagingID, agentfs.ValidateMemoryPath), symlink containment, and atomic multi-file rollback reporting RollbackIncomplete compound errors on partial failure.
• VTP-1 Strict Assertion Identification & Dual-Oracle Settlement (`internal/vtp`) — Mandatory identifiable AssertionResults matching declared assertion IDs, verifier key binding validation, and Workpool/0 Clause B disjoint seat enforcement.

It builds on 0.6.0 (anti-ornamental SAR-008 grounding nonces, SAR-007 byte preservation), 0.5.4 (VTP-1 initial protocol engine), 0.5.0 (federation, referenced landscape stores), and 0.4 (section merge driver).

See CHANGELOG.md for the full changelist.

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

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

1. Persist what you found via memory.propose_update, choosing the intent per kind:

• update_conventions → conventions.md (build/test/style/workflow)
• refresh_module → modules/ .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 " " 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 s