BrainLayer
Your AI has amnesia. BrainLayer fixes that.
Every architecture decision, every debugging session, every preference you've expressed — gone between sessions. You repeat yourself constantly. Your agent rediscovers bugs it already fixed.
BrainLayer gives any MCP-compatible AI agent persistent memory across conversations. One SQLite file. No cloud. No Docker. Just pip install.
"What approach did I use for auth last month?" → brain_search
"Remember this decision for later" → brain_store
"What was I working on yesterday?" → brain_recall
"Ingest this meeting transcript" → brain_digest
"What do we know about this person?" → brain_get_person
Quick Start
pip install brainlayer
Add to your MCP config (~/.claude.json for Claude Code):
{
"mcpServers": {
"brainlayer": {
"command": "brainlayer-mcp"
}
}
}
That's it. Your agent now remembers everything.
Other editors (Cursor, Zed, VS Code)
Cursor (MCP settings):
{
"mcpServers": {
"brainlayer": {
"command": "brainlayer-mcp"
}
}
}
Zed (settings.json):
{
"context_servers": {
"brainlayer": {
"command": { "path": "brainlayer-mcp" }
}
}
}
VS Code (.vscode/mcp.json):
{
"servers": {
"brainlayer": {
"command": "brainlayer-mcp"
}
}
}
MCP Tools (12)
Every tool includes ToolAnnotations so agents know which calls are safe to run without confirmation.
| Tool | Type | What it does |
|---|
brain_search | read | Semantic + keyword hybrid search across all memories. Lifecycle-aware. |
brain_store | write | Persist decisions, learnings, mistakes. Auto-importance scoring. Per-agent scoping via agent_id. |
brain_recall | read | Proactive retrieval — session context, summaries, recent work. |
brain_tags | read | Browse tags and discover what's in memory without a query. |
brain_digest | write | Ingest raw content — entity extraction, relations, action items. |
brain_entity | read | Look up knowledge graph entities — type, relations, evidence. |
brain_expand | read | Get a chunk with N surrounding chunks for full context. |
brain_update | write | Update importance, tags, or archive existing memories. |
brain_get_person | read | Person lookup — entity details, interactions, preferences. |
brain_enrich | write | Run LLM enrichment — Gemini, Groq, or local MLX/Ollama. |
brain_supersede | destructive | Replace old memory with new. Safety gate on personal data. |
brain_archive | destructive | Soft-delete with timestamp. Recoverable via direct lookup. |
All 14 legacy brainlayer_* tool names still work as aliases.
Architecture
graph LR
A["Claude Code / Cursor / Zed"] -->|MCP| B["BrainLayer<br/>12 tools"]
B --> C["Hybrid Search<br/>vector + FTS5"]
C --> D["SQLite + sqlite-vec<br/>single .db file"]
B --> KG["Knowledge Graph<br/>entities + relations"]
KG --> D
E["JSONL conversations"] --> W["Real-time Watcher<br/>~1s latency"]
W --> D
I["BrainBar<br/>macOS menu bar"] -->|Unix socket| B
Everything runs locally. Cloud enrichment (Gemini/Groq) and Axiom telemetry are optional.
| Layer | Implementation |
|---|
| Storage | SQLite + sqlite-vec, WAL mode, single .db file |
| Embeddings | bge-large-en-v1.5 (1024 dims, CPU/MPS) |
| Search | Vector similarity + FTS5, merged with Reciprocal Rank Fusion |
| Watcher | Real-time JSONL indexing (~1s), 4-layer content filters, offset-persistent |
| Enrichment | 10 metadata fields per chunk — Groq, Gemini, MLX, or Ollama |
| Knowledge Graph | Entities, relations, co-occurrence extraction, person lookup |
Why BrainLayer?