agent-memory

Purpose

agent-memory provides local, searchable project memory for AI coding agents. Memory uses Markdown as the source of truth and is committed into the code repository, with git serving as the synchronization mechanism; no cloud is required, and no vector database is used. It primarily solves the problem of agents forgetting context across multi-turn tasks, allowing task state, decisions, conventions, pitfalls, and module-level facts to be persistently recorded and retrieved across sessions.

Main Capabilities

• A single MCP call yields structured memory updates covering the current task state, decisions, conventions, pitfalls, and facts for each module.
• Branch-aware, secret-safe, byte-preserving.
• Memory is readable plain Markdown and can be reviewed with git diff; persistent changes are first staged pending human review, and after viewing the diff via review --diff , they are landed via apply , rather than being written silently.
• Secrets and personally identifiable information (PII) are scanned for and removed before writing.
• Provides three MCP tools and a complete CLI.
• Federated memory (federation): a repository's .agent-memory/ knows only about itself, while federation allows it to reference a shared read-only "landscape" store, bringing architecture knowledge bases, platform patterns, or peer service memories into the agent's reasoning loop.
• Version 0.6.1 brings Swarm Audit Hardening and Metamorphic Rebase: category-enforced approval routing, whole-file pre-state CAS, polarity/negation qualifier preservation in Jaccard deduplication, idempotent pure read-only fetch_context, canonical three-way merge deletion semantics; during rebase, whole-file pre-hash drift is detected to prevent silent overwrites when adjacent blocks are concurrently edited.
• Control-plane manifest isolation: fail-closed protection is enforced for .agent-memory/meta/manifest.yaml , preventing direct modification, symlink bypass, or path traversal.
• RFC 8785 (JCS) determinism: the internal vtp strictly follows JSON canonicalization, passes all 26 official test vectors, supports ECMAScript floating-point formatting, rejects lone surrogates, and performs recursive UTF-8 validation.
• Cross-process SQLite NonceStore (fail-closed): uses the withDB pattern to persist repository-scoped storage, eliminating Windows file descriptor locks, with zero-drift atomic verification and automatic cleanup of expired nonces.
• Two-phase staging and composite rollback: strict path traversal sanitization (ValidateStagingID, agentfs.ValidateMemoryPath), symlink containment, atomic multi-file rollback.
• VTP-1 strict assertion identification and dual-oracle settlement: assertion results must match the declared ID, verifier key binding verification, and Workpool/0 Clause B disjoint seat enforcement.
• Federated namespace governance (SAR-010): identifiers undergo full Unicode case folding normalization (FullCasefold(NFC(Trim(s)))),agent-memory doctor Can detect potential cross-platform case conflicts before deployment; supports local parsing overrides (meta/store_overrides.yaml) to define local_alias and exclude routes without modifying upstream.
• Anti-TOCTOU dual concurrency barrier: kernel-level OS advisory lock serializes write operations (sync, apply), while readers (fetch) hold a shared read lock throughout the entire store resolution and context bundle assembly; unconditional lockfile CAS digest verification (VerifyStoresLockCAS) is verified before writing.
• Read-set write-skew verification (ReadSections CAS): temporarily stores a record of all section hashes read during proposal synthesis; rebase and apply verify they have not drifted before applying changes.
• Typed governance event receipts (ProvenanceAlert): isolation conflicts or stale drift emit machine-readable receipts tracking incident_id, assigned_steward, escalation_deadline, and upstream commit SHA.
• VTP-1 verifiable task protocol: turns task execution into an end-to-end, machine-verifiable 5-phase cryptographic lifecycle.

Usage

1. Install: download the prebuilt binary package for your OS/arch from the latest release, extract it, and put agent-memory in your PATH; no toolchain required. Homebrew, Scoop, and winget packages are planned, and agent-memory has also been listed in the MCP Registry.
2. Run inside the target repository install claude will automatically register the MCP server: it merges a project-level .mcp.jsonat the repository root, runs agent-memory mcp --root ${CLAUDE_PROJECT_DIR:-.}. Claude Code expands CLAUDE_PROJECT_DIR at startup, so the server always serves the current repository; the configuration is portable across clones and overrides stray user-level servers according to Claude Code scope precedence (local > project > user). It is recommended to commit .mcp.json for team sharing.
3. The server resolves the repository in order from --root、$CLAUDE_PROJECT_DIR, and the working directory. Other runtimes (Cursor, Gemini CLI, any tool that reads AGENTS.md) use the same server and require installing their respective adapters.
4. Adopting on an existing project:init generates empty memory, then have the coding agent analyze the real codebase, then restart the agent so the memory.* tools load, then paste the prompt. The agent reads the repository and calls memory.propose_update; working notes and pitfalls take effect immediately, while persistent categories (conventions, decisions, modules) are staged pending review, use agent-memory review --diff to view and agent-memory apply to finalize (or reject). Without an MCP server, the agent or user can directly use the CLI, going through the same verification/secret scanning/routing pipeline.
5. Building from source requires Go 1.25+ (indirectly required by the MCP SDK); the make targets are equivalent to the above go commands.
6. Federation quick start: connect to the public architecture Wiki (https://github.com/xChuCx/arch-wiki），返回包实现两层检索——低 The token invariant package comes with on-demand pointers to full in-depth articles.

Applicable Scenarios

• Teams that need to provide AI coding agents with cross-session, reviewable project memory.
• Scenarios where memory is expected to be readable, diffable, and version-controllable, rather than a black-box vector store.
• Multi-repository environments that need federated sharing of architectural knowledge, platform patterns, or peer-to-peer service memory.
• Compliance-sensitive projects that need secret/PII security and audit trails.
• Experimental scenarios in multi-agent swarms or economic tasks that require machine-verifiable task execution.

Limitations

• VTP-1 status is experimental/security hardening in progress: Clause B disjoint seat verification currently relies only on identity string inequality (worker != verifier != creator), and in open decentralized or economic environments without external PKI or attested hardware identity, it should not yet be used as an adversarial trust boundary; cryptographic account attestation is under development.
• The anti-TOCTOU double barrier guarantees strict serializability only for cooperating processes participating in the locking protocol, and explicitly does not constrain non-cooperating external writers that bypass OS advisory locks.
• The repository's .agent-memory/ itself only knows about itself; cross-repository knowledge must be introduced through federated storage.
• No specific fee or pricing information is provided.
• The installation method currently recommends prebuilt binaries; Homebrew, Scoop, and winget packages are still planned.
• Federation coverage strictly requires the target storage to be non-eventually consistent (readback_consistency: eventual will be rejected), and incident_id, assigned_steward, and a valid RFC3339 escalation_deadline are mandatory fields.
• The documentation mentions that system-level/multi-repository memory is still planned in ROADMAP.md.