second-brain

Second Brain — setup and usage

Author: Moran Koren, Ben-Gurion University of the Negev ([email protected]). Part of the Theorist Toolbox.

Sets up a self-contained agentic-RAG library in a target directory: papers are ingested from LaTeX source (preferred), HTML, or PDF-OCR into a chunked, QA-gated index; an agent (or Claude Code itself via MCP) answers questions by reading exact theorems/proofs with custom macros and prerequisite definitions auto-bundled. Full design: package/ in this skill contains the complete brain Python package.

Throughout, $SKILL means this skill's base directory (shown in the message that loaded this file) and $TARGET means the directory the user wants the second brain in (default: the current working directory; ask only if the cwd is clearly wrong for a paper library, e.g. a code repo).

Step 0 — detect state

$TARGET/config.toml exists AND $TARGET/.venv/bin/brain runs → already initialized: skip to Usage. Otherwise run Init.

Init

cd "$TARGET"
python3 -m venv .venv
.venv/bin/pip install -q "$SKILL/package[dev,providers,mcp,web]"
cp "$SKILL/templates/config.toml" config.toml
.venv/bin/brain status        # creates papers/ parsed_papers/ index/ scratchpad/

Then register the MCP server for Claude Code by writing $TARGET/.mcp.json (absolute paths, no ~):

{
  "mcpServers": {
    "second-brain": {
      "command": "<ABS_TARGET>/.venv/bin/python",
      "args": ["-m", "brain.mcp_server"],
      "env": { "BRAIN_CONFIG": "<ABS_TARGET>/config.toml" }
    }
  }
}

Verify the install with the bundled fixture, then remove the test entry:

.venv/bin/brain ingest "$SKILL/package/tests/fixtures/mini_paper" --id selftest --no-llm
.venv/bin/brain search "monotone valuations"       # selftest must rank first
.venv/bin/python -c "
from pathlib import Path; from brain.config import load_config; from brain.index import store
import shutil
cfg = load_config(Path('config.toml')); idx = store.load_index(cfg.index_file)
idx.pop('selftest', None); store.save_index(cfg.index_file, idx)
shutil.rmtree(cfg.parsed_dir / 'selftest', ignore_errors=True)"