Second Brain
Persistent memory for any AI agent.
Every assistant forgets the moment the chat ends. Second Brain is the memorythey keep: a folder of Markdown pages you own, held in a hosted database witha vector index so they can be found by meaning, and served to any agent overthe Model Context Protocol. 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 |
| The librarian | An MCP memory server with five tools. Chops every page at its headings, vectorizes the pieces, files them, and answers questions. | 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/ |
Plus two tools for the machine that holds your notes: a bulk loader and atwo-way file sync, so you can keep editing in any editor and the memory stayscurrent.
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 into an agent with a shelland let it do the setup. By hand:
- Library. A Postgres with pgvector (Supabase is one click). Run the SQLin
migrations/in order. - Config.
cp .env.example .envand fill it in. Never commit.env. - Load.
npm install && npm run embedreads your notes folder and fillsthe library. A large vault costs a few dollars once. - Serve.
cd server, setSUPABASE_URLinwrangler.toml,wrangler secret putthe three secrets,npx wrangler deploy. - Connect. Add
https://<worker>/mcp/<AUTH_TOKEN>as an MCP connector inany client. The token rides in the URL because some clients cannot send abearer header. Treat the URL as a password. - Sync (optional).
npm run syncon the notes machine keeps folder andlibrary 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. initializereturns the rulebook as MCP instructions, so a client that honours themneeds 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 ofoverlap, then embedded withtext-embedding-3-large(3072 dims, stored ashalfvec). Search embeds the question and asks thesearch_chunksRPC forthe 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, sorunning cost is pennies.
- Kind is derived from the path (
wiki/projects/→project, and so on), sothe folder map inAGENTS.mdis 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.tsand one inserver/src/index.ts. - Auth: one shared token per server. For several people, issue a token peragent and check it against a table; the compare is already constant-time.
- Local-only mode (local Postgres + local embedder, no cloud) is not builtyet. The hosted version is the product.
Pairs with Mothership
Second Brain solves "the model does not know my projects, rules or past workacross any chat". A different amnesia, "this long session forgot what wedecided three hours ago", is solved byMothership's state ledger,transcript tail and exact recall. Use both. Seedocs/memory-layers.md.
License
MIT. Use it, fork it, build your own memory on it.
Made by lennymadethat.
