context-vault

Persistent memory for AI agents — save and search knowledge across sessions. Your data stays local as markdown files.

Hosted tier — cloud sync, web dashboard, and team sharing → app.context-vault.com

<p align="center"> <img src="assets/vault-brain.png" alt="Vault Brain — 3D knowledge graph visualization showing nodes, edges, and hub detection" width="800"> </p> <p align="center"><em>Vault Brain — your knowledge as a living neural network</em></p>

Quick Start

npx context-vault

Setup detects your AI tools (Claude Code, Cursor, Codex, Windsurf, etc.), configures MCP, downloads the embedding model (~22MB), and seeds a starter entry. Takes about 2 minutes.

The server auto-configures as a shared daemon, so all your AI sessions share one process. Updates are applied automatically.

Then restart your AI tool (required to pick up the new MCP server) and try:

"Search my vault for getting started"

You’re done. The vault lives at ~/vault/ — plain markdown files you own.

What It Does

• Save — Insights, decisions, patterns, contacts. Your AI agent writes them as you work.
• Search — Hybrid full-text + semantic search. Ask in natural language.
• Own your data — Markdown in folders you control. Git-versioned, human-editable.

First Steps

Tell your AI	What happens
"Save an insight: React Query's staleTime defaults to 0"	Creates ~/vault/knowledge/insights/...
"Search my vault for React Query"	Returns matching entries
"List my recent decisions"	Browses entries by kind
"Show my vault status"	Diagnostics and health

MCP Tools

Your AI agent uses these automatically — you don’t call them directly.

Core

Tool	Description
get_context	Search vault — hybrid full-text + semantic vector search
save_context	Save or update entries (insights, decisions, patterns...)
list_context	Browse entries with filters (kind, tags, date range)
delete_context	Remove an entry by ID

Ingest

Tool	Description
ingest_url	Fetch a URL, extract readable content, save as a vault entry
ingest_project	Scan a local project directory — extracts metadata and creates a bucket

Session

Tool	Description
session_start	Auto-assemble a context brief on session start — recent entries, decisions, blockers
clear_context	Reset in-memory session scope without deleting entries
create_snapshot	Compile vault entries on a topic into a single structured brief

System

Tool	Description
context_status	Vault health — config, file counts, database size, issues
list_buckets	List all registered buckets (named scopes for grouping entries)

Kinds: insight · decision · pattern · reference · contact — or any custom kind. Derived from vault subdirectory names.

CLI Reference

Command	Description
context-vault setup	Interactive installer — detects tools, writes MCP configs
context-vault ui [--port 3141]	Web dashboard
context-vault status	Vault health, paths, entry counts
context-vault reindex	Rebuild search index
context-vault import <path>	Import .md, .csv, .json, .txt
context-vault export	Export to JSON or CSV
context-vault update	Check for updates
context-vault uninstall	Remove MCP configs

Note: context-mcp works as an alias; context-vault is the primary command.

Hosted Option

Prefer cloud over local? No Node.js required — cloud sync, web dashboard, and team sharing at app.context-vault.com. Sign up, get an API key, and connect in 2 minutes.

Full setup instructions for Claude Code, Cursor, and GPT Actions: docs/distribution/connect-in-2-minutes.md

Configuration

Defaults work out of the box. Override if needed:

Setting	Default
Vault dir	~/vault/
Data dir	~/.context-mcp/
Database	~/.context-mcp/vault.db

Config: ~/.context-mcp/config.json. Env vars: CONTEXT_VAULT_VAULT_DIR, CONTEXT_VAULT_DB_PATH, etc.

Requirements

Node.js 22+. First run spawns a shared daemon that auto-updates from npm.

Prerequisites by Platform

Platform	Install Node.js 22+
macOS	brew install node or nvm: nvm install 22
Windows	winget install OpenJS.NodeJS.LTS or nvm-windows
Linux	nvm: nvm install 22 or NodeSource

Troubleshooting

Install fails (native modules):

npm rebuild sqlite-vec

Vault not found:

mkdir -p ~/vault
context-vault setup

Stale search results:

context-vault reindex

Feedback & Community

• Questions or ideas? Start a thread in Discussions
• Found a bug? Open an issue
• Using context-vault? I'd love to hear how — drop a note in Show & Tell

Development

git clone https://github.com/fellanH/context-vault.git
cd context-vault
nvm use
npm install
npm run cli -- setup

Use npx context-vault or npm run cli -- instead of context-vault when running from source.

License

MIT