vaultmind

VaultMind

A project's knowledge, where its agents can use it.

A codebase records what the system does. It rarely records why: the decisions and what they ruled out, how the parts work, the gotchas someone already paid for. VaultMind keeps that knowledge in a vault of plain Markdown notes in Git, and gets it to the agents that work on the project: searched, ranked and delivered into their context as they work, with no server and no LLM of its own.

It's a single Go binary. It builds a derived index (full-text, dense, sparse and late-interaction embeddings) and a graph of the [[wikilinks]] between notes. It needs 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 bash and python3 for the agent hooks.

What you can do

Get knowledge in

A re-import brings changes across and keeps notes you edited by hand (--force overwrites them). --dry-run shows what an import would do. A long document becomes an index note plus one note per section. Images become notes of their metadata, their text (OCR, when tesseract is installed) and, with --vision-endpoint, a description from a vision model.

Find it

Give it to agents

Keep it healthy

Every command has --help, and --json for scripts. vaultmind --help lists all of them by what you want to do.

Install

Claude Code plugin — one command:

claude plugin install vaultmind --marketplace peiman/vaultmind

Requires Claude Code 2.1.292+. Then run /vaultmind:vaultmind-setup inside Claude Code; the agent initializes a vault, imports project Markdown, embeds it and verifies retrieval. The plugin downloads a version-pinned binary on first use and supplies hooks plus MCP tools. See plugin/README.md for requirements, existing-hook coexistence, data storage and uninstall options.

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. The same MiniLM build is published as a plain archive, vaultmind_<version>_<os>_<arch>.tar.gz (no v in the version), for platforms without an ORT build. Windows is a .zip of that build.

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

The ORT archives carry a v in the version. The two published for v0.10.18 are vaultmind_v0.10.18_darwin_arm64_ort.tar.gz and vaultmind_v0.10.18_linux_amd64_ort.tar.gz (darwin_arm64 and linux_amd64) on the releases page. Extract the archive, keep libonnxruntime* in the same directory as the binary, and put that directory on PATH. The official libonnxruntime is bundled, so there's nothing else to install — no compiler required. Upgrading an existing install? Extract elsewhere and mv the new binary and its libonnxruntime* libraries into place rather than copying over the old ones — 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.

With the ORT build, the first vaultmind index --embed downloads the BGE-M3 model (about 2.3 GB). On an Apple Silicon Mac a first embed of 74 notes took 133 seconds and used 2.7 GB peak memory.

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             # verifies ONNX Runtime; hugot uses a Go tokenizer
task build                 # auto-selects ORT when the toolchain check passes

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

Quickstart

vaultmind init ./knowledge
vaultmind import docs *.md --vault ./knowledge
vaultmind index --embed --vault ./knowledge
vaultmind ask "what did we decide about retries?" --vault ./knowledge
vaultmind hooks install . --vault ./knowledge --merge

The shell expands *.md to the root Markdown (README, CONTRIBUTING, AGENTS, and the rest) and skips dotfiles, so tool chat logs such as .aider.chat.history.md stay out; drop docs if the project has no docs/, and if the project has no root Markdown, leave out *.md (zsh aborts the whole command with no matches found otherwise). Re-running the same command picks up changes; a root doc you delete or rename must be removed from the vault by hand: delete its file under <vault>/imported/ and run vaultmind index --vault <vault> (single-file imports have no orphan pass, even with --prune).

vaultmind init --wire-hooks installs the hooks while scaffolding. vaultmind init --print-instructions prints the agent setup guide.

init writes a type registry, a README for the vault and starter notes. doctor names those starters (2 example notes: delete or keep). Add your own notes as Markdown with frontmatter; vaultmind index picks up hand edits.

The vault's .vaultmind/.gitignore keeps its index, caches and locks out of git while leaving config.yaml, section templates, project hook setup and the telemetry fingerprint available to commit; init and the first index create it when absent and preserve an existing file.

The first index --embed downloads the embedding model if it is not cached (about 2.3 GB for BGE-M3). Allow a few minutes for the first embed: one run of 74 notes took 133 seconds and peaked at 2.7 GB of memory; time and memory depend on note length and hardware. Each batch prints embedded <done>/<total> notes (<elapsed>s) to stderr, so progress stays visible with --json too. The count includes only notes whose vectors were stored; failed batches are reported on the same line. Imports keep this progress, while ordinary note writes print one embed summary. Later runs reuse the cached model and skip notes whose embeddings are current.

Agents: hooks and MCP

Hooks deliver the vault without being asked. hooks install writes scripts into the project and wires them into the agent's settings (--merge adds to existing hooks and never removes them; --dry-run previews). A knowledge vault gets: the vault map and health at session start (and again after /clear and compaction), the notes that match each prompt as short excerpts, the notes about a code file when the agent reads or edits it, and related notes before a commit, push or merge. A note marked pinned: true is loaded at session start too, under one budget for the session, with a long note excerpted to 400 tokens. That mark lives in the vault so it survives hooks install --force. 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, and again after every upgrade. vaultmind hooks status <project-dir> checks each hook the way Codex does and fails while any would be skipped. Codex projects keep the scripts in .vaultmind/scripts/. Read-tracking, the code map and the pre-compaction prompt are Claude Code only.
• 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, and in our tests it did. Cursor projects share .vaultmind/scripts/ with Codex.

For Claude Code hooks in every project, use vaultmind hooks install --scope user --vault /absolute/path/to/knowledge --merge. Scripts live in ~/.vaultmind/scripts, with absolute paths in ~/.claude/settings.json. Check or upgrade an existing global install with vaultmind hooks status --scope user and vaultmind hooks install --scope user --merge --force --dry-run (preview before applying). Status fails for broken command paths or overlapping user/project hooks; install warns about overlaps and migrates generated legacy commands while preserving custom commands as conflicts. See user-scope hooks for Codex, Cursor and overwrite protection.

vaultmind hooks status <project-dir> reports both halves: whether each script matches the copy in the binary, and whether each event is actually wired. See docs/AGENT_USAGE.md for the day-to-day agent workflow.

MCP gives any client the tools. 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 deliver the vault without being asked, so use both where your agent has hooks.

An agent's own identity (persona vaults)

A vault can also hold who an agent is: the moments that changed how it works, its principles, and its captured sessions. Loaded at session start, it lets a new session continue as the same agent. vaultmind init --profile persona makes one, and hooks install --profile persona loads it. See docs/persona-vault.md for the persona hooks, seeding a vault from past sessions, the desk, and the example vault, and docs/building-an-identity-vault.md for the arc method.

How it works

Notes are the source of truth; the SQLite index is derived from them and rebuilt by vaultmind index. Search fuses full-text, dense, sparse and ColBERT lanes, and reports how far the top hit clears the vault's own off-topic noise floor, so "nothing relevant" is an honest answer. A hit brings along the notes it links to. See docs/how-it-works.md for retrieval, context packs, excerpts and delivery.

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.

doctor reports observable evidence over seven days:

Memory use (7d, all vaults on this machine): 5 surfaced → 5 delivered → 1 opened, 2 cited (2 unknown — not measurable from text)
gap-closing notes (all vaults on this machine): 1 surfaced, 1 cited

opened is a logged read in the same conversation and vault. cited means the exact note ID appeared in that turn's assistant text or tool inputs, with reads taking precedence. Titles and injected recall blocks do not count. Neither signal proves influence, and unknown never means unused: applying an idea in other words cannot be measured from text. The check runs in episode capture (the existing SessionEnd capture hook, or Stop when wired to that path), adding no work to recall. See use evidence for the event and JSON fields and measurement limits.

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. (import reaches the network when you give it a URL, and --vision-endpoint sends images to the endpoint you name; neither happens on its own.)

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.