io.github.ddmanyes/mcp-second-brain MCP Server

This MCP server implements a “self-maintaining knowledge vault” exposed to AI agents. It provides figure-level search, auto-wikilinks, and memory compression, and is presented as a plain-Markdown vault powered by MCP.

🛠️ Key Features

Self-maintaining personal knowledge base
Figure-level search
Auto-wikilinks
Memory compression
Plain-Markdown vault, powered by MCP

🚀 Use Cases

Retrieve knowledge from a local, plain-Markdown vault
Use figure-level search to find relevant content
Link knowledge automatically via wikilinks
Compress memory to manage stored information for AI agents

⚡ Developer Benefits

MCP-compatible interface for AI agents
Documentation and project metadata include CI workflow status, Python ≥ 3.11 requirement, and MIT licensing

⚠️ Limitations

Server description excerpt does not specify supported tools, endpoints, authentication, or deployment details

second-brain MCP Server

A self-maintaining personal knowledge base for AI agents — a plain-Markdown vault, powered by MCP.

Python 3.11–3.13

📖 English · 繁體中文

A local knowledge base your AI agent can read, write, and maintain on its own. Save a paper or note with one command — second-brain converts it to Markdown, OCRs every figure, embeds it for semantic search, and auto-links it to related notes. Notes you stop reading compress themselves over time, so recall stays cheap as the vault grows.

Everything is plain Markdown — sync via Google Drive / iCloud / git, switch agents anytime, zero lock-in.

Highlights

One command saves anything — save_article(url_or_pdf) fetches, converts to Markdown, OCRs figures (Claude Vision), embeds, and auto-links.
Figure-level search — search_figures("UMAP melanocyte") returns the exact panel across your whole library.
Self-organizing — new notes auto-link to related ones; frequently-read notes extract reusable rules.
Memory that forgets like a brain — Ebbinghaus ranking; stale notes auto-compress (60–90% fewer tokens).
Read-only housekeeping audit — inspect article metadata, links, exact duplicate candidates, inbox age, and source freshness without changing the vault.
Session continuity — get_context() reloads goals + top notes + rules at the start of every session.
Pluggable backend — DuckDB (default, offline) or Postgres + pgvector (central, multi-machine). Self-hosted embeddings optional; BM25 fallback when offline.

Quick Start (Claude Code)

bash

pip install mcp-second-brain
playwright install chromium

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

The vault directory and templates are created on first run. Then tell your agent init_vault to verify.

⚠️ PyPI currently lags the source tree. For the newest build — plus Claude Desktop, Windows, and multi-machine / central-server setups — see NEW_MACHINE_SETUP.md.

Core Tools

Tool	What it does
`auth_context`	Read the authenticated caller's canonical UUID, role, and RBAC state
`get_context`	Session start — goals + top-ranked notes + auto-rules
`save_article`	URL / PDF → Markdown + figures + embeddings
`search_notes` / `search_figures`	Hybrid BM25 + semantic search (note text / figure content)
`search_articles`	Structured author, ORCID, DOI/PMID/PMCID and year search for papers
`audit_article_records`	Bounded, read-only article housekeeping and social-source freshness report
`new_note` / `update_note` / `append_to_note`	Create & edit notes (auto-filed, auto-indexed, auto-linked)
`vault_sleep`	Compress old, low-activity notes
`get_agent_instructions`	Serve the full filing SOP (AGENTS.md) to remote agents

Full tool reference (46 tools) lives in AGENTS.md.

Use search_notes when you need content, health_check when the server or index may be unhealthy, and audit_article_records when you need a housekeeping report. Audit results never merge, archive, or delete notes automatically.

How It Works

text

Any source (paper · PDF · web · note)
        │   save_article · new_note
        ▼
Markdown vault  ──►  index  (DuckDB, or Postgres + pgvector)
  00-inbox/            • BM25 + semantic search
  10-projects/         • figure OCR + vision descriptions
  20-areas/            • auto-wikilinks between related notes
  30-resources/        • Ebbinghaus ranking → weekly auto-compression
  decisions/ memory/
        │
        ▼
Your AI agent queries it — search_notes · search_figures · get_context

The vault is the source of truth; the index is rebuildable anytime (sync_index). Filing conventions live in one operating manual — AGENTS.md — served to any agent via get_agent_instructions(), so every agent files things the same way without being re-taught.

Vault Structure

text

vault/
├── 00-inbox/       Unprocessed captures
├── 10-projects/    Active projects
├── 20-areas/       Ongoing research / coding domains
├── 30-resources/   Papers & articles (save_article writes here)
├── 40-archive/     Auto-compressed originals
├── decisions/      Architecture Decision Records
├── memory/         goals.md · rules.md  (injected every session)
└── templates/      Note templates

Legacy author metadata

search_articles reads structured frontmatter, so older article notes without authors are not guessed from body text or references. A bounded two-phase CLI can prepare those notes safely: first create and review a manifest, then apply it separately.

bash

python -m mcp_second_brain.author_backfill \
  --vault "<vault>" --limit 20 --out /tmp/author-backfill.json
python -m mcp_second_brain.author_backfill \
  --vault "<vault>" --apply --manifest /tmp/author-backfill.json

Apply on the central writer host only. Each entry requires an exact DOI/PMID/PMCID or title match and unchanged content/body hashes; successful writes are reindexed.

Documentation

AGENTS.md — filing SOP, naming conventions, full tool reference (single source of truth)
NEW_MACHINE_SETUP.md — source install, self-hosting, multi-machine central server, API keys
CONTEXT.md — domain model / ubiquitous language

Design Notes

Inspired by biological memory: the Ebbinghaus forgetting curve (access_count / ln(age_days)) for ranking, and sleep-dependent consolidation (weekly LLM compression of low-access notes). Built with MarkItDown · DuckDB · pgvector · FastMCP · Playwright · Claude API.

second-brain MCP