# 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](https://turso.tech) (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

```bash
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):

```bash
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:

```bash
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:

```bash
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:

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