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

Related MCP server: ilma

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:

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.