Vault-for-LLM

繁體中文 | 简体中文 | English

🧠 A local-first, open-source knowledge management system for LLM agents.
Zero cloud dependency. Zero Docker. Zero PyTorch. Just pip install and go.

What is Vault-for-LLM?

Vault-for-LLM is a four-layer hierarchical knowledge base designed to give any LLM agent persistent, searchable memory. It runs entirely locally using SQLite + sqlite-vec + ONNX embeddings.

Key Features

• Four-layer architecture (L0–L3) for structured knowledge injection
• Hybrid search: keyword + semantic vector search (ONNX, no GPU needed)
• Knowledge graph: auto-inferred entities and edges with 2-hop BFS expansion
• Atomic claims with source citations: sub-chunk granularity, every claim traceable to original text
• Self-questioning convergence: system judges if it "knows enough" to explain a topic (KAL-inspired)
• Cross-family LLM validation: extract with one model, verify with another to catch hallucinations
• Freshness tracking + FSRS spaced repetition: automated staleness detection and review scheduling
• AAAK compression: 6x compression for compiled knowledge
• Trust scoring: every knowledge entry has a confidence score (0.0–1.0)
• Lint & contradiction detection: automatic quality checks
• MCP server: expose your vault to any MCP-compatible AI agent mid-conversation
• CLI-first: 20+ commands for full lifecycle management

Architecture

L0 Identity      → Who the user is (injected every conversation)
L1 Core Facts    → Environment & active projects (injected every conversation)
L2 Context       → Recent decisions & troubleshooting (auto-updated daily)
L3 Deep Knowledge → Architecture, techniques, lessons (searched on demand)

What's New in v0.4.0

See CHANGELOG.md for full details.

Quick Start

# Install
pip install -e .

# Initialize a project
vault init

# Add knowledge
vault add "My First Entry" --content "Something I learned today"

# Compile (raw → database + compiled)
vault compile

# Search
vault search "my query"

# Health check
vault doctor

See INSTALL.md for detailed installation options.

Directory Structure

your-project/
├── vault.yaml          ← Project config (auto-generated by `vault init`)
├── L0-identity/             ← Who the user is (injected every conversation)
│   └── identity.md
├── L1-core-facts/           ← Core facts (injected every conversation)
│   └── current-projects.md
├── L2-context/              ← Dynamic context (auto-updated daily)
│   └── recent-sessions/
│       └── current.md
├── L3-knowledge/            ← Deep knowledge (searched on demand)
├── raw/                     ← Raw knowledge input (your .md files go here)
├── compiled/                ← AAAK compressed backup (auto-generated)
└── templates/               ← Clean templates for L0/L1/L2

AI Integration Guide

Any LLM Agent (Universal)

1. Read this README to understand the architecture
2. Read L0-identity/identity.md to know the user
3. Read L1-core-facts/current-projects.md for current state
4. Use vault search "query" for semantic search

Claude Code / Cursor / Any AI IDE

1. Copy CLAUDE.md (included) into your project root
2. For deep knowledge, search compiled/ or raw/
3. Use rg "keyword" raw/ compiled/ for fast lookup

MCP Integration (Chat with your vault)

Connect your vault to any MCP-compatible AI agent:

# Install MCP dependencies
pip install "vault-for-llm[mcp]"

# Start the server
vault-mcp --project-dir /path/to/your/project

Now your AI can search, add, and query knowledge mid-conversation — no manual copy-paste needed.

CLI Reference

MCP Server (Claude Code / Cursor / OpenClaw)

Expose your vault directly to any MCP-compatible AI agent:

# Install MCP dependencies
pip install "vault-for-llm[mcp]"

# Start the server (run from your project directory)
vault-mcp

# Or specify path explicitly
vault-mcp --project-dir /path/to/your/project

Add to your Claude Code config (~/.claude/claude_desktop_config.json):

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

Available MCP tools: vault_search, vault_add, vault_get, vault_list, vault_stats

Knowledge File Format

All .md files use YAML frontmatter:

---
title: "Knowledge Title"
category: "concept|technique|workflow|lesson|error|comparison"
layer: "L0|L1|L2|L3"
tags: ["tag1", "tag2"]
trust: 0.0-1.0
source: "source-description"
created: "YYYY-MM-DD"
---

Trust Score Guide

Compiler

vault compile

What it does:

• raw/ → database (upsert by content hash)
• raw/ → compiled/ (AAAK 6x compression)
• Extract atomic claims with source_span citations
• Auto L2 update + lint health check + git commit

Tech Stack

Requirements

• Python 3.10+
• ~150MB for ONNX embedding model (optional)
• No GPU, no Docker, no cloud account needed

License

MIT License — see LICENSE.

Built for developers who want their AI agents to actually remember things.