second-brain MCP

io.github.ddmanyesPublished by GitHub account ddmanyesv0.1.0Updated Oct 24, 2026

Self-maintaining knowledge vault: figure-level search, auto-wikilinks, and memory compression.

The publisher's own server: BrainDog

VerifiedSTDIODesktop onlyWeb Search & ScrapingFiles & StorageKnowledge & Memory

Overview

AI-generated overview

A local Markdown knowledge vault MCP server that lets an AI assistant save articles and PDFs, search notes and figures, and maintain linked, compressed memory.

What you can do
Save sources: fetch a URL or PDF, convert to Markdown, OCR figures and embed them into the vault, or create and edit notes directly with auto-filing and auto-linking. Search: hybrid keyword and semantic search over note text and figure content, plus structured paper search by author, DOI, PMID, PMCID or year. Session context: reload goals, top-ranked notes and auto-rules at the start of a session, and serve the filing manual to agents. Housekeeping: read-only audits of article metadata, links, duplicates and source freshness, and compression of stale, low-activity notes. Maintenance: rebuild the search index and check server health.
When to use it
Useful when you want an assistant to build and maintain a personal research or reading vault over time, capturing papers and web articles and recalling them later by content or figure. Suited to single-user local setups or a self-hosted central server shared across machines.
Requirements
Runs locally as a Python package installed with pip, started as a module over stdio. Needs a vault directory path set via the SECOND_BRAIN_PATH environment variable, created on first run. Playwright with Chromium is needed for fetching pages; figure OCR uses Claude Vision, and the README mentions API keys for self-hosting. Default storage is offline DuckDB; Postgres with pgvector is optional.
Before you install
The assistant writes into your vault: notes are created, edited, auto-linked and old notes compressed, so review changes. Figure OCR and weekly compression send content to the Claude API, a third party. The README warns the PyPI package lags the source tree. A separate author-backfill command writes metadata and should only be applied on the central writer host.

Installation

In SourceWeft

  1. Open second-brain MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

second-brain MCP Server

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

[CI] [Python 3.11–3.13] [License: MIT]

📖 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-brainplaywright 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

ToolWhat it does
auth_contextRead the authenticated caller's canonical UUID, role, and RBAC state
get_contextSession start — goals + top-ranked notes + auto-rules
save_articleURL / PDF → Markdown + figures + embeddings
search_notes / search_figuresHybrid BM25 + semantic search (note text / figure content)
search_articlesStructured author, ORCID, DOI/PMID/PMCID and year search for papers
audit_article_recordsBounded, read-only article housekeeping and social-source freshness report
new_note / update_note / append_to_noteCreate & edit notes (auto-filed, auto-indexed, auto-linked)
vault_sleepCompress old, low-activity notes
get_agent_instructionsServe 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.jsonpython -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.

License

MIT © 2026 Chan Chi Ru. See LICENSE.

Source: README.md at commit 0e08505

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Brain integrations

BrainDog

dog.brainOfficial publisher

BrainDog is a hosted record of projects, decisions and money that connected AI agents read before starting work and write their results into.

Streamable HTTPWeb executableAuth
FinanceCredential requiredNov 5, 2026

Codebase Brain

Published by GitHub account Nomannazir

Indexes a local or public git codebase so an assistant can search it, trace git history, check change impact and find stale docs, all with path:line citations.

STDIODesktop only
Developer ToolsNot validated yetNov 7, 2026

Personal Brain

Published by GitHub account zhang-liz

Gives an AI assistant memory of your professional network, stored as a graph in FalkorDB, so it can look up contacts, find people by topic, and save who you…

STDIODesktop only
Databases3 toolsNov 6, 2026

Second Brain

Published by GitHub account ara-5

Shared Graph-RAG memory for AI agents: markdown vault, wikilink recall, tasks, messaging.

STDIODesktop only
AI & ML12 toolsNov 7, 2026

Make0 Brain

Published by GitHub account make0-official

Local, offline memory server that gives Claude Code, Cursor, Codex and other MCP agents one shared, versioned store of durable facts.

STDIODesktop only
AI & MLNot validated yetNov 7, 2026