vaultmind

VaultMind

Associative memory for AI agents — over Git-backed Markdown vaults.

AI agents start each session from zero: strong parametric knowledge, but no memory of what they did yesterday, what they decided, or what they're working toward. VaultMind turns a directory of Markdown notes into queryable, linked memory an agent can reconstruct itself from at the start of a session — and continue from, rather than start over.

It's a single Go binary, local, with no server. Point it at a vault of Markdown files with Obsidian-compatible frontmatter; it builds a derived index (full-text + dense + sparse + late-interaction embeddings), resolves [[wikilinks]] and aliases into a knowledge graph, and answers queries with ranked, token-budgeted context. Two things it does need: the embedding model it downloads on first use (BGE-M3, about 2.3 GB, for the full hybrid; MiniLM, about 90 MB, for the pure-Go build), and — for the agent hooks — bash and python3, which the hook scripts run under.

Install

Quick — MiniLM, every platform:

go install github.com/peiman/vaultmind@latest   # requires Go >= 1.26.6

A pure-Go binary: full-text + MiniLM dense retrieval (2 lanes). Ideal for trying VaultMind — it does not include BGE-M3's sparse + ColBERT lanes.

Full 4-way hybrid — BGE-M3 (recommended for real use):

Download the self-contained ORT archive for your platform (darwin-arm64, linux-amd64) from the releases page — vaultmind_<version>_<os>_<arch>_ort.tar.gz — extract, and run. The official libonnxruntime is bundled (found automatically next to the binary), so there's nothing else to install — no compiler required. Upgrading an existing install? Extract elsewhere and mv the new binary into place rather than copying over the old one — mv is atomic and gives a fresh inode. Overwriting in place has been seen once on macOS to trip a codesigning SIGKILL; the cause is unconfirmed, but replacing rather than overwriting avoids it and is the safer form anyway.

Which one? For a small vault or a slow machine, MiniLM is genuinely fine — its dense lane covers a small corpus well, and its lighter query encoder keeps per-prompt latency low (that cost lands on every recall). Reach for BGE-M3 when your vault is large and varied and recall quality matters most. Note: go install is the only path that can't produce BGE-M3 (cgo can't travel through it) — so if your setup uses go install, you're on MiniLM by design; the prebuilt archive above is the no-compile way to the full hybrid.

From source (any platform with a C toolchain):

git clone https://github.com/peiman/vaultmind && cd vaultmind
brew install onnxruntime   # macOS; Linux: install from the ONNX Runtime releases
task setup:ort             # downloads the tokenizer static lib
task build                 # auto-selects ORT when the tokenizer lib is present

See docs/embedding-backends.md for every backend, platform, performance note, and the dense-only vs. 4-way-hybrid tradeoff.

Quickstart

# 1. scaffold a project knowledge base (type registry, README, starter notes)
#    — or an agent's identity vault with --profile persona
vaultmind init ./my-vault

# 2. index + embed
vaultmind index --vault ./my-vault
vaultmind index --embed --vault ./my-vault

# 3. ask
vaultmind ask "what did we decide about retries?" --vault ./my-vault

A project that already has docs doesn't have to start empty: vaultmind import copies a folder's Markdown into the vault as notes tied to their doc, and a re-run brings changes across. An http or https URL imports that one page.

vaultmind init ./knowledge
vaultmind import docs --vault ./knowledge --dry-run   # see what it would do
vaultmind import docs --vault ./knowledge             # re-run after the docs change
vaultmind import https://sqlite.org/fts5.html --vault ./knowledge

Try it with the example vault

VaultMind ships a small fictional example vault — Ada, an agent that pair-programs with a developer named Sam on a toy CLI — so you can see retrieval and persona reconstruction working before you build your own.

These commands assume a repo checkout — run git clone https://github.com/peiman/vaultmind && cd vaultmind first if you installed via go install or the prebuilt archive. The example vault also ships concept cards (concepts/) defining the vocabulary — arc, episode, principle, and how they link.

vaultmind index --vault examples/ada-vault
vaultmind index --embed --vault examples/ada-vault     # BGE-M3 on an ORT build, MiniLM otherwise
vaultmind ask "who are you" --vault examples/ada-vault
vaultmind ask "what did Ada learn about scope?" --vault examples/ada-vault

How it works

• Vault — a directory of Markdown notes with Obsidian-compatible frontmatter, tracked in Git. You curate it; the agent reads it.

• Index — a derived SQLite index: full-text (FTS5), dense + sparse + ColBERT embeddings (BGE-M3), and a link/alias knowledge graph. Rebuilt with vaultmind index; never hand-edited.

• Retrieval — Reciprocal Rank Fusion over the lanes, with top-hit confidence measured against each vault's own noise floor (the strong/moderate/weak bands are provisional: so far fit on a handful of vaults). A hit brings along the notes it links to (wikilinks, related_ids), so recalling one memory surfaces its neighbours. Ranking does not yet learn from use: usage-weighted ranking exists as an experiment, but replayed against real usage it did not improve recall, so it is not applied to results.

• Context packs — vaultmind ask assembles ranked results into a token-budgeted block ready to drop into an agent's context.

• Delivery — the pack carries note text, not just titles. A note larger than the remaining budget would otherwise contribute nothing while still being counted, which on a vault whose median note exceeds a hook's budget is every query rather than an edge case:

  vaultmind ask "spreading activation" --vault <path> --budget 4000 --excerpt 120
  

  --excerpt N caps each note at N tokens instead of dropping it, preferring the note's Principle section where it has one — arcs run trigger → push → deeper sight → principle, so the opening is story setup and the rule sits several sections down. Injecting "the first paragraph" hands an agent the anecdote and withholds the lesson. Off by default (0); set it when wiring a hook with a tight budget.

  A weak-but-correct top hit in a tight, well-curated vault delivers its body too. Low contrast between hits is a property of a focused vault, not evidence the top hit is wrong. Genuinely off-topic hits still land at or below the noise floor and stay suppressed.

  The context header states what actually arrived, in numbers you can recount from the output below it — 9 notes, 9 delivered as excerpts (968 tok). Changed in 0.7.0 from the old N items form: if you parse that line, update it.

Everything is --json-able for programmatic use; every command returns a stable envelope.

Agent integration (persona reconstruction)

VaultMind wires into Claude Code, Codex CLI and Cursor so the agent works from its vault each session. Name the project and the vault, and let it write the wiring. --profile persona asks for the persona loader and episode capture; without it a fresh project gets the knowledge set (recall, decision-time reach, the code map, health), the right shape for a knowledge vault:

# Claude Code — writes <project-dir>/.claude/settings.json
vaultmind hooks install <project-dir> --vault <your-vault> --merge

# Codex CLI — writes <project-dir>/.codex/hooks.json
vaultmind hooks install <project-dir> --vault <your-vault> --agent codex --merge

# Cursor — writes <project-dir>/.cursor/hooks.json
vaultmind hooks install <project-dir> --vault <your-vault> --agent cursor --merge

# Recall across several vaults (identity + a desk, say); the persona loads the first
vaultmind hooks install <project-dir> --vaults <identity-vault>,<desk-vault> --profile persona --merge

Add --dry-run to preview the change first. Without --merge the scripts are written and the wiring is printed for you to paste. Without --vault, the hooks look for <project-dir>/vaultmind-identity.

Codex needs your approval, and skips the hooks silently without it: trust the project when Codex asks, then run /hooks inside Codex and trust the VaultMind hooks. Until then the agent starts with no memory and nothing says why. Approve again after upgrading: a new or changed hook is skipped until you do. vaultmind hooks status <project-dir> checks each VaultMind hook the way Codex does (never approved, or changed since you approved it) and fails while any would be skipped. Codex projects keep the scripts in .vaultmind/scripts/, not .claude/. Under Codex, episode capture runs when the session ends; read-tracking, the code map and the pre-compaction prompt are Claude Code only. Every capture run, under either agent, leaves a line in ~/.vaultmind/capture/capture.log saying what happened.

Cursor adds context only at session start and after a tool runs. So under Cursor the agent gets the vault map at session start, the notes about a file after it reads or edits that file, and related notes after a commit — but no per-prompt recall: Cursor's hooks cannot add context to a prompt. The session-start message tells the agent to ask the vault itself (vaultmind ask), and in our tests it did. Cursor projects share .vaultmind/scripts/ with Codex.

Any MCP client, including agents without a shell. vaultmind mcp serves a vault over stdio to Claude Desktop, Cursor, or any MCP client. Its tools are ask, search, note_get, tree, links, note_create and import (a web page or site: http(s) URLs from public addresses only, since a page the agent read could prompt it). Each one runs the vaultmind command of the same name with --json, so a tool answers exactly what the CLI answers. The vaults are fixed when the server starts, so a client can't point a tool at another directory.

claude mcp add vaultmind -- vaultmind mcp --vault /path/to/vault

Claude Desktop, Cursor (.cursor/mcp.json) and most other clients take the same entry: {"mcpServers": {"vaultmind": {"command": "vaultmind", "args": ["mcp", "--vault", "/path/to/vault"]}}}. MCP gives an agent the tools, while the hooks above deliver the vault without being asked, so use both where your agent has hooks.

This installs hook scripts that load identity + current context at session start, surface relevant pointers per turn, and capture each session as an episode for later distillation. Check them with vaultmind hooks status <project-dir>, which reports both halves — whether each script matches the canonical copy, and whether each canonical event is actually wired in settings.json. A project can hold every script byte-identical and still run none of them; an unwired event is reported by name and fails the check. The scripts are embedded in the binary and written into <project-dir>/.claude/scripts/ (idempotent). See docs/AGENT_USAGE.md for the day-to-day agent workflow, and docs/building-an-identity-vault.md for how to grow an agent's identity from scratch — the arc method, and why an identity vault is personal and usually shouldn't be committed to a shared repo.

Cold start — seed from your existing sessions. A new identity vault is empty, but you've probably worked with an agent for months. Point episode capture at a directory of past Claude Code transcripts to batch-capture them into episodes (recursive; empty/non-transcript files skipped), then surface candidate arcs — so the vault starts warm, not blank:

vaultmind episode capture ~/.claude/projects/<project> --output-dir ~/.vaultmind/persona/episodes
vaultmind arc candidates --vault ~/.vaultmind/persona

Codex sessions work too: each is one rollout-*.jsonl under ~/.codex/sessions/. Codex keeps every project's sessions in that one folder, so capture the files of the project you mean rather than the whole folder, which would pull other projects' sessions into this vault. Codex's own sub-agent threads (its reviewers, spawned helpers) are passed over, the same as Claude Code's.

Subagent and workflow transcripts nested under a session are passed over: they carry the parent session's id, so capturing them would overwrite the session itself. The summary reports how many. (Pass one directly if you do want it captured.)

The desk — where raw material lands

arc candidates reads two sources. <vault>/episodes holds session captures, which it phrase-matches for candidate moments — guesses worth checking. The desk is any note in the vault whose frontmatter says type: journal: something the agent stopped mid-session to write down, already judged worth keeping. Episodes are found; desk entries are chosen, and the report weights them accordingly.

---
id: journal-2026-08-15-green-means-matches-my-assumption
type: journal
created: 2026-08-15
title: Green means "matches what I assumed", not "correct"
---
Spent an hour on a bug that turned out to be the test asserting the wrong thing.
The suite was green the whole time.

type: journal is what makes it a desk entry; the id is what lets you cite it later (from the arc it becomes, or via note get). An entry without one is still surfaced, flagged as unciteable.

Add distilled_to: <arc-id> to an entry once you've written its arc, and it stops being surfaced — so the list stays what's pending, not everything ever written. Each proposal is shown with the existing arcs it most resembles, which needs embeddings (vaultmind index --embed); without them the proposals still appear, minus the neighbours.

Keep the desk somewhere the agent owns outright. Use --arcs-vault when the desk and the arcs live in different vaults:

vaultmind arc candidates --vault ./agent-desk --arcs-vault ./agent-identity

The local usage log

VaultMind keeps a local SQLite log of retrieval events — which queries surfaced which notes, and which notes an agent then opened — as the raw material for learning from use. Today it is a record, not an input: it does not change what search returns. It is on by default, and it is worth knowing exactly what that means.

On your disk, by default: the full query text, the vault path, the note ids returned, and caller metadata ($USER, hostname, CLAUDE_PROJECT_DIR). The file is created 0600 — together with the -wal and -shm sidecars SQLite writes beside it, which hold the same material — at

• macOS: ~/Library/Application Support/vaultmind/experiments.db
• Linux: $XDG_DATA_HOME/vaultmind/experiments.db (default ~/.local/share/vaultmind/experiments.db)

Nothing is transmitted — VaultMind has no uploader, and doctor's once-a-day version check is the only network call it makes on its own (see "The one network call").

experiments.telemetry chooses what leaves, not what is written:

So anonymous means anonymous when shared. It is not a redaction at write time, and a reader who opens the database will find their queries in it. Reading an existing log still works under off; turning it off is a decision about new data, not a lock on what you already have.

To turn it off — in ~/.config/vaultmind/config.yaml (or $XDG_CONFIG_HOME/vaultmind/config.yaml):

experiments:
  telemetry: off

The nesting matters. A bare experiments: off does not work — it is read as an empty value and you get the anonymous default, which is the opposite of what you asked for. VAULTMIND_EXPERIMENTS_TELEMETRY=off works too, and vaultmind config prints what is currently in effect.

Turning it off loses that history; it changes nothing about today's search results.

Sharing remains something you do on purpose: there is no automatic upload, and export only writes a file.

The one network call

vaultmind doctor asks the Go module proxy once a day whether a newer VaultMind exists, and prints a line if so. That is the only time VaultMind reaches the network on its own, and it sends nothing about you or your vault — it is a GET for a version number, the same request go install …@latest makes. The answer is cached for 24 hours, times out in 3 seconds, and is silent on any failure.

It lives on doctor and nowhere else: that is the command you run to ask whether your setup is healthy, so a network call there is expected rather than a surprise — and putting it on ask would tax every query. Set VAULTMIND_NO_UPDATE_CHECK=1 to opt out; the check returns before making any request, and the notice itself tells you that variable exists.

Contributing

VaultMind is a Go CLI built on the ckeletin-go scaffold (the .ckeletin/ framework layer). task check is the single quality gate — it runs formatting, linting, architecture and security checks, the full test suite, and the coverage floor. If it passes, the change is sound regardless of who wrote it.

• Read AGENTS.md for architecture rules and conventions, and CONTRIBUTING.md before opening a PR.
• TDD: write the failing test first; commit test + implementation together.

License

See LICENSE.