README
¶
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, activation-weighted 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. 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.
Install
Quick — MiniLM, every platform:
go install github.com/peiman/vaultmind@latest # requires Go >= 1.26.4
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.
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 installis the only path that can't produce BGE-M3 (cgo can't travel through it) — so if your setup usesgo 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 vault (type registry, README, starter notes)
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
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 vaultmindfirst if you installed viago installor 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 calibrated top-hit confidence and optional activation-weighted reranking (notes accessed more often become more retrievable).
- Context packs —
vaultmind askassembles ranked results into a token-budgeted block ready to drop into an agent's context.
Everything is --json-able for programmatic use; every command returns a stable envelope.
Agent integration (persona reconstruction)
VaultMind can wire into Claude Code — or any agent that supports SessionStart hooks — so the agent reconstructs itself from its vault each session:
vaultmind hooks install <project-dir>
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. 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
Opt-in usage telemetry
VaultMind records local retrieval events (which queries surfaced which notes) to power activation-weighted reranking. Sharing that data is opt-in and sanitized — no note bodies, no content, no query text; only counts and identifiers — for anyone who wants to contribute anonymized retrieval signal back to the project. It is off by default and never leaves your machine unless you run the export.
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.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
ckeletin:allow-custom-command
|
ckeletin:allow-custom-command |
|
internal
|
|
|
baseline
Package baseline provides pre-curated golden-query regression metrics for VaultMind's retrievers.
|
Package baseline provides pre-curated golden-query regression metrics for VaultMind's retrievers. |
|
cmdutil
Package cmdutil provides shared helpers for CLI command implementations.
|
Package cmdutil provides shared helpers for CLI command implementations. |
|
commandcatalog
Package commandcatalog turns an assembled cobra command tree into a structured, group-ordered catalog and renders it for two surfaces: a terminal cheat-sheet (used by `vaultmind help`) and a markdown reference (used by `vaultmind docs commands` and embedded into onboarding).
|
Package commandcatalog turns an assembled cobra command tree into a structured, group-ordered catalog and renders it for two surfaces: a terminal cheat-sheet (used by `vaultmind help`) and a markdown reference (used by `vaultmind docs commands` and embedded into onboarding). |
|
discovery
Package discovery locates VaultMind vaults under a root directory so multi-vault commands (e.g.
|
Package discovery locates VaultMind vaults under a root directory so multi-vault commands (e.g. |
|
distill
Package distill reads rendered episode markdown (the durable episodic substrate captured by internal/episode) and surfaces candidate transformation moments for arc distillation — plasticity step 2.
|
Package distill reads rendered episode markdown (the durable episodic substrate captured by internal/episode) and surfaces candidate transformation moments for arc distillation — plasticity step 2. |
|
embedding
Package embedding provides text embedding infrastructure for VaultMind.
|
Package embedding provides text embedding infrastructure for VaultMind. |
|
envelope
Package envelope provides the standard JSON response wrapper for all --json output.
|
Package envelope provides the standard JSON response wrapper for all --json output. |
|
episode
Package episode parses a Claude Code session transcript (JSONL) into a structured Episode and renders it as a markdown "episode" file for the identity vault.
|
Package episode parses a Claude Code session transcript (JSONL) into a structured Episode and renders it as a markdown "episode" file for the identity vault. |
|
experiment
Package experiment provides the SQLite-backed database for VaultMind experiment data.
|
Package experiment provides the SQLite-backed database for VaultMind experiment data. |
|
fix
Package fix implements the `vaultmind frontmatter fix` command's logic — walking the vault and identifying domain notes that are missing the `created` field, then optionally writing it via the existing mutator.
|
Package fix implements the `vaultmind frontmatter fix` command's logic — walking the vault and identifying domain notes that are missing the `created` field, then optionally writing it via the existing mutator. |
|
graph
Package graph provides entity resolution and graph traversal over the SQLite index.
|
Package graph provides entity resolution and graph traversal over the SQLite index. |
|
hooks
Package hooks — legacy hooks.json detection.
|
Package hooks — legacy hooks.json detection. |
|
hooks/autorag
Package autorag defines the auto-RAG drift catalog schema — the JSON shape consumers use to declare their project-specific drift signatures for `auto-rag-guard.sh`.
|
Package autorag defines the auto-RAG drift catalog schema — the JSON shape consumers use to declare their project-specific drift signatures for `auto-rag-guard.sh`. |
|
hookscripts
Package hookscripts is the single source of truth for VaultMind's Claude Code hook scripts.
|
Package hookscripts is the single source of truth for VaultMind's Claude Code hook scripts. |
|
index
Package index provides the SQLite-backed derived index for VaultMind.
|
Package index provides the SQLite-backed derived index for VaultMind. |
|
initvault
Package initvault scaffolds a fresh VaultMind vault from embedded templates.
|
Package initvault scaffolds a fresh VaultMind vault from embedded templates. |
|
mutation
Package mutation provides utilities for reading and writing YAML frontmatter in Markdown note files while preserving key order, scalar styles, and line ending conventions.
|
Package mutation provides utilities for reading and writing YAML frontmatter in Markdown note files while preserving key order, scalar styles, and line ending conventions. |
|
noisefloor
Package noisefloor turns a raw top-hit cosine similarity into an honest relevance signal, relative to the vault's noise floor N — the cosine an off-topic ("garbage") query gets to any note in the vault.
|
Package noisefloor turns a raw top-hit cosine similarity into an honest relevance signal, relative to the vault's noise floor N — the cosine an off-topic ("garbage") query gets to any note in the vault. |
|
onboard
Package onboard provides the embedded agent-onboarding script as a CLI-accessible asset.
|
Package onboard provides the embedded agent-onboarding script as a CLI-accessible asset. |
|
parser
Package parser extracts frontmatter, links, headings, and blocks from Markdown files.
|
Package parser extracts frontmatter, links, headings, and blocks from Markdown files. |
|
progress
Package progress provides a flexible progress reporting system with handler-based architecture for composable output handling (logging, console, Bubble Tea UI).
|
Package progress provides a flexible progress reporting system with handler-based architecture for composable output handling (logging, console, Bubble Tea UI). |
|
query
Package query provides read-only vault diagnostics and search operations.
|
Package query provides read-only vault diagnostics and search operations. |
|
retrieval
Package retrieval defines the retrieval contract shared by every search backend (FTS, dense/sparse/ColBERT embedding, hybrid fusion) and by consumers that evaluate or compose them (baseline runner, ask/search commands).
|
Package retrieval defines the retrieval contract shared by every search backend (FTS, dense/sparse/ColBERT embedding, hybrid fusion) and by consumers that evaluate or compose them (baseline runner, ask/search commands). |
|
schema
Package schema provides the type registry and frontmatter validation.
|
Package schema provides the type registry and frontmatter validation. |
|
shellparse
Package shellparse provides shell-quoting-aware preprocessing for hooks that pattern-match Bash command strings.
|
Package shellparse provides shell-quoting-aware preprocessing for hooks that pattern-match Bash command strings. |
|
template
Package template provides template processing and ID generation for notes.
|
Package template provides template processing and ID generation for notes. |
|
testvault
Package testvault provides shared, per-process test fixtures built from the committed fixture vault.
|
Package testvault provides shared, per-process test fixtures built from the committed fixture vault. |
|
vault
Package vault provides vault scanning and configuration loading.
|
Package vault provides vault scanning and configuration loading. |
|
xdg
Package xdg provides XDG Base Directory Specification compliant paths.
|
Package xdg provides XDG Base Directory Specification compliant paths. |
|
test
|
|