persistent-memory

Give any AI agent a permanent memory.

Most AI assistants forget everything the moment a conversation ends. This is the infrastructure that fixes that — a self-hostable memory layer any Claude (or other LLM) client can read from and write to, over the Model Context Protocol. Your notes, decisions, and project state live in a Postgres + pgvector store, stay searchable by meaning (not just keywords), and mirror to plain Markdown files you own.

Built and used in production as the memory behind a personal knowledge vault. Extracted here as a clean, reusable starting point.

---

What you get

Piece	What it does
MCP server (server/)	A Cloudflare Worker exposing five tools — search_vault, read_file, write_page, append_to_page, delete_page — over MCP HTTP transport. Point any Claude client at it and the model gains long-term memory.
Vector store (migrations/)	Postgres schema for pages + chunks with pgvector (halfvec) embeddings and a search_chunks similarity RPC. Runs on any Postgres with the vector extension (Supabase, Neon, plain PG).
Bulk embedder (src/embed.ts)	Reads a folder of Markdown, chunks it (~500 tokens), embeds it, and upserts to the store. One command to load your whole knowledge base.
File-sync mirror (src/sync.ts)	Watches a local folder and keeps files ⇄ database in sync both ways, so you can edit in any editor and the memory stays current.

How it works

  Any LLM client ──MCP──▶  Worker (5 memory tools)  ──▶  Postgres + pgvector
        ▲                                                      │
        └───────────  semantic search results  ◀──────────────┘

  Your Markdown folder  ⇄  file-sync  ⇄  same database   (edit anywhere, stays in sync)

The database is the source of truth; the Markdown files are a backup mirror you can read, grep, and edit offline. Every write re-embeds only what changed, so ongoing cost is pennies.

Quick start

1. Provision a Postgres with pgvector (Supabase is easiest — the vector extension is one click). Run the SQL in migrations/ in order.
2. Configure secrets (never commit these):
   • SUPABASE_URL — set in server/wrangler.toml [vars] (replace YOUR_SUPABASE_PROJECT_REF)
   • SUPABASE_SERVICE_ROLE_KEY, OPENAI_API_KEY, AUTH_TOKEN — wrangler secret put each
3. Bulk-load your notes: npm install && npm run embed
4. Deploy the memory server: cd server && npx wrangler deploy
5. Connect a client — add the worker URL as an MCP connector. Auth is via URL path (POST /mcp/<AUTH_TOKEN>) because some clients don't send Bearer headers.

Design notes

• Embeddings: OpenAI text-embedding-3 by default; swap the provider in src/embed.ts.
• Auth: single shared AUTH_TOKEN in the URL path. For multi-tenant use, issue one token per agent and validate against a table.
• Cost: one-time bulk embed is a few dollars for a large vault; ongoing sync is pennies/day.

How this pairs with Mothership long-session memory

These solve different amnesia problems:

Problem	Layer	Where
“The chat forgot what we decided three hours ago when the window rolled over”	Conversation continuity — Persistent State ledger + verbatim tail + exact recall over the transcript archive	Mothership (docs/long-session-memory.md)
“The model doesn’t know my projects, rules, or past work across any chat”	Long-term knowledge — searchable Markdown vault + embeddings	This repo

Use both. Mothership keeps a single long thread coherent; persistent-memory keeps your wiki available to every agent. Neither should store secrets as pasted values — point at env files / secret stores.

See also docs/memory-layers.md.

License

MIT — see LICENSE. Use it, fork it, build your own memory on it.

---

_{Built by lennymadethat.}