Second Brain

Persistent memory for any AI agent.

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. Claude, ChatGPT, Grok, Gemini, Claude Code, Codex, Cursor: if it speaks MCP, it can remember.

Three parts, one product:

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 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.

Related MCP server: ilma

The five tools

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's state ledger, transcript tail and exact recall. Use both. See docs/memory-layers.md.

License

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

Made by lennymadethat.