Brainvault

Personal memory for Claude Code and Cursor — one local SQLite vault, MCP tools, and host hooks. No cloud, no extra infrastructure.

Best experience: Claude Code. Cursor works but has limitations — see Host support.

PyPI  ·  Repository  ·  Issues  ·  Changelog  ·  Documentation

Brainvault gives your agent durable context: decisions, patterns, project facts, and session notes stay in ~/.brainvault/memory.db, searchable across projects. Install once globally; hooks keep the vault warm while you work.

Quick start

pip install brainvault
brainvault install

Fully quit your editor (not just close a tab), then reopen so MCP loads. Verify:

brainvault doctor

Host support

Claude Code — recommended

Brainvault is built around Claude Code and works seamlessly there:

• CLAUDE.md is injected as a system-level instruction — Claude follows the memory rules reliably on every turn.
• Stop + PostToolUse hooks fire automatically after each turn — no manual steps.
• get_my_context() is called at session start without prompting.
• Cross-project context, proactive capture, and git scan all work out of the box.

Cursor — supported, with caveats

Cursor works but the experience is noticeably less smooth:

Workaround in Cursor: if context feels missing, say ”check my context” — that reliably triggers get_my_context(). Always verify brainvault is listed as an active MCP server for the current chat.

How it works in practice

Session start — context loads automatically

Open Claude Code and start working. Brainvault calls get_my_context() on your first turn:

> hey, continuing work on the backend

[Claude calls get_my_context()]

Got it. Picking up on myapp — a few things worth flagging before we start:
- Auth middleware: session tokens stored in a way that may not meet the new compliance
  requirements — this was flagged as a known risk last sprint.
- DB connection pool set to 5 in staging config, still needs bumping before prod deploy.

No briefing needed. It remembered.

Bug you've seen before — surfaces instantly

> getting a weird memory leak, can't figure out where it's coming from

[Claude calls search_memory("memory leak background task")]

Found it — you hit this in a previous project. Root cause: background tasks holding
references to closed database connections. Fix: explicit cleanup in the task teardown,
don't rely on GC. You noted this pattern 3 weeks ago.

One search, actionable answer, zero re-diagnosis.

Starting a new project — context follows you

> starting a new service, going with FastAPI + PostgreSQL

[Claude calls register_project() + save_memory(decision)]

Registered. Noted the stack. Pulling in patterns from your other projects — you've
already solved async connection pooling, JWT auth flow, and rate limiting. Want me
to flag those decisions before you re-implement them?

Prior work becomes a starting point, not forgotten history.

When does it get good?

Brainvault improves as you use it — here's roughly what to expect:

Run brainvault bootstrap and brainvault bootstrap-git ~/Projects after install to seed the vault with your existing history — this jumpstarts the process significantly.

What it does

• Hooks: after each agent turn — session notes, git scan, optional repo index, optional embedding backfill.
• Search: FTS5 keyword search always; optional semantic blend if you install [semantic] (see below).

MCP tools (12) — available to the agent once MCP is connected:

Memory types (for save_memory):

Vault: ~/.brainvault/memory.db (global — not per-repo).

Configs patched (global):

brainvault install --agent claude_code or --agent cursor limits which host is patched.

When to run what

Bootstrap and bootstrap-git are idempotent (safe to re-run).

CLI (short list)

Run brainvault help for the full command list. Common ones: install, uninstall, doctor, bootstrap, bootstrap-git, git-scan, index-repo, search, status, stats, reflect, export / import, embed, graph, sessions, activity.

Optional semantic search

pip install 'brainvault[semantic]'
brainvault embed

Adds local embeddings (fastembed + sqlite-vec); first run downloads a small model to ~/.cache/huggingface. Search blends keywords + vectors when extras are installed. Not required for normal use.

Platform support

macOS and Linux are fully supported and tested. Windows support is best-effort — hook commands use forward-slash paths (C:/Users/...) which work in both cmd.exe and PowerShell, and all file I/O is UTF-8. If you hit an issue on Windows, please open an issue.

Out of scope

• Not cloud sync or team wiki.
• Not full RAG over every line of your repo; index-repo + get_code_context are structural (files, imports, co-change), not “embed all source”.

Contributing / internals

• CLAUDE.md — module map, hook behaviour, MCP tool details, how to run tests.
• CONTRIBUTING.md — releases, PyPI README images, dev notes.

git clone https://github.com/SumithSB/brainvault.git
cd brainvault
pip install -e ".[dev]"
pytest

MIT License.