{
  "markdown": "<!-- mcp-name: io.github.ddmanyes/mcp-second-brain -->\n\n# second-brain MCP Server\n\n**A self-maintaining personal knowledge base for AI agents — a plain-Markdown vault, powered by MCP.**\n\n[![CI](https://github.com/ddmanyes/second-brain-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ddmanyes/second-brain-mcp/actions/workflows/ci.yml)\n[![Python ≥ 3.11](https://img.shields.io/badge/Python-%E2%89%A53.11-blue)](https://www.python.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-lightgrey)](LICENSE)\n\n📖 English · [繁體中文](README.zh.md)\n\n---\n\nA 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.\n\nEverything is plain Markdown — sync via Google Drive / iCloud / git, switch agents anytime, **zero lock-in**.\n\n## Highlights\n\n- **One command saves anything** — `save_article(url_or_pdf)` fetches, converts to Markdown, OCRs figures (Claude Vision), embeds, and auto-links.\n- **Figure-level search** — `search_figures(\"UMAP melanocyte\")` returns the exact panel across your whole library.\n- **Self-organizing** — new notes auto-link to related ones; frequently-read notes extract reusable rules.\n- **Memory that forgets like a brain** — Ebbinghaus ranking; stale notes auto-compress (60–90% fewer tokens).\n- **Read-only housekeeping audit** — inspect article metadata, links, exact duplicate candidates, inbox age, and source freshness without changing the vault.\n- **Session continuity** — `get_context()` reloads goals + top notes + rules at the start of every session.\n- **Pluggable backend** — DuckDB (default, offline) or Postgres + pgvector (central, multi-machine). Self-hosted embeddings optional; BM25 fallback when offline.\n\n## Quick Start (Claude Code)\n\n```bash\npip install mcp-second-brain\nplaywright install chromium\n\nclaude mcp add --scope user second-brain \\\n  --env SECOND_BRAIN_PATH=~/second-brain \\\n  -- python -m mcp_second_brain\n```\n\nThe vault directory and templates are created on first run. Then tell your agent `init_vault` to verify.\n\n> ⚠️ 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](NEW_MACHINE_SETUP.md)**.\n\n## Core Tools\n\n| Tool | What it does |\n| :--- | :--- |\n| `get_context` | Session start — goals + top-ranked notes + auto-rules |\n| `save_article` | URL / PDF → Markdown + figures + embeddings |\n| `search_notes` / `search_figures` | Hybrid BM25 + semantic search (note text / figure content) |\n| `audit_article_records` | Bounded, read-only article housekeeping and social-source freshness report |\n| `new_note` / `update_note` / `append_to_note` | Create & edit notes (auto-filed, auto-indexed, auto-linked) |\n| `vault_sleep` | Compress old, low-activity notes |\n| `get_agent_instructions` | Serve the full filing SOP (AGENTS.md) to remote agents |\n\nFull tool reference (40 tools) lives in **[AGENTS.md](AGENTS.md)**.\n\nUse `search_notes` when you need content, `health_check` when the server or index may be\nunhealthy, and `audit_article_records` when you need a housekeeping report. Audit results\nnever merge, archive, or delete notes automatically.\n\n## How It Works\n\n```text\nAny source (paper · PDF · web · note)\n        │   save_article · new_note\n        ▼\nMarkdown vault  ──►  index  (DuckDB, or Postgres + pgvector)\n  00-inbox/            • BM25 + semantic search\n  10-projects/         • figure OCR + vision descriptions\n  20-areas/            • auto-wikilinks between related notes\n  30-resources/        • Ebbinghaus ranking → weekly auto-compression\n  decisions/ memory/\n        │\n        ▼\nYour AI agent queries it — search_notes · search_figures · get_context\n```\n\nThe **vault is the source of truth**; the index is rebuildable anytime (`sync_index`). Filing conventions live in one operating manual — [AGENTS.md](AGENTS.md) — served to any agent via `get_agent_instructions()`, so every agent files things the same way without being re-taught.\n\n## Vault Structure\n\n```text\nvault/\n├── 00-inbox/       Unprocessed captures\n├── 10-projects/    Active projects\n├── 20-areas/       Ongoing research / coding domains\n├── 30-resources/   Papers & articles (save_article writes here)\n├── 40-archive/     Auto-compressed originals\n├── decisions/      Architecture Decision Records\n├── memory/         goals.md · rules.md  (injected every session)\n└── templates/      Note templates\n```\n\n## Documentation\n\n- **[AGENTS.md](AGENTS.md)** — filing SOP, naming conventions, full tool reference (single source of truth)\n- **[NEW_MACHINE_SETUP.md](NEW_MACHINE_SETUP.md)** — source install, self-hosting, multi-machine central server, API keys\n- **[CONTEXT.md](CONTEXT.md)** — domain model / ubiquitous language\n\n## Design Notes\n\nInspired 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](https://github.com/microsoft/markitdown) · [DuckDB](https://duckdb.org) · [pgvector](https://github.com/pgvector/pgvector) · [FastMCP](https://github.com/jlowin/fastmcp) · [Playwright](https://playwright.dev) · [Claude API](https://docs.anthropic.com).\n\n## License\n\nMIT © 2026 Chan Chi Ru. See [LICENSE](LICENSE).\n",
  "bytes": 5515,
  "sha": "9b54ac808e4d5e73e514334ee50644c508926a8a704bf6b1c12ff8ea48112771",
  "repo_slug": "ddmanyes/second-brain-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ddmanyes_mcp_second_brain_806035ec/readme"
}