# MemDrive

**Shareable memory for AI coding agents.** Teach Claude Code (or Cursor)
something once, then carry that knowledge across sessions — and hand it to a
teammate as a single file they can import into *their* agent.

```
I taught Claude Code something on my laptop, exported a pack, my friend
imported it in Cursor, and their agent knew it.
```

MemDrive is a tiny [MCP](https://modelcontextprotocol.io) server + CLI. No
cloud, no account, no embeddings service — just a local SQLite database and
plain-text `.jsonl` packs you own.

---

## Install

```bash
npx memdrive@latest install
```

This wires MemDrive into every agent it finds:

- **Claude Code** — adds the MCP server and (optionally) a Stop hook that
  auto-distills durable memories when a session ends.
- **Cursor** — adds the MCP server (you call `remember`/`recall` yourself).

It backs up each config before touching it, never clobbers your other MCP
servers, and prints exactly what changed. Then open your agent and ask:
**"what do you remember?"**

Remove it any time:

```bash
npx memdrive@latest install --remove
```

## The three tools

Your agent gets three tools it can call on its own:

| Tool | When it fires |
|---|---|
| `remember` | You decide something, state a rule/preference, or hit a gotcha and its fix. Stores a short, distilled memory — never a transcript. |
| `recall` | At the start of a task. Returns the most relevant memories, pinned first, inside labelled `[MEMORY …]` envelopes. |
| `forget` | A memory is wrong or outdated. Tombstones it by id. |

Memories have a **type** (`decision`, `convention`, `gotcha`, `preference`,
`fact`, `snippet`, `todo_context`), an optional **project** scope, and **tags**.

## Sharing packs

Packs are the whole point. A pack is one `.jsonl` file — a header line plus one
memory per line.

```bash
# Export the acme project's memories (personal preferences are left out)
memdrive export acme.jsonl --project acme

# On another machine / in another agent
memdrive import acme.jsonl --name acme-team
```

- **Idempotent.** Every memory has a ULID, so re-importing an updated pack only
  adds the new entries. Share the file over GitHub or Drive and re-import
  whenever it changes — that's your sync story for v0.1.
- **Secret-safe.** Export scans for API keys, tokens, JWTs, connection strings,
  and private keys, and refuses (naming each finding) unless you pass `--force`.
- **Provenance kept.** Imported memories are labelled `source=pack:<name>` and
  are never auto-pinned into your context.

## Other commands

```bash
memdrive list [--project x] [--all]   # see what's stored
memdrive status                        # DB path + counts by type/source
memdrive serve                         # run the MCP server (your agent does this)
```

Everything lives in `~/.memdrive/local.db`. Override with `MEMDRIVE_DB` for
scratch/testing.

## Security note

**Imported packs are untrusted text.** A pack is just JSON someone else wrote —
read the `.jsonl` before importing it, exactly as you would a shell script from
the internet. MemDrive relabels provenance and refuses to pin imported memories,
but it cannot vouch for their content.

## How it works

- **Storage:** SQLite with an FTS5 full-text index. Search is `bm25` relevance,
  pinned-first, with a recency tiebreak; tombstoned and expired memories are
  never returned.
- **Server:** stdio MCP. `recall` renders memories under a token budget so it
  never blows up your context.
- **Distill hook:** on Claude Code session end, MemDrive tails the transcript
  and asks a headless `claude -p` to extract ≤5 durable memories as strict JSON,
  validates them, redacts secrets, and stores them with `confidence=0.6`.

## Roadmap

v0.1 is deliberately small. Next up, roughly in order:

- **Embeddings** (hybrid FTS + vector search) behind the same `recall` contract
- **Collections** for grouping memories beyond `project`/`tags`
- **Live mounts / sync** and an HTTP transport
- **Review queue** for triaging imported packs
- More clients (Windsurf, Cline, VS Code)

The v0.1 interfaces — the store API, the `recall` contract, and the JSONL pack
format — were chosen to survive all of the above without a migration.

## Develop

```bash
npm install
npm run build      # tsup → dist/cli.js
npm test           # vitest
npm run typecheck
```

MIT licensed.