Research Second Brain

A personal research literature knowledge base built around Claude Code. You curate raw sources (papers, books, lecture notes); Claude reads them, summarizes them, cross-references them, and maintains a living wiki on your behalf — a "second brain" for your reading.

Concept

This project follows the "LLM Wiki" pattern popularized by Andrej Karpathy (gist): instead of you writing and maintaining notes by hand, an LLM agent maintains a wiki for you, page by page, session after session. The wiki is a living synthesis that compounds over time, while the raw material it's built from is never touched.

Two principles carried over from that pattern, applied here to a research-literature use case:

• Raw sources are immutable. Papers, books, and other source files are never edited, moved, renamed, or deleted by the agent. They live in their own folders, untouched.
• The wiki is LLM-owned. Claude creates and updates topic hubs, entity pages (authors, instruments, software), concept pages (methods, models, datasets), source summaries, cross-paper syntheses, and cached verbatim quotes — all linked together with Obsidian-style [[wikilinks]]. You read it, ask questions, and direct emphasis; Claude does the reading and bookkeeping.

The full schema — folder layout, frontmatter conventions, linking rules, and step-by-step workflows — lives in CLAUDE.md. Claude reads that file automatically at the start of every session in this directory; you generally won't need to read it yourself, but it's there if you want the exact rules Claude is following.

Setup

1. Clone this repo as your vault

This repo is the vault: it contains CLAUDE.md (the schema Claude follows) and, once you start using it, a wiki/ folder that Claude creates and maintains.

Your raw source material (paper PDFs, books, etc.) is not stored inside this repo. It lives in sibling folders, in a parent directory of your choosing — clone this repo as a subfolder inside that parent directory, alongside your existing articles/, books/, etc. folders (or wherever you keep your library).

2. Install Claude Code

If you don't already have it, install Claude Code and run it from inside this repo's folder.

3. Install the ADS/arXiv MCP server

Fetching papers directly from arXiv (by id or URL) during ingest relies on the mcp-ads-arxiv MCP server. Follow that repo's own installation instructions, then register it with Claude Code, e.g.:

claude mcp add mcp-ads-arxiv -- <command to run the server, per its README>

Check it's connected with /mcp inside a Claude Code session. Without it, you can still ingest sources you already have on disk — only fetching new arXiv papers by id/URL requires this server.

4. First run

Start Claude Code in this folder and say hello, or just give it your first request (e.g. /ingest <some arxiv id>). CLAUDE.md is a template the first time you use it: Claude will notice the placeholder <DOCUMENTS_DIR> hasn't been filled in yet and will ask you:

• where your raw source material lives (the absolute path to the parent directory),
• what your raw-material subfolders are called (articles/, books/, etc.),
• roughly what research domain(s) you're tracking.

It then rewrites CLAUDE.md itself with your answers filled in. This only happens once.

5. (Optional) Browse the wiki in Obsidian

Since the wiki is plain Markdown with Obsidian-style [[wikilinks]] and YAML frontmatter, it's convenient to open wiki/ as a vault in Obsidian. This gives you a proper UI for navigating between pages by clicking links, and — more importantly — Obsidian's built-in graph view lets you visualize the whole wiki as a knowledge graph: topics, entities, concepts, sources, and syntheses as nodes, with their [[wikilinks]] as edges. It's a quick way to spot how densely a topic is connected, which pages are hubs, and which are orphans, without having to read through wiki/index.md. This step is purely for browsing — Claude reads and writes the wiki files directly and doesn't need Obsidian itself.

Use

Five slash commands drive the workflow:

Command	Purpose
/ingest <arxiv-id-or-url | path>	Add a new source to the wiki: fetch it (if an arXiv id/URL) or read it from disk, summarize it, and update/create the entity, concept, and topic pages it touches.
/query <question>	Ask a question answered from the wiki only — fast, no raw sources reopened. The default for everyday research questions.
/research <question>	Deep research: same as /query, but every substantive claim is backed by a verbatim quote traceable to the exact page/section of the raw source. Use when you need to verify or cite the original material directly.
/save [slug]	File the last response as a synthesis page in the wiki, linked from the relevant topic hub(s).
/lint	Health check: surfaces contradictions between pages, stale claims, orphan pages, missing cross-references, and concepts worth their own page.

A typical session: /ingest a handful of new papers, /query or /research questions as they come up, /save anything substantial worth keeping, and run /lint periodically to keep the wiki coherent.

What lives where

• CLAUDE.md — the schema Claude follows: folder layout, frontmatter, linking conventions, and the full ingest/query/research/lint workflows.
• wiki/ — created on first use. index.md is the catalog (read first for any query), log.md is an append-only history, and topics/, entities/, concepts/, sources/, syntheses/, quotes/ hold the pages themselves.
• Your raw sources — outside this repo, in sibling folders under the parent directory you configured during first run.