xChuCx/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
| 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 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),