second-brain
A universal memory layer for AI coding agents. Ingests conversation history from Claude Code and Cursor into a knowledge store with vector and lexical search, then serves it via MCP (Model Context Protocol) so any AI agent can recall what you've discussed, decided, and built across projects and machines.
Why
Every AI coding tool keeps its own conversation history locked in its own format. Claude Code stores JSONL in ~/.claude/projects/, Cursor keeps JSONL in ~/.cursor/projects/. None of them talk to each other, and none of them let you search across sessions. If you discussed an architecture decision with Claude last week and ask Cursor about it today, you start from zero.
second-brain fixes this by creating a single knowledge store that ingests from all your AI tools, embeds everything for semantic search, tracks relationships between memories (reinforces, contradicts, supersedes), and exposes it all through MCP so any connected agent can recall context from any previous conversation.
Memory Pipeline
- File watcher detects new
.jsonlin~/.claude/projects/(10s debounce) - Hash check skips unchanged files
- Adapter parses tool-specific format into conversation chunks
- Heuristic filter (
is_memorable) rejects noise: tool output, short lines, code-only blocks - Dedup checks first 128 chars against existing memories
- Embed generates 384-dim BGE vector (local)
- Store writes to SQLite with conversation and entity relations
- Consolidate (manual) distills raw memories via LLM into concise knowledge facts, then cleans up raw
Crates
| Crate | Description |
|---|---|
second-brain-core |
SQLite storage, vector and lexical indexes, BGE-small-en-v1.5 embeddings, QueryEngine, schema types |
second-brain-adapters |
Parsers for Claude Code JSONL and Cursor JSONL formats |
second-brain-sync |
SSH transport, JSONL change log export/import, conflict resolution |
second-brain-mcp |
Thin MCP stdio server, proxies to daemon over HTTP |
second-brain-cli |
CLI binary for setup, ingest, recall, sync, consolidation |
second-brain-api |
HTTP daemon: owns DB, embedder, file watcher, serves all endpoints on port 7200 |
Install
setup handles everything: creates ~/.second-brain/, installs a systemd user service, registers the MCP server with Claude Code (claude mcp add --scope user), starts the daemon, and runs the first ingest.
Or build from source:
Usage
Ingest conversations
# Ingest Claude Code history
# Ingest Cursor history
# Ingest everything
Ingest reads from standard paths (~/.claude/projects/ for Claude Code, ~/.cursor/ for Cursor), parses conversations, extracts memories with types (episodic, semantic, procedural), generates 384-dim embeddings, and stores everything in SQLite with entity extraction and relationship tracking.
Recall
Recall uses a weighted scoring function: 50% vector cosine similarity, 30% graph relevance (relation types and counts), 20% recency (exponential decay + access frequency). Results below a 0.59 similarity threshold are filtered out.
MCP server
sb setup registers this automatically. To register it by hand:
MCP tools available:
| Tool | Description |
|---|---|
recall |
Semantic search with graph-boosted scoring |
remember |
Store a new memory with embedding |
ingest |
Trigger conversation ingestion |
associate |
Create explicit relations between memories |
forget |
Remove a memory by ID |
context |
Get a memory with its graph neighborhood |
status |
DB stats: memory count, index health, sync state |
Sync
Bidirectional sync between machines over SSH using a sequence-numbered JSONL change log.
# Full bidirectional sync with a peer
# Manual export/import
|
# Check sync state
# Backfill sync log for data that predates the log
Sync resolves conflicts with last-write-wins on memory updates (newer last_accessed wins). Conversations, entities, and relations use create-or-skip semantics.
Consolidation
Distill raw conversation memories into higher-level summaries using a local LLM (Ollama).
Uses any OpenAI-compatible chat completions endpoint (llama.cpp, Ollama, vLLM). When a distillate drops an exact identifier its excerpt names (a path, backticked command, ticket id or number), the default --guard retry asks the model once to rewrite it with them and keeps the rewrite only if it loses nothing the first draft had. After consolidation, raw memories are automatically cleaned up. Distilled memories are the primary knowledge store, linked to sources via DistilledFrom relations.
Daily Pipeline
End-of-day automation: consolidate memories via local LLM.
Requirements:
- Local LLM at
localhost:8081(llama.cpp, Ollama, vLLM) or pass--llm-url - Default model:
gemma-4-E4B-it-Q4_K_M(override with--model)
Memory Types
Memories are classified at ingest time (heuristic, no LLM):
| Type | Trigger patterns |
|---|---|
| Task | TODO, FIXME, action item, remaining, need to |
| Decision | decided, chose, went with, agreed, selected |
| Architecture | architecture, data model, schema, the approach |
| Debugging | root cause, the bug, the issue is, error: |
| Question | contains "?" + interrogative word |
| Procedural | steps:, to do this, run, install, how to |
| Episodic | deployed, shipped, migrated, found that |
| Semantic | catch-all factual knowledge |
Priority order: first match wins (Task → Decision → ... → Semantic).
Configuration
| Env var | Default | Description |
|---|---|---|
SECOND_BRAIN_DB |
~/.second-brain/brain.db |
Path to the SQLite database |
SECOND_BRAIN_API |
http://127.0.0.1:7200 |
Daemon URL (used by MCP server and CLI) |
SECOND_BRAIN_BIND |
127.0.0.1:7200 |
Daemon listen address |
SECOND_BRAIN_RERANK_DOC_CHARS |
1024 |
Cross-encoder document character budget; 0 disables truncation |
SECOND_BRAIN_RERANK_POOL |
min(cores, 4) |
Rerank session pool size (concurrency headroom, not throughput) |
SECOND_BRAIN_RERANK_CHECKOUT_SECS |
30 |
Seconds to wait for a free rerank session before falling back to the non-reranked hybrid path |
RUST_LOG |
- | Tracing filter (e.g. info, second_brain_mcp=debug) |
Query scoring
The QueryEngine combines three signals:
- Vector similarity (weight: 0.5): cosine distance between query embedding and memory embedding using BGE-small-en-v1.5 (384 dimensions)
- Graph relevance (weight: 0.3): based on relation types connected to the memory. Reinforces (+0.3), RelatesTo (+0.2 * strength), DistilledFrom (+0.15), Mentions (+0.1), DerivedFrom (+0.05), Contradicts (-0.1), Supersedes (-0.2)
- Recency (weight: 0.2): exponential decay over 30 days plus a logarithmic access frequency boost
Weights are configurable via QueryEngine::with_weights(vector, graph, recency).
Graph schema
Relation types:
RELATES_TO(Memory -> Memory): semantic relationship with strengthREINFORCES(Memory -> Memory): one memory strengthens anotherCONTRADICTS(Memory -> Memory): conflicting information with resolutionSUPERSEDES(Memory -> Memory): newer information replaces olderDISTILLED_FROM(Memory -> Memory): consolidation linkDERIVED_FROM(Memory -> Conversation): provenance trackingMENTIONS(Memory -> Entity): entity extraction links
Dependencies
- fastembed 5 for BGE-small-en-v1.5 embeddings (384-dim, runs locally, no API calls)
- Rust 1.85+
License
MIT