Agent Memory Vault: one Git-backed Markdown memory that Claude Code and Codex share
Markdown-first shared memory vault for Claude Code and Codex with SQLite, Zvec, Git, closeout, and audit
At a glance
- What is it?
- Agent Memory Vault is a local-first long-term memory system where Markdown files remain the source of truth, SQLite provides structured and full-text retrieval, and an optional local vector sidecar adds semantic search. Its real subject is governance: session-scoped claims, validated writes and a fail-closed closeout so two agents can share one memory without trampling each other.
- Who is it for?
- Agent Memory Vault fits developers running both Claude Code and Codex who want one auditable long-term memory instead of two private ones, and anyone whose agent memory needs provenance: every write classified, claimed by a session, and committed by a closeout that fails closed on unclaimed changes. It does not fit teams wanting hosted or multi-machine sync, since local-first is the architecture, or anyone unwilling to run a Python CLI alongside their agents.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 19 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
One vault, two agents, Markdown on top
Agent Memory Vault addresses the gap between a useful coding session and a durable collaboration. Agents are competent inside one conversation and amnesiac outside it, and simply keeping chat history does not fix that: history is not organized, not verifiable, and not safe to share between tools. The project's answer is a local-first, Git-backed vault that Claude Code and Codex use together, with one vault, one Git history and one retrieval index between them.
The layering is explicit. Markdown remains the source of truth: facts, decisions, workflows, project state and agent lessons live as readable files. SQLite provides structured and full-text retrieval over them. An optional EmbeddingGemma plus Zvec layer adds local semantic search, with a requirements-vector lock file pinning that side of the stack. Every derived store is rebuildable from the Markdown, which is the only rule that keeps an index honest over time.
Privacy posture is stated up front: the repository itself contains only reusable templates, scripts and fictional examples. Real memories, paths, credentials and conversation content stay in your private local vault. Obsidian is optional; the vault is an ordinary Markdown directory that works with any editor, and the Obsidian topic tag reflects fit rather than dependency.
The trust model: claims, closeout, fail-closed
What separates this from a shared notes folder is the write discipline. Sessions claim the files they changed, claims are stored as session hashes, and a closeout processes only the files claimed by that session, explicitly excluding changes owned by other sessions. Two agents working concurrently therefore cannot accidentally commit each other's edits. When there is nothing to process, closeout exits successfully as a no-op; unclaimed memory changes still fail closed, meaning the default outcome for unattributed edits is refusal, not silent inclusion.
The normal write sequence has five steps: prewrite to classify the source, knowledge type, target and duplicate risk; edit the Markdown; claim the changed files; closeout with a dry-run flag to review; then closeout for real, which checks, indexes, audits and optionally commits only the claimed files. High-impact writes get more: source checks, content-bound intents, approvals and immutable receipts.
For protected paths and host applications there is also a two-phase workflow through a host boundary script, structured as read-target, then prepare, then an explicit apply or cancel. The design keeps the agent on the read side of the boundary and the user on the trigger side, which is the correct place for that split.
Retrieval: candidate generators, not truth
The retrieval design draws a line most memory systems blur. Unified search combines SQLite and FTS results with the optional Zvec sidecar, deduplicates candidates and applies orthogonal filters: project, memory type, track, scope and status. The README then says the quiet part out loud: search indexes are candidate generators, not authorization or truth sources.
The retrieve path is where truth lives. It reopens the current Markdown, validates containment and symlinks, requires strict UTF-8, reapplies scope and status rules, checks for sensitive content, and returns bounded excerpts with current hashes. Every answer is re-derived from the files as they are now, not as the index remembers them, so a stale index can cost recall but cannot fabricate authority.
That distinction, indexes propose and retrieval disposes, is the most portable idea in the repository. It is also why the optional vector layer is genuinely optional: losing it degrades candidate generation, never correctness.
Bootstrap, indexes, and the first health check
Requirements are Python 3.10 or newer and Git. The quick start:
git clone https://github.com/mcncarl/agent-memory-vault.git
cd agent-memory-vault
cp .env.example .env
python3 scripts/bootstrap.py --memory-root "$HOME/agent-memory-vault" --write-env
source .env
python3 scripts/agent_memory_evolution.py --init --scan --report
python3 scripts/agent_memory_index.py --init --scan --report
python3 scripts/agent_memory_check.py
python3 scripts/agent_memory_doctor.pybootstrap.py creates an independent Git repository inside the private vault and commits the template baseline, preserving any existing Git history; a flag exists to skip Git initialization entirely when that is intentional. If the checkout has neither .env nor a runtime TOML file, generated databases and logs stay in an ignored local .agent-memory/ directory, and the project does not silently reuse another installed memory system, a small detail that says a lot about how it treats your machine.
On Windows 10 and 11 there is a PowerShell installer:
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-windows.ps1 `
-MemoryRoot "$HOME\Documents\Agent Memory Vault"It accepts paths containing spaces or non-ASCII characters, creates a private virtual environment, installs a verifiable runtime, initializes the vault and indexes, and runs the built-in checks. A doctor script provides end-to-end health checks on demand, and the .env.example file confines all configuration to the AGENT_MEMORY_* namespace, covering roots, state and audit databases, closeout and audit logs, and the optional embedding settings such as a 300M EmbeddingGemma model at 768 dimensions on CPU.
Wiring it into Claude Code and Codex
Sharing is deliberately thin. Codex reads the vault's shared AGENTS.md; Claude Code imports the same file from its CLAUDE.md using an absolute-path import; Claude Code's native auto-memory is expected to remain separate from the formal vault; and both hosts call the shared CLI with their own actor and session identity:
python3 scripts/memoryctl --actor codex search "project status" --limit 5
python3 scripts/memoryctl --actor codex prewrite \
"Stable fact to preserve" \
--source-class user_direct \
--knowledge-kind fact \
--asserted-by user \
--evidence-ref "current-conversation"
python3 scripts/memoryctl --actor codex claim \
--file "/absolute/path/to/changed-memory.md"
python3 scripts/memoryctl --actor codex closeout --dry-run
python3 scripts/memoryctl --actor codex closeoutReading those commands left to right: a search limited to five results, a prewrite that classifies a stable fact by source class, knowledge kind, asserter and evidence reference, a claim on an absolute file path, then a dry-run closeout followed by the real one. The flags are the governance made visible, since every write carries its provenance with it.
Search examples show the filter vocabulary:
python3 scripts/agent_memory_search.py "project closeout" --limit 5
python3 scripts/agent_memory_search.py "preferences" --track user
python3 scripts/agent_memory_search.py "deployment boundary" --current-project example-appTrack, project and limit constraints narrow candidates before retrieval revalidates them. The adapter model means neither tool gets special plumbing: anything that can run the CLI and read one Markdown file participates.
Boundaries, licence, and the per-tool alternative
The boundaries are worth stating plainly. The vault is Python plus Git plus SQLite, with an optional local vector runtime; if you want hosted sync or multi-machine concurrency, the repository does not provide it, since local-first is the point. There are no published releases yet, so pinning means pinning a commit. Tests run in CI, docs cover architecture, privacy, automation and Windows, and the licence is MIT. The last push was on 2026-08-31.
The alternative is what most people do now: each tool's own memory. Claude Code ships native auto-memory, and Codex keeps its AGENTS.md conventions, but those are per-tool silos with no shared lifecycle, no cross-session claims, and no fail-closed closeout; the README itself instructs keeping Claude's native memory separate from the vault rather than pretending they integrate. A plain wiki or an Obsidian folder alone gives human readability without any of the write governance. What this project sells is precisely the unglamorous part, verification, scoping and audit, and it sells it to whichever agent you run.
Editorial conclusion
Agent Memory Vault fits developers running both Claude Code and Codex who want one auditable long-term memory instead of two private ones, and anyone whose agent memory needs provenance: every write classified, claimed by a session, and committed by a closeout that fails closed on unclaimed changes. It does not fit teams wanting hosted or multi-machine sync, since local-first is the architecture, or anyone unwilling to run a Python CLI alongside their agents. Verify first: that bootstrap.py creates the private vault and Git baseline on your machine, that closeout --dry-run reviews exactly the files your session claimed, and that retrieve, not raw search, is what your agents call for answers. The last push was on 2026-08-31.
Frequently asked questions
What is a memory vault?
In this project, a local Markdown directory that acts as the source of truth for long-term agent memory, backed by Git history, with SQLite for structured and full-text retrieval and an optional local vector sidecar. Agents read and write it through scripts rather than chat history.
What does agent memory mean?
Memory that an AI coding agent keeps across sessions: stable facts, decisions, workflows, project state and lessons learned, preserved as readable Markdown files instead of living only inside one conversation that ends.
What is the main problem with AI memory?
Per the project's framing, chat history is not durable collaboration: sessions overwrite each other, writes go unverified, and derived stores drift from the truth. It answers with session-scoped claims, validated high-impact writes, immutable receipts and indexes rebuildable from the Markdown source.
Community notes