mcncarl/agent-memory-vault

Agent Memory Vault – a local, Git‑backed long‑term memory store for Claude Code, Codex and similar AI coding agents

What it is – A Python‑based toolkit that lets AI coding agents keep a durable, auditable knowledge base on your own machine. The source of truth is a plain‑text Markdown directory (the vault). Git tracks every change, SQLite provides fast keyword/FTS lookup, and an optional local embedding model (EmbeddingGemma + Zvec) adds semantic search. All data stays private; the public repository only contains the reusable scripts and templates.

Why it matters – Current AI‑coding assistants (Claude Code, Codex, etc.) only remember what was said in the current chat session. When a project spans many sessions, important facts, decisions, and code snippets get lost. Agent Memory Vault gives those agents a shared, version‑controlled memory that:

• Persists across sessions.
• Guarantees that any write is reviewed, signed, and recorded in Git.
• Allows safe concurrent use by multiple agents (Codex, Claude, a third‑party “Ailu”).
• Provides both keyword and optional vector search while keeping the authoritative Markdown untouched.

Core components

Component	Role
templates/vault/	Ready‑made Markdown layout you can copy into a private folder.
scripts/bootstrap.py	Creates a fresh vault, initializes a private Git repo, and writes the initial INDEX.md.
scripts/memoryctl	Unified command‑line interface used by agents for search, retrieve, write, migration, health‑checks, etc.
scripts/agent_memory_index.py	Builds the SQLite FTS index from the vault.
scripts/agent_memory_search.py	Runs keyword + optional vector (Zvec) search and returns ranked candidates.
scripts/agent_memory_retrieve.py	Re‑opens the selected Markdown file, validates hashes, and returns a bounded excerpt.
scripts/agent_memory_write.py	Implements the read‑prepare‑authorize‑apply write flow with fencing tokens and Git commits.
scripts/agent_memory_migrate.py	Handles upgrades of the vault schema (v1 → v4) with explicit backup and audit steps.
scripts/agent_memory_closeout.py	Finalizes a write, records the receipt in Git, and updates the audit ledger.
scripts/agent_memory_doctor.py	End‑to‑end health‑check suite that verifies the vault, indexes, and runtime configuration.

How it works (high‑level flow)

1. Create a vault – bootstrap.py makes a private directory, copies the Markdown template, and commits it to a new Git repo.
2. Index – agent_memory_index.py scans the vault and builds a SQLite FTS table; optionally a Zvec vector index is added.
3. Search – Agents call memoryctl --actor <agent> search "query". The CLI merges keyword matches and, if enabled, vector scores (Hybrid RRF) and returns a list of memory_ids.
4. Retrieve – memoryctl retrieve --view section … re‑opens the exact file, checks that the stored hash still matches the current file, and returns a safe excerpt.
5. Write – The write protocol is:
   • write read-target → fetch current bytes and lease token.
   • write prepare → propose a new version, get a monotonic fencing token.
   • Authorization (human or policy) → approve the proposal.
   • write apply → the CLI verifies the lease, token, Git base, and then atomically replaces the file and records a receipt.
   • closeout → final audit entry and Git commit.
6. Migration / upgrades – memoryctl --actor migration … runs a planned, read‑only migration, backs up the state DB, and only after explicit review applies changes.

Key safety guarantees

• Git‑backed immutability – every accepted change is a signed Git commit; the vault can be rolled back.
• Fencing tokens – prevent stale writers from overwriting newer proposals.
• Audit ledger – all reads, writes, and status transitions are logged with hashes, timestamps, and risk classifications.
• Privacy‑first logging – search logs store only hashes and classifications, never raw queries or user‑identifying data.
• Explicit risk classes – actions marked action_sensitive require stricter evidence and cannot be downgraded.

Installation (quick start)

# Clone the repo
git clone https://github.com/mcncarl/agent-memory-vault.git
cd agent-memory-vault

# Install the POSIX entry point (plans then applies)
python3 scripts/install-posix.py --plan \
  --memory-root "$HOME/agent-memory-vault" --no-host-hooks --json
python3 scripts/install-posix.py --apply \
  --memory-root "$HOME/agent-memory-vault" --no-host-hooks \
  --launchagent-backup-dir "$HOME/.config/agent-memory/backups/launchagent-NEW" \
  --json

The --plan step only reads and reports what would happen; --apply performs the actual bootstrap, Git init, and index creation.

Typical usage by an AI agent

# Search for relevant project notes
scripts/memoryctl --actor codex search "deployment boundary" --limit 5

# Retrieve a specific section safely
scripts/memoryctl --actor codex retrieve --view section \
  --file "项目/example.md" --project-id example-app \
  --section-id s0002 --expected-sha256 '<outline-sha256>' --json

# Propose a new decision record (the agent prepares the markdown, then asks a human to approve)
scripts/memoryctl --actor codex write read-target --json <<'JSON'
{"schema_version":2,"target_relative_path":"决策/2024-10-17-deploy.md","app_id":"example-app","project_id":"example-project"}
JSON
# …human reviews the proposal JSON, then:
 scripts/memoryctl --actor codex write apply <proposal-id> --json

All writes go through the same gated flow, guaranteeing that the vault never contains an unreviewed edit.

Optional semantic search – If you want vector‑based retrieval, install the extra environment:

python3 -m venv .venv-vector
.venv-vector/bin/pip install -r requirements-vector.lock

The vector layer only supplies candidate IDs; the authoritative SQLite/Markdown layer still performs the final filtering.

Supported platforms – macOS, Linux (POSIX installer) and Windows 10/11 (PowerShell installer). The core code is pure Python 3.10+ and has no external services; all data stays on the local machine.

Maturity – The repository contains a full test suite (scripts/run_tests_isolated.py) and a “doctor” health‑check command. The design targets production‑grade safety for local AI agents, but it is still a niche, self‑hosted tool aimed at developers who run Claude Code, Codex, or similar agents in their own environment.

---

Bottom line – Agent Memory Vault gives you a private, version‑controlled, searchable knowledge base that multiple AI coding agents can read from and write to safely. It bridges the gap between fleeting chat‑session memory and durable project documentation, all while keeping the data under your control.