second-brain-mcp

second-brain MCP Server

A self-maintaining personal knowledge database — powered by MCP, DuckDB, and biological memory models.

---

For anyone who saves more papers, notes, and figures than they could ever re-read. second-brain turns everything you capture into a database that maintains itself — auto-linking related notes, compressing what you stop reading, and keeping every figure searchable by its content. What you saved a year ago is still one query away, at a fraction of the token cost.

Why Does This Exist?

Problem	Solution
📄 You save dozens of papers but can never find the right figure	search_figures("UMAP melanocyte") — returns the exact panel, across every paper you've saved
📑 arXiv gives you the abstract; you need the full paper	Auto-upgrades /abs/ → /html/ — fetches the complete paper with all sections, not just the abstract
🗂 Notes pile up; older ones never get cleaned up	Vault Sleep: low-access notes compress automatically every Sunday while you sleep (60–90% token reduction)
🔗 New notes stay isolated; you forget what's connected	Auto-wikilinks: every saved note is automatically linked to semantically related notes already in your vault
🔎 Semantic search needs a cloud API or Docker stack	Self-hosted nomic-embed-text via llama-server; BM25 fallback when offline
🔒 Every AI memory tool locks you into their format	Pure Markdown vault — sync with Google Drive, iCloud, or git; switch agents anytime
🖼 Figure context is lost when you read a paper	Every figure is downloaded, OCR'd by Claude Vision, and stored in DuckDB — searchable by gene name, p-value, axis label

---

The One-Command Demo

save_article("https://arxiv.org/abs/2405.01234")
  ↓
• /abs/ auto-upgraded to /html/ — full paper, not just abstract
• Full text converted to Markdown
• All figures downloaded + OCR'd by Claude Vision
• Semantic embeddings computed
• Auto-linked to related notes already in your vault   ← auto-wikilinks
• Stored in 30-resources/ — queryable immediately

search_figures("UMAP cluster batch correction")
  ↓
• Returns the exact figure from the exact paper
• Works across your entire saved literature library

---

What Makes It Different

flowchart LR
    subgraph input["📥 Any Content Source"]
        A1["arXiv / PubMed paper"]
        A2["Web article / blog"]
        A3["Local PDF / DOCX"]
        A4["Personal note"]
    end

    subgraph core["⚙️ second-brain-mcp"]
        B1["Markdown note<br/>30-resources/"]
        B2["Figure OCR<br/>+ VLM description"]
        B3["Semantic embedding<br/>+ auto-wikilinks"]
        B4["Ebbinghaus score<br/>ranking"]
        B5["PNG snapshots<br/>60–90% token reduction"]
    end

    subgraph query["🔍 Queryable Knowledge"]
        C1["search_figures<br/>'UMAP melanocyte'"]
        C2["search_notes<br/>'batch correction scRNA'"]
        C3["get_context<br/>top-20 relevant notes"]
    end

    input --> core
    B1 --> B2
    B1 --> B3
    B3 --> B4
    B4 --> B5
    B2 --> C1
    B3 --> C2
    B4 --> C3

Eight things most self-hosted memory tools can't do — combined in one:

Most memory tools…	second-brain
Save a link or PDF, then leave you to read and tag it	🔬 One command builds the database — save_article fetches any URL/PDF, converts to Markdown, downloads & OCRs every figure with Claude Vision, then semantic-indexes it
Store the arXiv abstract you pasted	📑 Full text, not abstracts — /abs/ URLs auto-upgrade to /html/ for the complete paper: methods, results, discussion
Leave new notes isolated until you tag them	🔗 The knowledge graph builds itself — every note is auto-linked to semantically related notes already in your vault
Cost the same whether a note is read daily or never	🧠 Memory that forgets like a brain — Ebbinghaus score ranks by recency × frequency; stale notes compress while you sleep
Search documents, not what's inside the figures	🖼 Figure-level search across your whole library — search_figures("p < 0.001") returns the exact panel from the exact paper
Forget your project decisions between sessions	📋 The AI learns your rules — hot notes auto-extract constraints into memory/rules.md, injected at every session start
Grow more expensive as the vault grows	📉 Token cost shrinks with age — PNG snapshots replace old text at 60–90% compression; frequently-read papers stay full-fidelity
Lock you into their database format	🔓 Zero lock-in — pure Markdown, any MCP agent, sync via any cloud drive or git

---

Cross-Session Continuity — Pick Up Where You Left Off

Every project you work on can be resumed in a new session with full context — no re-explaining, no lost progress.

flowchart LR
    A["🟢 Session Start<br/>get_context()"] --> B["AI receives:<br/>• goals.md — current priorities<br/>• Top-20 recent notes<br/>• Extracted rules"]
    B --> C["Work on project<br/>new_note / search / read"]
    C --> D["🔴 Before ending session<br/>update_goals(...)"]
    D --> E["New session<br/>get_context() again"]
    E --> B

How It Works in Practice

End of session — tell the agent to save state:

Update goals: currently working on the scRNA batch correction pipeline.
Completed: harmony integration. Blocked on: choosing n_components for PCA.
Next session: start from the PCA parameter sweep in 20-areas/research/harmony-notes.md

The agent calls update_goals() and optionally new_note("project", ...) for detailed progress.

Start of next session — just say:

Get context and continue where we left off.

The agent calls get_context() and immediately sees:

• goals.md with the state you saved
• The harmony-notes.md surfaced at the top (recently accessed, high Ebbinghaus score)
• Rules auto-extracted from that note, e.g.:

RULE: use n_components=30 for this dataset — tested 20/30/50, 30 minimises batch effect without losing resolution
RULE: exclude sample CRC_04 — library size outlier confirmed by QC

These rules live in memory/rules.md and are injected at every get_context() call — the AI carries your hard-won decisions forward automatically, without you having to repeat them.

What Gets Persisted

What	Where	Always in context?
Current priorities / blocked items	memory/goals.md	✅ every session
Project progress notes	10-projects/ or 20-areas/	✅ if recently accessed
Decisions and rationale	decisions/	via get_decisions()
Extracted rules from notes	memory/rules.md	✅ every session
Saved papers and figures	30-resources/	via search_notes/figures

This works across any project — bioinformatics analysis, coding, writing, research. Save state with one sentence at the end of a session; resume instantly at the start of the next.

---

Consistent Filing — The Operating Manual

Tools alone don't keep a vault tidy — the agent has to know where each note belongs, how to name it, and what not to touch. second-brain ships a single operating manual (AGENTS.md) that encodes those decisions, so any agent files things the same way every time — no re-explaining your conventions each session.

Agent receives a request
        │
        ▼
get_agent_instructions()   ← returns the full AGENTS.md operating manual
        │
        ▼
Agent now knows, without being told:
  • Filing decision tree   — paper (DOI/author) → 20-areas/research/
                             reference doc      → 30-resources/
                             stock analysis     → finance/  · unsure → 00-inbox/
  • Naming convention      — papers: {YYYY}_{Author}_{ShortTitle}.md
  • Figure rules           — figures/{slug}/fig-NN.png, embedded as ![[…]]
  • Editing discipline     — local edits only, never reorder frontmatter,
                             new notes go through new_note (templated)

Why it matters for efficiency:

Without the manual	With AGENTS.md
You re-explain "papers go here, name them like this" every session	The agent reads it once per session and just does it
Notes drift into inconsistent folders/names; search degrades	Stable structure → semantic + figure search stays reliable
Each agent (local Claude Code, remote MCP, Gemini) behaves differently	One manual, one behaviour — served locally via CLAUDE.md, remotely via get_agent_instructions()

Single source of truth: keep all conventions in the one AGENTS.md the server serves. Forks in a second copy silently diverge — remote agents then act on stale rules. Edit the canonical file only.

---

Example Queries

# Resume a project from last session
get_context()  # → goals + recent notes + rules loaded automatically

# Find a specific figure panel across all saved papers
search_figures("p < 0.001 UMAP cluster")

# Semantic search across all notes
search_notes("single cell integration batch correction")

# Decision records for a specific project
get_decisions("MyProject")

---

Memory Architecture — Biological Analogy

Biological Brain	This System
Hippocampal consolidation during sleep	Vault Sleep: weekly LLM-compression of old low-access notes
Ebbinghaus forgetting curve	Score-based ranking: access_count / ln(age_days)
Visual long-term memory	PNG snapshots — resolution degrades gracefully with age
Associative recall	Semantic search + auto-generated [[wikilinks]]
Sleep-dependent consolidation	launchd cron, runs Sunday 02:00 while you sleep

---

Token Efficiency

Memory that gets cheaper over time — unlike flat-file systems where old notes cost the same forever.

Note age →   fresh (0–3 mo)   3–6 months     6–12 months    1 year+
             ──────────────   ──────────     ───────────    ───────
token cost:  ██████████████   ██████         ████           ██
             ~1,000 tokens    ~400 tokens    ~256 tokens    ~100 tokens
                              ▼ 60%          ▼ 74%          ▼ 90%

Tier assigned by score × age (adaptive). Frequently-accessed notes stay full-text regardless of age.

---

Search Performance

Measured on Apple Silicon MacBook (20-rep average, BM25-only mode).

Vault    BM25-only p50          Hybrid BM25+semantic p50
──────   ─────────────────      ────────────────────────
10 n     ████░░░░░   21 ms      ████████████   37 ms
50 n     ██████░░░   25 ms      █████████████  39 ms
100 n    ███████░░   27 ms      ██████████████ 45 ms

Vault Size	BM25 p50	Hybrid p50	Recall@1	Recall@5	MRR
10 notes	21 ms	37 ms	30%	60%	0.42
50 notes	25 ms	39 ms	70%	90%	0.78
100 notes	27 ms	45 ms	70%	80%	0.73

Hybrid mode adds ~18 ms for embedding lookup. Both modes scale sub-linearly with vault size.

Recall figures at this scale (10–100 notes) carry high sample variance — a single ambiguous query shifts Recall@1 by 10%. Treat them as directional, not as benchmarks against large corpora; the takeaway is that hybrid consistently beats BM25-only on relevance for a fixed query set.

---

System Architecture

┌─────────────────────────────────────────────────────┐
│                    AI Agent Layer                    │
│         Claude Code · Gemini CLI · Any MCP           │
└──────────────────────┬──────────────────────────────┘
                       │ MCP Protocol (27 tools)
┌──────────────────────▼──────────────────────────────┐
│               Layer 2 — MCP Server                   │
│              mcp_second_brain/server.py              │
│  get_context · search_notes · save_article · … (27)  │
└──────┬───────────────┬────────────────┬─────────────┘
       │               │                │
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│  vault_sleep│ │  vault_db   │ │  figures    │
│  compress   │ │  DuckDB FTS │ │  PNG snap   │
│  Phase 3–9  │ │  + semantic │ │  OCR · VLM  │
└──────┬──────┘ └──────┬──────┘ └─────────────┘
       │               │
┌──────▼───────────────▼──────────────────────────────┐
│               Layer 0 — Markdown Vault               │
│   00-inbox · 10-projects · 20-areas · 30-resources   │
│   40-archive · decisions · memory · templates        │
│         (syncs via Google Drive / iCloud / git)      │
└─────────────────────────────────────────────────────┘

---

Vault Sleep — Auto-compression Flow

Every Sunday 02:00 (launchd, no interaction needed)
        │
        ▼
 sync_index + embeddings
        │
        ▼  age > 90d AND Ebbinghaus score ≤ 0.5
 ┌──────────────────────────────────────┐
 │         Adaptive Tier Selection      │
 │  score > 1.5  →  text  (keep full)  │  ← frequently-read: never compressed
 │  score > 0.8  →  large  ~400 tokens │
 │  score > 0.3  →  base   ~256 tokens │
 │  otherwise    →  small  ~100 tokens │
 └────────────────┬─────────────────────┘
                  │
  Gemini CLI → Claude CLI → naive   (auto-fallback, no LLM required)
                  │
    compressed → vault  /  original → 40-archive/  /  snapshot → .png

---

MCP Tools (27 total)

Tool	Description
get_context	Session start: goals + top-20 Ebbinghaus-ranked notes + auto-rules
save_article	Fetch URL/PDF → Markdown + auto-extract figures
search_notes	Hybrid BM25 + semantic search across all notes
search_figures	Search figure OCR text / VLM descriptions
search_news_tool	Search cnews morning briefs and financial news by keyword
extract_figures_for	Manually trigger figure extraction for a saved article
read_note	Read note + record access (updates Ebbinghaus score)
read_note_as_image	Return PNG snapshot for token-efficient reading
new_note	Create note with correct template and folder by type
get_decisions	List ADR decision records, optionally filtered by project
update_goals	Update memory/goals.md
sync_index	Rebuild DuckDB index from vault files
index_stats	Show note counts by type
vault_sleep	Compress old low-activity notes (dry_run=True by default)
sleep_status	Show compression candidates without acting
snapshot_note_tool	Render note to PNG at chosen resolution tier
extract_rules_tool	Extract L3 rules from frequently-accessed notes
consolidate_tool	Merge semantically similar notes into one abstract note
update_links_tool	Refresh auto-generated [[wikilinks]]
prune_archive_tool	Delete archived originals that have a PNG snapshot
find_related_notes	Find semantically related notes by cosine similarity (finance & knowledge management)
search_grouped	Hybrid search returning knowledge notes + cnyes morning briefs in one call
top_notes	Rank notes by Ebbinghaus score or recency — find your most-engaged knowledge nodes
update_note	Overwrite an existing note with new content (auto-reindexes)
append_to_note	Append content to end of an existing note — safe, never loses existing text
init_vault	Create or repair vault directory structure and templates
get_agent_instructions	Return full AGENTS.md operating manual — call at remote session start to learn vault SOP

---

Test Results

tests/test_figures.py      24 passed   (OCR, snapshots, VLM)
tests/test_server.py       30 passed   (MCP tools, path safety)
tests/test_vault_db.py     73 passed   (FTS, semantic search, embeddings)
tests/test_vault_sleep.py  46 passed   (compression, consolidation, rules, prune)
────────────────────────────────────────
173 passed in 7.51s

---

Installation

⚠️ Install from source for now. The source tree is packaged (v0.2.0, with a working python -m mcp_second_brain entry point), but the PyPI release is still catching up — the published mcp-second-brain is 0.1.0, so pip install lands an outdated build. Until the fresh release ships, use the Development Install (clone) path. Self-hosting across your own machines from a synced source tree? See NEW_MACHINE_SETUP.md.

Prerequisites

Dependency	Required	Notes
Python 3.11+	✅
Playwright	✅	PNG snapshot rendering
uv	Dev only	Only needed for Development Install path
llama-server or Ollama	Optional	Enables semantic search; BM25 fallback if absent
nomic-embed-text-v1.5.Q8_0.gguf	Optional	~300 MB — needed for llama-server path only
ANTHROPIC_API_KEY	Optional	Better compression quality in vault_sleep; naive fallback if absent

Vault structure is auto-created on first server start — no manual mkdir needed.

---

macOS / Linux — Quick Start

Step 1 — Install

pip install mcp-second-brain
playwright install chromium

Step 2 — Register with your AI agent

Claude Code (CLI) — global, works in any project:

claude mcp add --scope user second-brain \
  --env SECOND_BRAIN_PATH=~/second-brain \
  -- python -m mcp_second_brain

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "second-brain": {
      "command": "python",
      "args": ["-m", "mcp_second_brain"],
      "env": { "SECOND_BRAIN_PATH": "/Users/yourname/second-brain" }
    }
  }
}

Step 3 — First run

Start your agent and say:

init_vault

The server auto-creates all directories and templates on startup. Call init_vault explicitly to verify or repair the structure.

---

Windows — Quick Start

Step 1 — Install Python and the package

# Install Python 3.11+ from python.org, or via winget:
winget install Python.Python.3.11

pip install mcp-second-brain
playwright install chromium

Step 2 — Choose a vault location

# Local folder:
$vault = "C:\Users\$env:USERNAME\second-brain"

# Or a cloud-synced folder (Google Drive, OneDrive, etc.):
$vault = "G:\My Drive\second-brain"

The vault directories and templates are created automatically when the server first starts. No manual setup needed.

Step 3 — Register with your AI agent

Claude Code (VSCode extension) — create .mcp.json in your vault folder:

{
  "mcpServers": {
    "second-brain": {
      "command": "python",
      "args": ["-m", "mcp_second_brain"],
      "env": { "SECOND_BRAIN_PATH": "C:\\Users\\YourName\\second-brain" }
    }
  }
}

Claude Desktop — add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "second-brain": {
      "command": "python",
      "args": ["-m", "mcp_second_brain"],
      "env": { "SECOND_BRAIN_PATH": "C:\\Users\\YourName\\second-brain" }
    }
  }
}

Gemini CLI / other IDEs — edit %USERPROFILE%\.gemini\mcp_config.json (or IDE-specific config):

{
  "mcpServers": {
    "second-brain": {
      "command": "C:\\Users\\YourName\\.venvs\\mcp-second-brain\\Scripts\\python.exe",
      "args": ["-m", "mcp_second_brain"],
      "env": { "SECOND_BRAIN_PATH": "C:\\Users\\YourName\\second-brain" }
    }
  }
}

Tip: Use a dedicated venv at C:\Users\YourName\.venvs\mcp-second-brain\ (local SSD) rather than a venv on a network drive. Python loads thousands of small files at startup — on a cloud drive this causes 15–30 s delays and context deadline exceeded errors.

Step 4 — Semantic search (optional, Windows)

Ollama is the easiest path on Windows:

winget install Ollama.Ollama
ollama pull nomic-embed-text

Then add to the env block of your MCP config:

"EMBED_URL": "http://localhost:11434/v1/embeddings",
"EMBED_PORT": "11434"

Ollama starts automatically with Windows. No extra configuration needed.

Alternatively, build llama.cpp for Windows and register it as a scheduled task:

# Register llama-server as a login-triggered scheduled task:
$exe  = "C:\Users\$env:USERNAME\llama.cpp\build\bin\llama-server.exe"
$model = "C:\Users\$env:USERNAME\nomic-embed-text-v1.5.Q8_0.gguf"
$args = "-m `"$model`" --port 11435 --embedding --pooling mean -np 4 -c 2048 --log-disable"

$action   = New-ScheduledTaskAction -Execute $exe -Argument $args
$trigger  = New-ScheduledTaskTrigger -AtLogOn
$settings = New-ScheduledTaskSettingsSet -RestartCount 5 -RestartInterval (New-TimeSpan -Minutes 1)
Register-ScheduledTask -TaskName "llama-embed" -Action $action -Trigger $trigger `
  -Settings $settings -RunLevel Highest -Force

Step 5 — Weekly vault maintenance (optional, Windows)

# Run vault_sleep every Sunday at 02:00
$pythonExe = "C:\Users\$env:USERNAME\.venvs\mcp-second-brain\Scripts\python.exe"
$serverPy  = "C:\path\to\second-brain-mcp\launchd\run_sleep.py"
$vaultPath = "C:\Users\$env:USERNAME\second-brain"

$action  = New-ScheduledTaskAction -Execute $pythonExe -Argument "`"$serverPy`"" `
  -WorkingDirectory (Split-Path $serverPy)
$trigger = New-ScheduledTaskTrigger -Weekly -DaysOfWeek Sunday -At 2am
$env_var = [System.Environment]::SetEnvironmentVariable(
  "SECOND_BRAIN_PATH", $vaultPath, "Machine")
Register-ScheduledTask -TaskName "vault-sleep" -Action $action -Trigger $trigger -Force

---

Development Install (clone)

git clone https://github.com/ddmanyes/second-brain-mcp
cd second-brain-mcp
uv sync
uv run playwright install chromium

Register with Claude Code:

# macOS / Linux
claude mcp add --scope user second-brain \
  --env SECOND_BRAIN_PATH=~/second-brain \
  -- uv run --project /path/to/second-brain-mcp python -m mcp_second_brain

# Windows (PowerShell)
claude mcp add --scope user second-brain `
  --env SECOND_BRAIN_PATH="C:\Users\$env:USERNAME\second-brain" `
  -- uv run --project C:\path\to\second-brain-mcp python -m mcp_second_brain

Environment Variables

Variable	Default	Description
SECOND_BRAIN_PATH	~/second-brain	Path to your vault directory
EMBED_URL	http://localhost:11435/v1/embeddings	Embedding server endpoint
EMBED_MODEL	nomic-embed-text	Embedding model name
EMBED_PORT	11435	llama-server port (use 11434 for Ollama)

Auto-start (macOS, optional)

Weekly vault maintenance (Sunday 02:00) is wired up by the bundled installer — it generates the launchd plists from templates and loads them, using your local venv:

SECOND_BRAIN_PATH=~/second-brain bash launchd/install.sh

For an always-on embedding server, adapt the reference plist:

cp examples/launchd/com.yourname.llama-embed.plist ~/Library/LaunchAgents/
# Edit paths inside the file, then:
launchctl load ~/Library/LaunchAgents/com.yourname.llama-embed.plist

---

Troubleshooting

Symptom	Likely cause	Fix
new_note returns Error: template not found	Templates missing from vault	Run init_vault — the server copies bundled templates automatically
Semantic search silently falls back to BM25	Embedding server not running	Start Ollama (ollama serve) or llama-server; check with curl localhost:11435/health (or port 11434 for Ollama)
read_note_as_image / snapshots fail	Playwright chromium not installed	pip install playwright && playwright install chromium
vault_sleep never compresses anything	No ANTHROPIC_API_KEY → naive fallback, or no eligible notes	Export ANTHROPIC_API_KEY; only notes >90 days old with Ebbinghaus score ≤ 0.5 are candidates — run sleep_status to see them
Agent sees no notes / empty results	Index not built	Run sync_index once after install (and after bulk file changes)
Notes land in the wrong place	SECOND_BRAIN_PATH unset or wrong	Set it in your MCP config env block; defaults to ~/second-brain
Tools unavailable when working in other project folders	Installed as local config instead of user scope	Re-register with --scope user: claude mcp remove second-brain -s local && claude mcp add --scope user second-brain ...
Windows: MCP server times out on connect (context deadline exceeded)	Python venv is on a network/cloud drive	Move the venv to local SSD (e.g. C:\Users\Name\.venvs\) — cloud drives cause 15–30 s startup delay
Windows: Semantic search returns no results after sync_index	Ollama not running	ollama serve in a terminal, or install Ollama with auto-start via winget

---

Vault Structure

vault/
├── 00-inbox/          # Unprocessed captures — clear daily
├── 10-projects/       # Active projects
├── 20-areas/
│   ├── research/      # Ongoing research domains
│   ├── coding/        # Dev tools and workflows
│   └── consolidated/  # Auto-merged similar notes (Phase 8)
├── 30-resources/      # ← Papers and articles (save_article writes here)
├── 40-archive/        # Compressed originals (auto-managed by vault_sleep)
├── decisions/         # Architecture Decision Records (ADR format)
├── memory/
│   ├── goals.md       # Current priorities — injected at every session start
│   ├── index.md       # Vault map
│   └── rules.md       # Auto-extracted L3 rules — injected at every session start
└── templates/         # Note templates (note, decision, project, research)

---

Running Tests

uv run pytest tests/ -v
uv run python benchmark.py --quick --markdown   # search latency + accuracy report

---

References & Acknowledgements

Papers That Directly Inspired This Project

Paper	Where Used
Do Language Models Need Sleep? Offline Recurrence for Improved Online Inference (2026)	Phase 3 Vault Sleep — hippocampal replay as batch memory consolidation
Experience Compression Spectrum: Unifying Memory, Skills, and Rules in LLM Agents (2026)	Phase 9 adaptive tier — score × age dual-axis; addresses the "missing diagonal" in existing systems
DeepSeek-OCR: Contexts Optical Compression (2025)	Phase 4 PNG tiers — image as compressed medium, 10× compression at 97% fidelity
MemOCR: Layout-Aware Visual Memory for Efficient Long-Horizon Reasoning (2026)	Phase 4 vision API — Playwright render → VLM reading pipeline
Active Context Compression: Autonomous Memory Management in LLM Agents (2026)	Phase 3 design comparison — session-level vs. nightly batch consolidation
SimpleMem: Efficient Lifelong Memory for LLM Agents (2026)	Phase 8 consolidation — 3-stage semantic compression, 30× token reduction
Memory for Autonomous LLM Agents: Mechanisms, Evaluation, and Emerging Frontiers (2026)	Architecture positioning — mechanisms, evaluation, and frontiers

Cognitive Science Foundations

• Ebbinghaus, H. (1885). Über das Gedächtnis. — forgetting curve; basis for access_count / ln(age_days + 1)
• Stickgold, R. (2005). Nature, 437, 1272–1278. — sleep-dependent memory consolidation

Built With

MarkItDown · DuckDB · llama.cpp · nomic-embed-text · FastMCP · Playwright · Anthropic Claude API

---

Known Issues & Fixes

WAL corruption (Failure while replaying WAL file)

Cause: DuckDB write was interrupted mid-transaction (IDE restart, pkill -9, or machine sleep).
Symptom: MCP server crashes on startup; every DB operation fails.
Fix:

rm -f ~/.second-brain/vault.db ~/.second-brain/vault.db.wal

Restart the server — it will rebuild a clean DB. Run sync_index to re-index your vault.

Note: If running inside a sandboxed IDE (e.g. Antigravity), the agent cannot delete ~/.second-brain/. Run the command in your local Terminal, or ask Claude Code (VSCode extension) which has full shell access.

---

vault.db created in the wrong directory

Cause: the server was launched with a non-home working directory; DuckDB created vault.db relative to cwd.
Symptom: ~/.second-brain/vault.db is tiny (< 1 MB) but a large vault.db exists elsewhere.
Fix:

# Find the real vault.db
find ~ -name "vault.db" -size +1M 2>/dev/null

# Move it to the correct location
cp /path/to/found/vault.db ~/.second-brain/vault.db

Running from a cloud-synced source tree (Google Drive / iCloud / OneDrive) across several of your own machines? Keep the venv on local disk (~/.venvs/), never inside the synced folder — sync breaks venv symlinks. That self-hosting model is documented in NEW_MACHINE_SETUP.md.

---

Contributing

PRs and Issues welcome. Please open an issue first to discuss significant changes.

---

License

MIT License — © 2026 Chan Chi Ru. See LICENSE.