\n\n[](LICENSE)\n[](https://github.com/xChuCx/agent-memory/actions/workflows/ci.yml)\n[](go.mod)\n[](#mcp-tools)\n[](docs/eval/retrieval.md)\n[](#agent-runtime-adapters)\n[](#agent-runtime-adapters)\n[](#agent-runtime-adapters)\n[](#agent-runtime-adapters)\n\nLocal, **git-native** project memory for AI coding agents. One MCP call in,\nstructured memory updates out — current task state, decisions, conventions,\npitfalls, per-module facts. Branch-aware. Secret-safe. Byte-preserving.\n**No cloud, no vector DB** — Markdown is the source of truth and git is the\nsync. Three MCP tools + a full CLI.\n\nWhy it's different: memory is **plain Markdown committed to your repo**, so\nyou can read and `git diff` it; durable changes **stage for human review**\n(`review --diff` → `apply`) instead of landing silently; and secrets/PII are\n**scanned out** before anything is written. See [ROADMAP.md](ROADMAP.md) for\nwhere this is headed (system-level / multi-repo memory).\n\n## Demo\n\n
\n \n
\n\nAn agent records a durable decision; it **stages** for review; you see the\nexact **diff**, **apply** it, and a later **`fetch`** surfaces it — local,\ngit-native, reviewable, secret-safe. The clip is reproducible:\n[`docs/demo/demo.sh`](docs/demo/demo.sh) is the runnable flow and\n[`docs/demo/demo.tape`](docs/demo/demo.tape) renders the gif with\n[`vhs`](https://github.com/charmbracelet/vhs) — see [docs/demo/](docs/demo/).\n\n## How it compares\n\n| Capability | AGENTS.md / CLAUDE.md | Vendor memory (e.g. Claude) | Vector / DB memory (mem0, Zep) | **agent-memory** |\n|---|---|---|---|---|\n| Plain-text, git-versioned source of truth | ✓ flat file | ✗ vendor-managed | ✗ DB / cloud | **✓ Markdown in your repo** |\n| Structured, section-level updates | ✗ | ✗ | ~ | **✓** |\n| Human review gate (see the diff first) | ✗ free edit | ✗ | ✗ | **✓ stage → `review --diff` → apply** |\n| Vendor-neutral (MCP — any agent) | ~ broad convention | ✗ one vendor | ~ varies | **✓ Claude · Cursor · Codex · Gemini** |\n| Secret / PII scan on write | ✗ | ✗ | ~ varies | **✓** |\n| Team merge for concurrent edits | ✗ text conflicts | ✗ | ✗ | **✓ section merge driver** |\n| Runs fully local (no cloud) | ✓ | ✗ | ~ varies | **✓** |\n| Verifiable Task Protocol (VTP-1) & Machine Receipts | ✗ | ✗ | ✗ | **✓ 5-phase cryptographic lifecycle + Clause B disjoint seat** |\n\nThese are general characterizations and the tools evolve fast — see something\ninaccurate? [Open an issue](https://github.com/xChuCx/agent-memory/issues) and\nI'll fix the row. agent-memory is complementary to instruction files like\n`AGENTS.md`/`CLAUDE.md` (it even installs one): those say *how to behave*;\nagent-memory is the *durable, searchable, reviewed knowledge* behind it.\n\n## Status\n\n**Release 0.5.4** — the **Verifiable Task Protocol (VTP-1) & Swarm Consensus** release:\nbridges durable memory with verifiable autonomous multi-agent execution. Agents in a swarm\nno longer rely on unverified claims; work is proven by machine-executable receipts,\nCRLF-invariant SHA-256 Merkle roots, and independent dual-oracle verification.\n\n- **VTP-1 Protocol Engine (`internal/vtp`)** — 5-phase contract lifecycle (`TASK-SPEC`,\n `TASK-CLAIM`, `TASK-RECEIPT`, `TASK-VERIFY`, `TASK-SETTLE`).\n- **SAR-002 LF Normalization** — Cross-platform byte-level digest parity across Windows NTFS,\n macOS, and Linux runners (`\\r\\n` stripped before hashing).\n- **Workpool/0 Clause B Disjoint Seat Enforcement** — Verifications fail closed unless\n executed on an isolated seat physically or logically distinct from the task worker.\n- **`agent-memory vtp` CLI** — `digest`, `verify`, and `settle` subcommands built into\n the main binary.\n- **`agent-memory digest` (0.5.2)** — Deterministic SHA-256 Merkle root of active memory\n for cryptographic state attestation.\n\nIt builds on **0.5.0** (the **federation** release: referenced landscape stores, `meta/stores.lock`,\n`agent-memory sync`, multi-store FTS5 search) and **0.4** (team-and-launch release: section-aware git merge\ndriver, offline retrieval-quality eval at recall@5 0.98, Apache-2.0 open-source packaging).\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full changelist.\n\n| Document | Purpose |\n|---|---|\n| [ROADMAP.md](ROADMAP.md) | Where the project is going, principles, and non-goals. |\n| [CHANGELOG.md](CHANGELOG.md) | Per-release feature list and known limitations. |\n| [Design Doc v0.4.1](agent-memory-design-doc-v0.4.1.md) | Canonical design this binary implements. |\n| [Implementation Plan](agent-memory-implementation-plan.md) | Historical MVP build log (M0–M8); see ROADMAP for what's next. |\n| [Retrieval eval](docs/eval/retrieval.md) | Offline recall/MRR/nDCG benchmark of `fetch` (method + numbers). |\n| [Patterns](docs/patterns/) | Reusable design patterns documented per subsystem. |\n| [Spikes](docs/spikes/) | Pre-M1 spike outcomes (byte-preserving engine, MCP SDK, flock, FTS5). |\n\n## Quick start\n\n**Install — download a prebuilt binary** (recommended): grab the archive\nfor your OS/arch from the [latest release](https://github.com/xChuCx/agent-memory/releases/latest),\nextract it, and put `agent-memory` on your `PATH`. No toolchain needed.\n\n```bash\n# npx (no Go, no manual download): fetches the verified release binary on\n# first run and caches it — also usable straight from an MCP client config.\nnpx -y @xchucx/agent-memory --help\n\n# Go toolchain alternative (Go 1.25+)\ngo install github.com/xChuCx/agent-memory/cmd/agent-memory@latest\n\n# from source\ngo build -o agent-memory ./cmd/agent-memory\n```\n\nHomebrew, Scoop, and winget packages are planned. agent-memory is also\nlisted on the [MCP Registry](https://registry.modelcontextprotocol.io/).\n\nThen, inside the repo you want to give a memory:\n\n```bash\n# Scaffold .agent-memory/ in a repo\nagent-memory init --name my-project\n\n# Install the Claude Code skill + register the project MCP server\n# (writes .claude/skills/agent-memory/SKILL.md and merges .mcp.json)\nagent-memory install claude\n\n# Verify (prints the release tag, the go-install version, or dev+vcs locally)\nagent-memory version\n\n# Read context\nagent-memory fetch # bootstrap pack\nagent-memory fetch \"auth\" # FTS query\n\n# Start MCP server (your agent spawns this automatically once configured)\nagent-memory mcp\n```\n\n`install claude` registers the MCP server for you: it merges a project-scoped\n`.mcp.json` at the repo root that runs `agent-memory mcp --root ${CLAUDE_PROJECT_DIR:-.}`.\nClaude Code expands `CLAUDE_PROJECT_DIR` to the repo at spawn, so the server\nalways serves **this** repo — the config is portable across clones and (by\nClaude Code's scope precedence, local > project > user) overrides any stray\nuser-scoped server. Commit `.mcp.json` so your team shares it.\n\n> ⚠️ **Do not** register a single **user-scoped** server with a hardcoded root\n> (`claude mcp add -s user agent-memory -- agent-memory mcp --root /some/repo`):\n> it serves *every* project from that one repo, so memory you write in project B\n> silently lands in project A. Per-project registration (what `install` writes)\n> is the correct model; `agent-memory doctor` flags a mis-rooted registration.\n\nThe server resolves its repo from `--root`, then `$CLAUDE_PROJECT_DIR`, then the\nworking directory. Other runtimes (Cursor, Gemini CLI, anything reading\n`AGENTS.md`) use the same server — install their adapter (see below).\n\n## Adopt on an existing project\n\n`init` scaffolds empty memory. To seed it from a real codebase, let your\ncoding agent do the analysis — that's the whole point. After `init` +\n`install ` + registering the MCP server (above), **restart the\nagent** so the `memory.*` tools load, then paste the prompt below.\n\nWhat happens: the agent reads the repo and calls `memory.propose_update`.\nWorking notes and pitfalls apply immediately; durable categories\n(conventions, decisions, modules) **stage for your review** — inspect each\nwith `agent-memory review --diff` and land it with `agent-memory apply`\n(or `reject`). Nothing durable is written without your approval.\n\n````text\nYou now have agent-memory MCP tools (memory.fetch_context,\nmemory.propose_update, memory.status) backed by this repository's\n.agent-memory/ store. Bootstrap the project's memory from the codebase.\n\n1. Call memory.fetch_context with an empty query to see the current\n (mostly empty) state and the conventions/decisions/pitfalls/modules\n layout.\n\n2. Analyze THIS repository — read the build files, CI config, entry\n points, and the main packages/modules. Identify:\n - build / test / run / lint commands and the toolchain;\n - conventions: code style, branching, commit rules, review practices;\n - architecture: the major modules/components and what each is for;\n - durable decisions: notable choices and WHY (only ones that are real\n and stable — not speculation);\n - pitfalls: footguns, sharp edges, \"don't do X because Y\" you can infer\n from the code, tests, or docs.\n\n3. Persist what you found via memory.propose_update, choosing the intent\n per kind:\n - update_conventions → conventions.md (build/test/style/workflow)\n - refresh_module → modules/.md (one per major component)\n - record_decision → decisions.md (Date / Status / Confidence +\n sources; type ∈ file|test|user, NOT external)\n - add_pitfall → pitfalls.md\n - update_shared → local/current.shared.md (a short \"current\n state / where things stand\" summary)\n\nRules:\n- Cite provenance: pass sources as file references you actually read\n (e.g. {\"type\":\"file\",\"ref\":\"internal/auth/session.go\"}). Use\n confidence=confirmed for facts from code, inferred for deductions.\n- Every section needs a unique \"\" anchor; keep entries\n concise — this is working knowledge, not a wiki. Decisions need\n **Date**, **Status** (active|superseded|deprecated|proposed), and\n **Confidence** fields.\n- NEVER put secrets, tokens, or credentials in memory (the server will\n reject them anyway).\n- Work in a few focused passes (conventions + architecture first, then\n modules, then decisions/pitfalls). Report what you proposed and what\n staged for review.\n````\n\nNo MCP server handy? The agent (or you) can use the CLI instead — same\nvalidation/secret-scan/routing pipeline:\n\n```bash\nagent-memory propose --intent update_conventions --op append_section \\\n --path conventions.md --heading \"Build & test\" --heading-level 2 \\\n --source file:Makefile --confidence confirmed \\\n --content-file - <<'MD'\n## Build & test\n\nRun `go build ./...` and `go test ./...`. ...\nMD\n# add --apply to land it immediately (you are the reviewer);\n# or omit it and review the staged proposal with `review --diff` + `apply`.\n```\n\n## Build\n\nRequires Go 1.25+ (the MCP SDK transitively requires it).\n\n```bash\ngo build -o agent-memory ./cmd/agent-memory # binary\ngo test ./... # unit + integration tests\ngo test -tags=e2e ./internal/e2e/... # end-to-end smoke (linux/macos)\ngo test -race ./internal/... # race detector\n```\n\n`make` targets are equivalent to the `go` commands above; see the\n`Makefile` if you prefer that style.\n\n## CLI\n\n```bash\nagent-memory init [--root DIR] [--name NAME] [--force]\n # Create the .agent-memory/ scaffold.\n\nagent-memory status [--root DIR] [--json]\n # Project state: version, file counts per category, lock metadata.\n\nagent-memory doctor [--root DIR]\n # Diagnostic layout checks. Advisory; exits 0 even with findings.\n\nagent-memory digest [--root DIR] [--verify SHA256] [--json]\n # Compute or verify deterministic SHA-256 Merkle root of active memory.\n # CRLF-normalized; cryptographic receipt for VTP-1 or swarm audit.\n\nagent-memory fetch [QUERY] [--scope X,Y] [--budget N]\n [--exclude-archive] [--json] [--root DIR]\n # Return a budgeted Markdown context pack.\n\nagent-memory mcp [--root DIR]\n # Start the MCP server (stdio). Exposes memory.fetch_context and\n # memory.propose_update.\n\nagent-memory propose --intent INTENT --op OP --path PATH [op flags...]\n [--content STR | --content-file FILE|-] [--source type:ref]\n [--confidence C] [--apply] [--from-json FILE|-] [--json]\n # Create a proposal WITHOUT an MCP server, through the same\n # validate / secret-scan / route pipeline. --from-json takes a full\n # multi-op ProposeRequest; --apply immediately lands a result that\n # would otherwise stage (you are the reviewer).\n\nagent-memory review [STAGING_ID] [--diff] [--show] [--json] [--root DIR]\n # List staged proposals or inspect one. --diff shows a unified diff\n # of each staged file vs the current on-disk version.\n\nagent-memory apply STAGING_ID [--json] [--root DIR]\n # Re-validate drift and apply a staged proposal.\n\nagent-memory reject STAGING_ID [--json] [--root DIR]\n # Discard a staged proposal.\n\nagent-memory rebase STAGING_ID [--force] [--json] [--root DIR]\n # Re-plan a staged proposal against the current disk state\n # after target_drift. --force is required for soft drifts\n # (acknowledges accepting the new base as planning input).\n\n# review / apply / reject / rebase accept a full STAGING_ID, any unique\n# prefix (Git-style), or --latest for the most recently staged proposal:\n# agent-memory apply 20260527 # unique prefix\n# agent-memory apply --latest # newest staged proposal\n\nagent-memory install [--user-global] [--force] [--json]\n # Materialise agent-runtime adapter assets.\n # Supported: claude, cursor, agents, gemini.\n\nagent-memory merge-driver --install [--root DIR]\n # Register the section-aware git merge driver so a team's concurrent\n # edits to .agent-memory/ files union by @id instead of conflicting.\n # Run once per clone. (git invokes the bare `merge-driver %O %A %B %P`\n # form itself during a merge.)\n\nagent-memory store add --name NAME --source URL|PATH [--revision REV]\n [--path DIR] [--priority-multiplier F] [--root DIR]\nagent-memory store list [--json] [--root DIR]\nagent-memory store rm --name NAME [--root DIR]\n # Federation: declare / list / remove referenced \"landscape\" stores\n # (a shared platform/architecture-memory repo) in the manifest.\n\nagent-memory sync [--update] [--root DIR]\n # Materialise each referenced store into the gitignored cache and pin it\n # in meta/stores.lock (committed). --update moves a pin forward.\n\nagent-memory rebuild-index [--root DIR] [--clobber] [--no-assign-ids] [--json]\n # Recreate the FTS5 shadow index from canonical Markdown files.\n # Use for SQLite corruption, schema changes, or after manual .md edits.\n\nagent-memory sweep [--root DIR] [--ttl DURATION] [--dry-run] [--json]\n # Remove staged proposals past the manifest's staging.ttl_seconds.\n # Each removal also writes a ttl_expired entry to meta/rejection-log.jsonl.\n\nagent-memory vtp digest [--json]\n # Compute canonical SAR-002 LF-normalized SHA-256 digest of a target file.\n\nagent-memory vtp verify --receipt FILE [--spec FILE] [--stdout FILE]\n [--diff FILE] [--exit-code N] [--verifier ID]\n [--disjoint] [--json]\n # Verify a TaskReceipt execution proof against stdout/diff digests, exit code,\n # and enforce Workpool/0 Clause B (disjoint seat isolation).\n\nagent-memory vtp settle --verify FILE [--spec FILE] --payer ID --payee ID\n --seq N [--json]\n # Emit a canonical TaskSettle artifact from a passed verification, enforcing\n # that Clause B disjoint verification was satisfied.\n\nagent-memory version\n # Print binary version and exit.\n```\n\n## MCP tools\n\nExposed by `agent-memory mcp` over stdio JSON-RPC:\n\n| Tool | Purpose |\n|------|---------|\n| `memory.fetch_context` | Read a budgeted Markdown context pack. |\n| `memory.propose_update` | Submit structured edits (apply or stage). |\n| `memory.status` | Report memory health: file counts, staged proposals (with drift), security/git/lock posture. |\n\n## Federated memory (landscape stores)\n\nA repository's `.agent-memory/` knows only itself. **Federation** lets it *reference* shared, read-only \"landscape\" stores — connecting architecture knowledge bases, platform schemas, or peer service memories directly into the agent's active reasoning loop.\n\nThis is **fundamentally different from pulling in a static wiki**:\n- **Zero-Waste Engineering (Peer Solution Discovery):** Instead of an agent reinventing complex distributed mechanisms from scratch (e.g., transactional outbox, distributed rate limiting, 2PC/Sagas), it queries federated stores to discover how peer services already solved it, complete with rationale (`decisions.md`) and known production traps (`pitfalls.md`).\n- **Context Beyond the Public API:** APIs (OpenAPI, gRPC) declare structural syntax, but hide operational physics: database isolation levels, lock contention patterns, deduplication windows, and backpressure behavior. Federated memory surfaces these hidden operational boundaries.\n- **Safe Cross-Service PRs:** When an agent must modify an upstream or adjacent service, federated memory provides the local conventions and invariants needed to propose safe, non-breaking contributions.\n\n### Quickstart with `arch-wiki`\n\nConnect the public, canonical Architecture Wiki ([`https://github.com/xChuCx/arch-wiki`](https://github.com/xChuCx/arch-wiki) — 165 production-grade technical articles across the 4-layer taxonomy L1–L4):\n\n```bash\n# 1. Declare the landscape store (edits .agent-memory/meta/manifest.yaml)\nagent-memory store add --name arch-wiki --source https://github.com/xChuCx/arch-wiki\n\n# 2. Fetch, sandbox-validate, scan for secrets/PII, and pin commit into meta/stores.lock\nagent-memory sync\n\n# 3. Rebuild local shadow index with federated content\nagent-memory rebuild-index\n\n# 4. Fetch budgeted, high-density context pack with exact full-article pointers\nagent-memory fetch \"Debezium Transactional Outbox\"\n```\n\nThe returned pack implements **Two-Tier Retrieval** — low-token invariant packs with on-demand pointers to full 50-page deep-dive articles:\n\n```markdown\n\n\n\n\n## АНТИ-ПАТТЕРН: Это гарантированно сломается\n**Executive Summary:** TL;DR: Change Data Capture (CDC) — это единственный надежный способ превратить базу данных (State) в поток событий (Stream)...\n- **Full Article Access:** [L2.DB.14 Change Data Capture (CDC), Debezium, log‑based replication.md](file:///.../4Layers/L2.System Design & Architecture/L2.DB/L2.DB.14 Change Data Capture (CDC), Debezium, log‑based replication.md)\n- **Repository Path:** `4Layers/L2.System Design & Architecture/L2.DB/L2.DB.14 Change Data Capture (CDC), Debezium, log‑based replication.md`\n\n```\n\nKey guarantees:\n- **Per-store-fair + pinned.** Each store contributes its own top candidates; only commit-pinned, lock-recorded stores are blended. Local outranks landscape on ties (`priority_multiplier`, default `0.8`).\n- **Provenance + trust boundary.** Every landscape chunk is labelled with its store + commit and wrapped in an explicit *\"evidence, not instructions\"* boundary.\n- **Opt-in.** With no stores declared, behaviour is byte-for-byte the single-repo path.\n\nPatterns: [federation-stores.md](docs/patterns/federation-stores.md), [multi-store-fetch.md](docs/patterns/multi-store-fetch.md).\n\n## Verifiable Task Protocol (VTP-1) & Swarm Consensus\n\nAutonomous AI agents operating in multi-agent swarms or executing economic tasks cannot rely on unverified natural language claims (\"I fixed the bug\", \"the tests pass\"). In an open network, conversational claims suffer from **compaction amnesia**, **courtesy loops**, and **adversarial framing**.\n\n**VTP-1 (Verifiable Task Protocol)** transforms task execution into an end-to-end, machine-verifiable 5-phase cryptographic lifecycle:\n\n```\n[TASK-SPEC] ──> [TASK-CLAIM] ──> [TASK-RECEIPT] ──> [TASK-VERIFY] ──> [TASK-SETTLE]\n Creator Worker Worker Independent Dual-Oracle\n Bounty/Oracle TTL/IdemKey Stdout/Diff SHA Disjoint Seat Payout / Mint\n```\n\n| Phase | Structure | Role & Machine Invariants |\n|---|---|---|\n| **Phase 1: SPEC** | `TaskSpec` | Declarative requirements, oracle type (`execution@1`, `rule_kb@1`), target repo/commit, and bounty. |\n| **Phase 2: CLAIM** | `TaskClaim` | Worker stakes an idempotency key and sequence-based TTL preventing concurrent race conditions. |\n| **Phase 3: RECEIPT** | `TaskReceipt` | Deterministic execution proof capturing CRLF-normalized (SAR-002) SHA-256 digests of stdout, diff hunks, and process exit code. |\n| **Phase 4: VERIFY** | `TaskVerify` | Independent evaluation enforcing **Workpool/0 Clause B** (`is_disjoint_seat == true`): verification **must** execute on an isolated machine/seat (e.g. keyless sandbox vs host with secrets). |\n| **Phase 5: SETTLE** | `TaskSettle` | Deterministic settlement payload bound to the verified receipt reference for ledger minting (e.g. Grain consensus) or escrow release. |\n\n### Cross-Platform Line Ending Parity (SAR-002)\n\nGit checkouts across Windows (CRLF) and Linux/macOS (LF) can produce divergent hashes for identical textual content. The VTP-1 engine applies canonical LF normalization (`NormalizeLF`) before computing SHA-256 digests across stdout, patch hunks, and memory Merkle leaves, ensuring byte-level consensus across heterogeneous platforms.\n\n### CLI Workflow for Autonomous Agents\n\n```bash\n# 1. Compute canonical normalized digest for an output log or diff patch\nagent-memory vtp digest ./artifacts/stdout.log --json\n\n# 2. Verify a worker's TaskReceipt against live execution output\nagent-memory vtp verify --receipt receipt.json --spec spec.json \\\n --stdout stdout.log --diff patch.diff \\\n --verifier @orca-agent --disjoint --json > verify.json\n\n# 3. Settle verified task into a settlement artifact (fails closed if Clause B violated)\nagent-memory vtp settle --verify verify.json --spec spec.json \\\n --payer @creator --payee @worker --seq 14500 --json > settle.json\n```\n\n## Evidence (measured)\n\nThree layers, honest about scope — **retrieval → continuity → behaviour**.\nThe first two are deterministic, no-LLM, and run in CI with regression\nguards; the corpora, labels, and methods are auditable in-repo.\n\n**1 · Retrieval quality.** Does `fetch` return the *right* sections? On a\nlabeled 28-query / 28-section benchmark the shipped match-any retrieval\nputs a relevant section in the top 5 for **98%** of queries — a **+0.91\nrecall lift** over the prior match-all behaviour.\n\n| Config | recall@5 | hit@1 | MRR |\n|---|---|---|---|\n| match-all (AND) — prior | 0.07 | 0.07 | 0.07 |\n| **match-any (OR) — shipped** | **0.98** | **0.96** | **0.97** |\n\n→ method + caveats: [docs/eval/retrieval.md](docs/eval/retrieval.md) · `go test -run TestRetrievalEval -v ./internal/eval/`\n\n**2 · Cross-session continuity.** Does a lesson recorded in one session\nsurvive into the next? Through the real record → persist → retrieve loop, a\nlesson is in the next session's context in **5 / 5** scenarios **with**\nagent-memory and **0 / 5 without** (the amnesia baseline).\n\n→ [docs/eval/continuity.md](docs/eval/continuity.md) · `go test -run TestMemoryContinuity -v ./internal/eval/`\n\n**3 · Behavioural (task-success).** Does the agent *act* on it — fewer\nrepeated mistakes? That needs an LLM in the loop, so it ships as a runnable\nA/B harness (\"groundhog-day\", with vs without memory) you run with your own\nmodel: [eval/behavioural/](eval/behavioural/). No number is published here —\nisolating the *without* arm cleanly is non-trivial (stock Claude Code's own\nauto-memory leaks across runs; see the harness README). Not in CI by design.\n\n## Agent-runtime adapters\n\n`agent-memory install ` drops a worked instruction file at the\nlocation each runtime reads from:\n\n| Adapter | Target file | Notes |\n|---------|------------|-------|\n| `claude` | `.claude/skills/agent-memory/SKILL.md` | Claude Code skill format. `--user-global` writes to `~/.claude/skills/`. |\n| `cursor` | `.cursor/rules/agent-memory.mdc` | Cursor MDC rule with description-based matching. `--user-global` writes to `~/.cursor/rules/`. |\n| `agents` | `AGENTS.md` (repo root) | Industry-broad convention. Read by OpenAI Codex CLI, Cursor's agent mode, Sourcegraph Cody, etc. Project-local only. |\n| `gemini` | `GEMINI.md` (repo root) | Gemini CLI long-term project context. Project-local only. |\n\nEach file teaches the runtime when to call `memory.fetch_context` and\n`memory.propose_update`, the intent vocabulary, provenance rules, and\ndebugging reject reasons. The same behavioural model across all four;\neach adapter just wraps it in the runtime's native format.\n\n## Architecture (at a glance)\n\n```\n.agent-memory/\n├── meta/\n│ ├── manifest.yaml operational settings (budgets, approval, security)\n│ ├── schema.yaml per-category file/glob, section schema, provenance\n│ ├── index.sqlite FTS5 shadow index (regenerable)\n│ ├── lock OS-level advisory lock (flock)\n│ └── lock.info informational metadata sidecar\n├── conventions.md project conventions\n├── decisions.md durable architectural decisions\n├── pitfalls.md known footguns\n├── index.md server-managed memory index summary\n├── modules/.md per-module facts\n├── archive/-*.md write-once archived entries\n├── local/\n│ ├── current.shared.md cross-branch working notes\n│ └── current..md branch-scoped working notes\n├── sessions/.md per-day session logs\n└── staging// pending human-review proposals\n ├── proposal.json\n ├── target-checksums.json\n └── files/\n```\n\n## Layout\n\n```\ncmd/agent-memory/ CLI and MCP binary entry point\ninternal/\n adapters/ agent runtime adapters (Claude, Cursor, Codex, Gemini)\n bench/ retrieval & FTS5 benchmark harness\n cli/ cobra subcommands (init, fetch, propose, digest, vtp, etc.)\n config/ schema/ YAML loaders (manifest.yaml + schema.yaml)\n e2e/ release smoke test suite (-tags=e2e)\n eval/ offline retrieval and continuity benchmarks\n fs/ atomic file swap and path sanitization\n git/ branch resolution and repo inspection\n index/ FTS5 incremental shadow index\n lock/ flock-based cross-process advisory lock\n logging/ structured slog logging with level filtering\n markdown/ byte-preserving section-level Markdown engine\n mcp/ stdio JSON-RPC 2.0 Model Context Protocol server\n memory/ operations, staging pipeline, security scanner, Merkle tree\n vtp/ Verifiable Task Protocol (VTP-1) engine & Clause B verifier\nspikes/ pre-M1 architectural spikes (S1-S4)\ndocs/\n patterns/ reusable architecture patterns (SAR, Merkle, federation)\n eval/ retrieval and continuity benchmark methods and logs\n spikes/ spike outcome write-ups\n.github/workflows/ CI & CD release workflows (goreleaser)\nagent-memory-design-doc-v0.4.1.md canonical design specification\nagent-memory-implementation-plan.md MVP and federation build log\nCHANGELOG.md per-release feature list and upgrade notes\n```\n\n## Releases\n\nTag-driven via [goreleaser](https://goreleaser.com/). Pushing a `v*`\ntag triggers\n[`.github/workflows/release.yml`](.github/workflows/release.yml),\nwhich builds the binary matrix and publishes a GitHub Release with\narchives attached.\n\nMatrix per release:\n\n- `linux_amd64`, `linux_arm64`\n- `darwin_amd64`, `darwin_arm64`\n- `windows_amd64`, `windows_arm64`\n\nEach archive contains the `agent-memory` binary, `README.md`, and\n`CHANGELOG.md`. A sibling `agent-memory__checksums.txt`\nprovides SHA-256 hashes.\n\n```bash\n# Verify a downloaded archive\nsha256sum -c agent-memory_0.2.0_checksums.txt\n```\n\nLocal dry-run of the release pipeline (requires `goreleaser`\ninstalled):\n\n```bash\ngoreleaser check # parse + validate .goreleaser.yml\ngoreleaser release --snapshot --clean # full build with no upload\n```\n\nSource builds always identify as `dev`:\n\n```\n$ go build -o agent-memory ./cmd/agent-memory\n$ ./agent-memory version\ndev\n```\n\nRelease builds via goreleaser stamp the actual tag through\n`-ldflags='-X .../cli.ProgramVersion=v0.X.Y'`.\n\n## License\n\n[Apache License 2.0](LICENSE). You may use, modify, and distribute this\nsoftware under its terms; it includes an express patent grant. Contributions\nare accepted under the same license (see [CONTRIBUTING.md](CONTRIBUTING.md)).\n",
"bytes": 30427,
"sha": "87da2ccc4d0712b8365f19712cfa746047bd0c3b58ffa6917adf6af81f0b9096",
"repo_slug": "xchucx/agent-memory",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_xchucx_agent_memory_889dae5f/readme"
}
![\"agent-memory](\"docs/assets/banner.svg\")
\n![\"agent-memory:](\"docs/demo/demo.gif\")
\n