Vault-for-LLM

English | 繁體中文 | 简体中文

Local-first memory for LLM agents.

Vault-for-LLM creates a portable SQLite knowledge vault for your projects and AI agents. Add Markdown notes, compile them into searchable structured memory, and let agents query the vault through the vault CLI or the vault-mcp server.

Why this exists

LLM agents are powerful, but most of them forget project context between sessions. They lose decisions, repeated mistakes, user preferences, debugging history, and hard-won operational knowledge.

Vault-for-LLM gives an agent a simple local memory layer:

1. You write knowledge as Markdown.
2. vault compile stores it in a local SQLite database.
3. Agents search it only when needed, instead of stuffing everything into every prompt.
4. MCP-compatible agents can query the vault during a conversation.

The goal is not to replace your notes app. The goal is to make your notes usable by agents.

What makes it different

Vault-for-LLM is not just another vector store. It is evolving into an agent memory QA layer:

• Can the agent find the right memory when it needs it?
• Can it read only the relevant section instead of dumping whole documents into context?
• Can it tell whether a knowledge entry is complete, stale, duplicated, or under-specified?
• Can teams measure search quality before and after changing retrieval logic?
• Can reusable agent workflows be shared as skills instead of rediscovered in every project?

In other words: regular RAG focuses on retrieval; Vault-for-LLM focuses on whether memory can be used correctly by agents.

Core principles

• Local by default — SQLite is the source of truth. No cloud is required for core usage.
• Works without embeddings — keyword search works first; semantic search is optional.
• Agent-oriented memory — split always-needed facts from searchable deep knowledge.
• Bounded retrieval — Document Map tools help agents read the right section instead of dumping entire files into context.
• Optional sync — Supabase support is an optional sync/read target, not required infrastructure.
• CLI-first — this is a developer-facing tool. Core local usage is stable; advanced QA, semantic, and sync workflows still evolve.

What's new in 0.5.0

Version 0.5.0 upgrades Vault-for-LLM from “local keyword-search memory” into a measurable retrieval workflow:

• Search QA baseline — run fixed query sets and compare retrieval quality/latency before and after search changes.
• FTS5/BM25 keyword search — faster keyword retrieval when SQLite FTS5 is available, with safe fallback to the legacy LIKE path for compatibility and CJK misses.
• Guarded semantic workflow — optional semantic vectors, provider validation, persistent embedding cache, and operator commands for rebuild/warm/smoke/startup/daemon.
• Explicit DB schema status/migration — inspect and run idempotent SQLite migrations with vault db status/migrate.
• Release gates — README command smoke, wheel smoke, version parity, secret scan, full-history privacy scan, and public-boundary checks.

Semantic search is optional by design: the base install still works with keyword search only. If you configure a real embedding provider, use vault semantic ... to rebuild vectors, warm caches, and run smoke checks. Deterministic hash embeddings require --allow-hash and are for CI/local tests only.

Older repository hygiene tools from 0.4.3 are documented in scripts/README.md and docs/repo_governance.md.

What it can do

Quality tools roadmap

These features exist today, but their maturity differs. Core local commands are the stable path; advanced QA, semantic, sync, and skill-registry workflows are still evolving:

The benchmarks/search_qa/ examples are repository fixtures in a source checkout, not files installed by the PyPI wheel. After pip install vault-for-llm, run vault search-qa with your own QA JSON files, or clone/download this repository to use the example fixtures.

The stable path is still the core loop: vault init → vault add → vault compile → vault search → vault-mcp.

Architecture

L0 Identity        → who the user/project is; loaded every session
L1 Core Facts      → stable environment and project facts; loaded every session
L2 Recent Context  → recent decisions, incidents, and working context
L3 Deep Knowledge  → lessons, APIs, architecture, troubleshooting; searched on demand

Markdown raw/  →  vault compile  →  SQLite database  →  vault search / MCP tools

This keeps the agent prompt small while still making deeper memory available when relevant.

Installation

Install from PyPI

python3 -m venv .venv
source .venv/bin/activate
pip install vault-for-llm

vault doctor

Optional semantic search

Keyword search works with the base install. For local ONNX embeddings:

pip install "vault-for-llm[semantic]"
vault install-embedding --model mix

Or use an existing Ollama embedding model:

vault config set embedding.provider ollama
vault config set embedding.model nomic-embed-text

Optional MCP server

pip install "vault-for-llm[mcp]"
vault-mcp --project-dir /path/to/your/project

Security note: vault-mcp is a local stdio MCP server. It does not implement network authentication or user-level access control. Only configure it for agents you trust with read/write access to the selected --project-dir, and prefer a dedicated project directory for shared or experimental agents.

Development install from source

git clone https://github.com/zycaskevin/Vault-for-LLM.git
cd Vault-for-LLM
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Quickstart

# 1. Create a vault in your project
vault init

# 2. Add a first knowledge entry
vault add "First lesson" --content "The bug was caused by X. The fix was Y."

# 3. Compile Markdown into the local SQLite vault
vault compile

# 4. Search it later
vault search "what caused the bug"

You can also add Markdown files directly under raw/ and run vault compile.

Example entry:

---
title: "Postgres migration pitfall"
category: "error"
layer: L3
tags: ["postgres", "migration"]
trust: 0.8
source: "project-notes"
created: "2026-05-16"
---

# Postgres migration pitfall

What broke, why it broke, and how to avoid it next time.

Optional semantic workflow

Semantic search is optional by design. The base install keeps working with keyword search only. After configuring a real embedding provider, the main operator commands are:

vault semantic rebuild --persist-cache
vault search "what caused the bug" --mode semantic
vault search "what caused the bug" --mode hybrid
vault semantic smoke --qa-file benchmarks/search_qa/basic.en.json --mode semantic --pretty
vault semantic cache-stats --pretty

vault search --mode semantic reads stored semantic_vectors directly. --mode hybrid fuses keyword results with the stored semantic index when available, and falls back safely when it is not.

For the full lifecycle — warm, cache-prune, startup, daemon, and the --allow-hash test-only provider — see docs/semantic_search.md.

Directory structure

your-project/
├── L0-identity/              # user or project identity loaded every session
│   └── identity.md
├── L1-core-facts/            # stable facts loaded every session
│   └── current-projects.md
├── L2-context/               # recent context, decisions, incidents
│   └── recent-sessions/
├── L3-knowledge/             # deep knowledge organized for retrieval
├── raw/                      # source Markdown knowledge entries
├── compiled/                 # compiled / compressed knowledge artifacts
├── vault.db             # local SQLite database generated by vault
└── templates/                # starter templates

CLI reference

Run vault <command> --help for command-specific options.

Obsidian export

Use vault export obsidian when you want humans to browse the compiled vault in Obsidian without changing the source knowledge base:

vault export obsidian \
  --vault /path/to/ObsidianVault \
  --category technique \
  --dry-run

The export is intentionally one-way and read-only: it reads from vault.db, writes Markdown notes under 00-Vault-Knowledge/, includes YAML frontmatter plus Vault #<id> citations, and does not write back to raw/, compiled/, SQLite, or any remote sync target. Re-running the command overwrites the same stable note paths instead of creating duplicates.

For citation-safe memory use, see the Document Map citation policy: search results are navigation hints, while vault map read returns bounded source text for final citations.

MCP integration

Install MCP extras and start the server:

pip install "vault-for-llm[mcp]"
vault-mcp --project-dir /path/to/your/project

Security note: vault-mcp is a local stdio MCP server. It does not implement network authentication or user-level access control. Only configure it for agents you trust with read/write access to the selected --project-dir, and prefer a dedicated project directory for shared or experimental agents.

Example MCP server config:

{
  "mcpServers": {
    "vault": {
      "command": "vault-mcp",
      "args": ["--project-dir", "/path/to/your/project"]
    }
  }
}

Current MCP tools include:

• vault_search
• vault_add
• vault_stats
• vault_map_show
• vault_read_range
• vault_remote_map_show / vault_remote_read_range when optional Supabase sync is configured

For agent loops, prefer vault_search → vault_map_show → vault_read_range. vault_search returns compact MCP payloads by default; pass compact: false only when a caller explicitly needs the fuller preview output. Final answers should cite vault_read_range output rather than search previews.

Optional Supabase sync

Core Vault-for-LLM usage is local-only. Supabase support is for teams or remote read paths that want a synced copy of local SQLite data.

The local SQLite database remains the source of truth. Supabase is an optional sync/read target. Remote table names use Vault-branded defaults and can be overridden with VAULT_SUPABASE_*_TABLE environment variables when integrating an existing private schema.

# optional integration dependency
pip install supabase

# configure Supabase credentials in your environment, then run sync scripts as needed
python scripts/sync_to_supabase.py --document-map

Current maturity

Vault-for-LLM is CLI-first developer tooling:

• Core local commands (init, add, compile, search) are the most stable path.
• Search QA, FTS5/BM25 keyword search, Document Map citation reads, and semantic workflow commands are usable but still evolving.
• Optional integrations such as Supabase sync, MCP, and local skill registry may change before a stable 1.0 release.
• The default install is available from PyPI; source installs are for development.

If you want the most stable path, start with:

vault init
vault add
vault compile
vault search

Development

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest -q

Some optional test paths require optional dependencies such as ONNX, MCP, or Supabase.

License

MIT