Supermem

A personal super-memory graph that acts as a shared execution layer: it stores everything you're building — projects, tools, decisions, people, files — as a graph, and exposes it over MCP so any tool or agent (and you) can query and grow the same context in natural language.

• Backend: Turso (managed libSQL / SQLite) — free, low-maintenance, network-addressable, native vector search, and portable (it's just a SQLite file). Dev runs against a local file: DB with no account.
• Retrieval: hybrid — graph edges for exact traversal, vector search as the natural-language front door, and FTS5 keyword search as an exact-term complement.
• Embeddings: local, free, offline via @huggingface/transformers (Xenova/all-MiniLM-L6-v2, 384-dim). No API keys, no cost.

Quick start

npm install
cp .env.example .env        # defaults to a local file: DB — no account needed
npm run migrate             # create the schema
npm run seed                # optional: a small example graph about Supermem itself
npm run verify              # end-to-end checks (embedding → recall → traversal)
npm run mcp:smoke           # live MCP client↔server check

First run downloads the ~22 MB embedding model once, then works offline.

Use it from Claude Code

Register the stdio server (use the absolute path to this repo):

claude mcp add supermem -- npx tsx /ABSOLUTE/PATH/TO/supermem/src/mcp/stdio.ts

Then, in any session, the agent can call these tools:

Tool	Purpose
remember	Store a fact in natural language (optionally about a named entity).
add_entity	Create/update an entity (type, name); attrs merged.
add_relation	Connect two entities with a typed edge (uses, decided, …).
add_observation	Attach an embedded fact to a specific entity.
recall	Primary query — hybrid search → relevant entities + facts + neighbors.
get_entity	Full detail for one entity: attrs, all facts, connections.
neighbors	Traverse the graph from an entity, up to N hops.
list_entities	List entities, optionally by type.
forget	Delete an observation or an entire entity.

Reachable over HTTP (Phase 2)

The same server also speaks the MCP Streamable HTTP transport, so agents and people can reach one shared memory remotely. It runs statelessly (a fresh server per request), which suits serverless and horizontal scaling.

Run it locally or on any always-on host:

export SUPERMEM_AUTH_TOKEN=$(openssl rand -hex 32)   # required before exposing publicly
npm run http                                         # → http://localhost:3000/mcp
npm run http:smoke                                   # verifies auth + remember/recall over HTTP

• GET /health — liveness (no auth).
• POST /mcp — MCP endpoint; requires Authorization: Bearer $SUPERMEM_AUTH_TOKEN whenever the token is set. If it's unset, auth is disabled (local dev only) and the server warns.

Register the remote server with Claude Code:

claude mcp add --transport http supermem-remote https://YOUR_HOST/mcp \
  --header "Authorization: Bearer $SUPERMEM_AUTH_TOKEN"

Deploy to Vercel

api/index.ts exports the Express app and vercel.json routes all traffic to it, so:

vercel                       # preview
vercel --prod                # production
vercel env add SUPERMEM_AUTH_TOKEN     # and TURSO_DATABASE_URL / TURSO_AUTH_TOKEN

Embeddings caveat. The default embedder (transformers.js/onnxruntime) is a heavy native dependency for serverless functions (bundle size + cold starts). For a smooth reachable deploy today, either run npm run http on a small always-on host (Railway/Fly/Render/VPS), or swap the embedder in src/embed/embedder.ts for a hosted embedding endpoint. Phase 2's HTTP transport + auth work identically in all of these.

Point at Turso (reachable deployment)

Create a free Turso DB, then set in .env:

TURSO_DATABASE_URL=libsql://your-db.turso.io
TURSO_AUTH_TOKEN=...

npm run migrate and everything else behave identically — the schema and code are backend-agnostic.

Data model

• nodes(id, type, name, attrs, …) — entities, unique on (type, name).
• edges(id, src_id, dst_id, type, attrs, …) — typed, directed relationships.
• observations(id, node_id, text, source, embedding F32_BLOB(384), …) — atomic facts, embedded on write; mirrored into an FTS5 index and a libSQL vector index.

Roadmap

• Phase 1 (done): core memory graph over stdio MCP, Turso-ready.
• Phase 2 (done): Streamable-HTTP MCP transport + bearer-token auth + Vercel/self-host deploy path so agents and people reach it remotely. ← you are here
• Phase 3: auto dev-activity ingestion (scan git repos/commits/files → same write tools).
• Phase 4: integrations (Gmail/Drive/…) and a thin REST + web UI for non-agent users.