# Second Brain

**Persistent memory for any AI agent.**

![How Second Brain works: a rulebook at the front, a librarian in the middle that chops and vectorizes every page, and a library at the back that any agent can search](docs/second-brain.png)

Every assistant forgets the moment the chat ends. Second Brain is the memory
they keep: a folder of Markdown pages you own, held in a hosted database with
a vector index so they can be found by meaning, and served to any agent over
the [Model Context Protocol](https://modelcontextprotocol.io). Claude, ChatGPT,
Grok, Gemini, Claude Code, Codex, Cursor: if it speaks MCP, it can remember.

Three parts, one product:

| Part | What it is | Where |
|---|---|---|
| **The rulebook** | `AGENTS.md`: how the memory is laid out, when to append versus create, what never to write. Handed to every agent the moment it connects. | [`AGENTS.md`](AGENTS.md) |
| **The librarian** | An MCP memory server with five tools. Chops every page at its headings, vectorizes the pieces, files them, and answers questions. | [`server/`](server/) |
| **The library** | A hosted Postgres with pgvector. Two tables: every page whole, and every page in chunks with its vectors. The rolodex is the vector index. | [`migrations/`](migrations/) |

Plus two tools for the machine that holds your notes: a bulk loader and a
two-way file sync, so you can keep editing in any editor and the memory stays
current.

Built and used daily as the memory behind one person's entire working life
(every project, every decision, thousands of pages). Extracted here clean.

## Quick start

The fastest route is to paste [`KIT.md`](KIT.md) into an agent with a shell
and let it do the setup. By hand:

1. **Library.** A Postgres with pgvector (Supabase is one click). Run the SQL
   in `migrations/` in order.
2. **Config.** `cp .env.example .env` and fill it in. Never commit `.env`.
3. **Load.** `npm install && npm run embed` reads your notes folder and fills
   the library. A large vault costs a few dollars once.
4. **Serve.** `cd server`, set `SUPABASE_URL` in `wrangler.toml`,
   `wrangler secret put` the three secrets, `npx wrangler deploy`.
5. **Connect.** Add `https://<worker>/mcp/<AUTH_TOKEN>` as an MCP connector in
   any client. The token rides in the URL because some clients cannot send a
   bearer header. Treat the URL as a password.
6. **Sync (optional).** `npm run sync` on the notes machine keeps folder and
   library mirrored both ways.

## The five tools

| Tool | Does |
|---|---|
| `search_vault(query, limit?)` | Semantic search across every live page. Returns chunks with their page path, title, kind and heading. |
| `read_file(path)` | The full page: title, kind, body, metadata, updated_at. |
| `write_page(path, body, metadata?)` | Create or overwrite a page. Derives kind from the path, extracts headings and `[[links]]`, re-chunks, re-embeds. |
| `append_to_page(path, section, content)` | Insert under a `## Section`, newest at top. Creates the section if missing. |
| `delete_page(path, confirm)` | Soft-delete. Needs `confirm: true`. Hidden from search, kept in the database, restorable. |

`GET /` is a liveness probe. `GET /rules` returns the rulebook. `initialize`
returns the rulebook as MCP `instructions`, so a client that honours them
needs no extra prompt.

## How it works

```
  Any agent ──MCP──▶ librarian (Worker, 5 tools) ──▶ library (Postgres + pgvector)
      ▲                    │ hands over AGENTS.md            │ pages + chunks
      └──── the right memory comes back ◀───────────────────┘

  Your notes folder ⇄ sync ⇄ the same library     (edit anywhere; you own the files)
```

- Pages are chunked at `## ` headings, about 500 tokens each with 50 of
  overlap, then embedded with `text-embedding-3-large` (3072 dims, stored as
  `halfvec`). Search embeds the question and asks the `search_chunks` RPC for
  the nearest chunks.
- The database is the source of truth. The folder is a mirror you can read,
  grep and edit offline. Every write re-embeds only the page that changed, so
  running cost is pennies.
- Kind is derived from the path (`wiki/projects/` → `project`, and so on), so
  the folder map in `AGENTS.md` is also the schema.

## What is in the box

```
AGENTS.md            the rulebook (also served on connect and at /rules)
KIT.md               paste-prompt: an agent sets the whole thing up for you
server/              Cloudflare Worker, MCP HTTP transport, 5 tools
migrations/          pages + chunks schema, search RPC, soft delete
src/embed.ts         bulk loader: folder → chunks → vectors → library
src/sync.ts          two-way mirror between the folder and the library
src/parse.ts         path → kind, title, headings, wikilinks
reconcile.mjs        repairs drift between folder and library
docs/                the explainer image and the memory-layers note
.env.example         what the local tools need
```

## Design notes

- **Embeddings:** OpenAI by default; swap the provider in one function in
  `src/embed.ts` and one in `server/src/index.ts`.
- **Auth:** one shared token per server. For several people, issue a token per
  agent and check it against a table; the compare is already constant-time.
- **Local-only mode** (local Postgres + local embedder, no cloud) is not built
  yet. The hosted version is the product.

## Pairs with Mothership

Second Brain solves "the model does not know my projects, rules or past work
across any chat". A different amnesia, "this long session forgot what we
decided three hours ago", is solved by
[Mothership](https://github.com/lennymadethat/mothership)'s state ledger,
transcript tail and exact recall. Use both. See
[`docs/memory-layers.md`](docs/memory-layers.md).

## License

MIT. Use it, fork it, build your own memory on it.

<sub>Made by [lennymadethat](https://lennymadethat.com).</sub>