# 🧠 Second Brain MCP

**Remember everything you watch and listen to.**

A [Model Context Protocol](https://modelcontextprotocol.io) server that turns YouTube videos and podcasts into a private, searchable memory — built on the brand-new **stateless MCP spec (2026-07-28)**.

Paste a link once. Ask about it forever.

> *"What did that video I watched last month say about salary negotiation?"*
>
> 🧠 → *"At [12:43] in **Never Split the Difference — Chris Voss**, he says never to accept the first offer without anchoring high…"* — with a deep link that jumps to the exact second.

## Why

You watch hours of talks, tutorials, and podcasts — and a week later you can quote none of it. Browser history remembers *that* you watched something; nothing remembers *what it said*. Second Brain gives your AI assistant total recall over everything you've ever watched or listened to:

- 🎯 **Ask across your whole watch history** — answers come back with timestamps and deep links to the exact moment.
- 🔒 **Private by design** — one local SQLite file. No cloud, no accounts, no API keys. Podcast audio is transcribed locally.
- ⚡ **Zero-key ingestion** — YouTube captions are fetched directly; nothing to configure.
- 🗑️ **Nothing is deleted without you** — destructive operations use the spec's new multi round-trip (MRTR) approval flow.

## Quickstart

### 1. Install

**Option A — as a tool, straight from GitHub** (recommended):

```bash
uv tool install git+https://github.com/ravishu5/second-brain-mcp
```

This installs the `second-brain` command into `~/.local/bin`. Find its absolute path — you'll need it below:

```bash
which second-brain     # e.g. /Users/you/.local/bin/second-brain
```

**Option B — from a local clone** (for hacking on it):

```bash
git clone https://github.com/ravishu5/second-brain-mcp
cd second-brain-mcp
python3 -m venv .venv && .venv/bin/pip install -e .
```

Your binary is then at `<clone-dir>/.venv/bin/second-brain`.

### 2. Connect a client

> **Always use the absolute path to the binary.** GUI apps (like Claude Desktop) don't inherit your shell's `PATH`, so a bare `second-brain` command often fails with *"Failed to spawn process: No such file or directory"*.

**Claude Code**

```bash
claude mcp add second-brain -- /absolute/path/to/second-brain
```

**Claude Desktop** — Settings → Developer → Edit Config, then add:

```json
{
  "mcpServers": {
    "second-brain": {
      "command": "/absolute/path/to/second-brain"
    }
  }
}

ex: "command": "/Users/ravi/Desktop/mcp/second-brain-mcp/.venv/bin/second-brain" in my case
```

Fully quit (⌘Q) and reopen Claude Desktop — the server should show as connected under Settings → Developer.

**As a stateless HTTP service** (deployable behind any load balancer — no sticky sessions, no shared state):

```bash
second-brain --http --port 8000
```

### 3. Use it

Talk to your assistant:

```
› Remember this: https://www.youtube.com/watch?v=8S0FDjFBj8o
› What have I saved about system design?
› What did Lex's guest say about AGI timelines? Link me to the moment.
› Give me a digest of everything I added this week.
```

## Tools

| Tool | What it does |
|---|---|
| `remember(url, episode?)` | Ingest a YouTube video or podcast episode: fetch transcript, chunk with timestamps, index. |
| `recall(query, limit?)` | BM25 full-text search across every transcript; returns passages with deep links to the exact second. |
| `library(limit?)` | Everything in the brain, newest first, with stats. |
| `transcript(item_ref, start?, end?)` | Read a raw transcript, optionally sliced by time range. |
| `digest(days?)` | What you added recently, rolled up. |
| `forget(item_ref)` | Delete an item — **gated by MRTR user confirmation**. |

Podcast transcription is optional (local [faster-whisper](https://github.com/SYSTRAN/faster-whisper)):

```bash
pip install "second-brain-mcp[whisper]"
```

## Built on the 2026-07-28 stateless spec

This server is a working showcase of [MCP's biggest release since remote MCP launched](https://blog.modelcontextprotocol.io/posts/2026-07-28/):

```mermaid
sequenceDiagram
    participant U as User
    participant C as Client (Claude)
    participant S as Second Brain
    C->>S: tools/call forget("that crypto video")
    S-->>C: resultType: input_required ("Permanently delete? No undo.")
    C->>U: Asks for approval
    U-->>C: Yes
    C->>S: tools/call retry (inputResponses + requestState)
    S-->>C: "Forgot 'Crypto Explained' (213 chunks removed)."
```

- **Stateless by construction.** No `initialize` handshake, no `Mcp-Session-Id`. Every request is self-contained; protocol metadata rides in `_meta` per request. Run one instance or twenty behind a load balancer — nothing breaks, because the only durable state is your local SQLite file, addressed through explicit item ids that clients thread between calls (exactly the application-state pattern the spec prescribes).
- **MRTR instead of server-push.** `forget` returns `resultType: "input_required"` with an elicitation request; the client gathers your approval and retries with `inputResponses`. No open streams, no sessions — and nothing is ever deleted without a human saying yes.
- **Header-routable.** Under the streamable HTTP transport, gateways can rate-limit `Mcp-Method: tools/call` + `Mcp-Name: remember` (expensive ingestion) differently from cheap `recall` reads — without parsing a byte of JSON.
- **SDK v2.** Built on [`mcp` v2.0.0](https://github.com/modelcontextprotocol/python-sdk), released alongside the spec. Type hints are the schema; `Resolve()` powers the MRTR flow.

## Architecture

```
┌─────────────┐   remember(url)   ┌──────────────┐
│ Claude /    │ ────────────────► │ ingest.py    │  YouTube captions (no key)
│ any MCP     │                   │              │  RSS + local whisper
│ client      │   recall(query)   ├──────────────┤
│             │ ────────────────► │ store.py     │  SQLite + FTS5 (BM25)
└─────────────┘   ◄─ passages +   │ ~/.second-   │  timestamped chunks
                     deep links   │  brain/      │
                                  └──────────────┘
```

Transcripts are merged into ~450-character chunks, split on silence gaps (usually topic boundaries), each carrying its `start`/`end` timestamps — so search hits map back to a playable moment, not just a document.

## Troubleshooting

- **"Server disconnected" / "Failed to spawn process: No such file or directory"** — the client can't find the binary. Use the absolute path from `which second-brain` (or your venv's `.venv/bin/second-brain`) in the config, then fully restart the client.
- **macOS: `PermissionError: Operation not permitted` on a path under `~/Desktop`, `~/Documents`, or `~/Downloads`** — macOS blocks other apps from reading those folders. Don't point the client at a venv inside them; install outside instead: `uv tool install git+https://github.com/ravishu5/second-brain-mcp` (lands in `~/.local`, which isn't protected). Alternatively grant the client Desktop access under System Settings → Privacy & Security → Files and Folders.
- **"No transcript/captions available"** — the video has captions disabled; there's nothing to index (yet — see roadmap).
- **Podcast ingestion errors about whisper** — install the optional extra: `pip install "second-brain-mcp[whisper]"`.
- **Where's my data?** One SQLite file at `~/.second-brain/brain.db`. Override with the `SECOND_BRAIN_DB` env var. Delete the file to wipe the brain.

## Development

```bash
git clone https://github.com/ravishu5/second-brain-mcp
cd second-brain-mcp
uv sync --extra dev
uv run pytest
uv run mcp dev src/second_brain_mcp/server.py   # MCP inspector
```

## Roadmap

- [ ] Client-side summaries on ingest via MRTR `sampling/createMessage` (the *client's* model writes the summary — still zero server keys)
- [ ] Semantic search (local embeddings) alongside BM25
- [ ] Browser extension: one-click "remember this"
- [ ] Whisper speaker diarization for podcasts

PRs welcome — especially ingestion sources (lectures, audiobooks, Twitch VODs).

## License

MIT © Ravi Shankar