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 can suit developers who want shared, auditable Markdown memory across supported coding agents. The current project uses a governed write and migration workflow; review its installation plan, backups, host-hook choices and authorization steps before applying changes.
- 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 42 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 November 15, 2026, and from our analysis. They are not legal advice.
Star history
- mcncarl/agent-memory-vault347 ★ · +33
| Repository | 2026-09-21 | 2026-11-15 |
|---|---|---|
| mcncarl/agent-memory-vault | 314 | 347 |
33 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial 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
The project uses session-scoped claims and a governed write boundary to reduce accidental inclusion of another session's work. The current README describes reading the target, preparing an exact proposal and applying it after the required authorization. Claims are projections of an active intent rather than write permission; a fencing token prevents an older lease holder from applying after a newer one. Successful apply runs scoped closeout. These safeguards depend on using the supported workflow, so inspect the current documentation and test it for your deployment rather than treating concurrency isolation as unconditional.
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
The project requires Python 3.10 or newer and Git. Its current macOS/Linux guide recommends a read-only `install-posix.py --plan` followed by an explicit `--apply`, with host hooks chosen deliberately. Select a private memory root separate from the source checkout and review the plan before applying it. Upgrades may require reviewed migration dispositions and new backup paths; macOS apply also requires a separate unused LaunchAgent backup directory. Follow the current README for the exact arguments and platform-specific steps.
The lower-level bootstrap sequence is for a fresh vault only. The project explicitly says not to use `bootstrap.py` as an upgrade step against an existing vault. The Windows guide supplies a PowerShell installer and explains its runtime and health checks.
Wiring it into Claude Code and Codex
The project describes a shared `AGENTS.md` for Codex and an absolute-path import from Claude Code's `CLAUDE.md`; Claude's native auto-memory remains separate. Hosts use `memoryctl` with an actor and session identity. The current supported write workflow reads the target and obtains a read token, prepares a content-bound proposal, then applies it only after the required authorization; apply runs scoped closeout. Consult the current README and host-hook guide for exact JSON schemas, backup requirements and commands.
Search returns candidates, while `retrieve` reopens and revalidates the current Markdown with scope and status rules. This distinction matters when a memory is stale or belongs to another project.
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 can suit developers who want shared, auditable Markdown memory across supported coding agents. The current project uses a governed write and migration workflow; review its installation plan, backups, host-hook choices and authorization steps before applying changes. Use a private vault path separate from the source checkout, and follow the current upgrade guide for an existing installation.
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.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/mcncarl-agent-memory-vault)Star history chart for your README
[](https://hysenlabs.com/projects/mcncarl-agent-memory-vault)Was this useful?