agent-memory

# agent-memory

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

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![CI](https://github.com/xChuCx/agent-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/xChuCx/agent-memory/actions/workflows/ci.yml)
[![Go](https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go&logoColor=white)](go.mod)
[![MCP](https://img.shields.io/badge/MCP-server-1f6feb)](#mcp-tools)
[![retrieval recall@5](https://img.shields.io/badge/retrieval_recall%405-0.98-2ea44f)](docs/eval/retrieval.md)
[![Claude Code](https://img.shields.io/badge/Claude_Code-compatible-8b5cf6)](#agent-runtime-adapters)
[![Cursor](https://img.shields.io/badge/Cursor-compatible-0ea5e9)](#agent-runtime-adapters)
[![AGENTS.md / Codex](https://img.shields.io/badge/AGENTS.md_·_Codex-compatible-111827)](#agent-runtime-adapters)
[![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-compatible-4285F4)](#agent-runtime-adapters)

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](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`](docs/demo/demo.sh) is the runnable flow and
[`docs/demo/demo.tape`](docs/demo/demo.tape) renders the gif with
[`vhs`](https://github.com/charmbracelet/vhs) — see [docs/demo/](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 | **✓** |
| Verifiable Task Protocol (VTP-1) & Machine Receipts | ✗ | ✗ | ✗ | **✓ 5-phase cryptographic lifecycle + Clause B disjoint seat** |

These are general characterizations and the tools evolve fast — see something
inaccurate? [Open an issue](https://github.com/xChuCx/agent-memory/issues) 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.4** — the **Verifiable Task Protocol (VTP-1) & Swarm Consensus** release:
bridges durable memory with verifiable autonomous multi-agent execution. Agents in a swarm
no longer rely on unverified claims; work is proven by machine-executable receipts,
CRLF-invariant SHA-256 Merkle roots, and independent dual-oracle verification.

- **VTP-1 Protocol Engine (`internal/vtp`)** — 5-phase contract lifecycle (`TASK-SPEC`,
  `TASK-CLAIM`, `TASK-RECEIPT`, `TASK-VERIFY`, `TASK-SETTLE`).
- **SAR-002 LF Normalization** — Cross-platform byte-level digest parity across Windows NTFS,
  macOS, and Linux runners (`\r\n` stripped before hashing).
- **Workpool/0 Clause B Disjoint Seat Enforcement** — Verifications fail closed unless
  executed on an isolated seat physically or logically distinct from the task worker.
- **`agent-memory vtp` CLI** — `digest`, `verify`, and `settle` subcommands built into
  the main binary.
- **`agent-memory digest` (0.5.2)** — Deterministic SHA-256 Merkle root of active memory
  for cryptographic state attestation.

It builds on **0.5.0** (the **federation** release: referenced landscape stores, `meta/stores.lock`,
`agent-memory sync`, multi-store FTS5 search) and **0.4** (team-and-launch release: section-aware git merge
driver, offline retrieval-quality eval at recall@5 0.98, Apache-2.0 open-source packaging).

See [CHANGELOG.md](CHANGELOG.md) for the full changelist.

| Document | Purpose |
|---|---|
| [ROADMAP.md](ROADMAP.md) | Where the project is going, principles, and non-goals. |
| [CHANGELOG.md](CHANGELOG.md) | Per-release feature list and known limitations. |
| [Design Doc v0.4.1](agent-memory-design-doc-v0.4.1.md) | Canonical design this binary implements. |
| [Implementation Plan](agent-memory-implementation-plan.md) | Historical MVP build log (M0–M8); see ROADMAP for what's next. |
| [Retrieval eval](docs/eval/retrieval.md) | Offline recall/MRR/nDCG benchmark of `fetch` (method + numbers). |
| [Patterns](docs/patterns/) | Reusable design patterns documented per subsystem. |
| [Spikes](docs/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](https://github.com/xChuCx/agent-memory/releases/latest),
extract it, and put `agent-memory` on your `PATH`. No toolchain needed.

```bash
# 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](https://registry.modelcontextprotocol.io/).

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

```bash
# 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.

````text
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 (bu