# recollect

**Local, cross-agent memory for AI coding agents.** One SQLite file on your machine, shared by Claude Code, Codex CLI, Gemini CLI, Cursor — anything that speaks MCP. Start a task in one agent, finish it in another.

- **Local-first** — a single file at `~/.recollect/memory.db`. No cloud, no Docker, no daemon.
- **Cross-agent** — every agent spawns the same stdio MCP server against the same database (SQLite WAL handles concurrency).
- **Sessions + facts** — resumable work sessions (summary, decisions, open threads, running log) and durable long-term memories.
- **Fast keyword search** — SQLite FTS5, works offline, zero extra dependencies.
- **Never trapped** — `recollect export` dumps everything to plain Markdown.

## Install

```bash
# Claude Code
claude mcp add recollect -- npx -y recollect-mcp

# Codex CLI
codex mcp add recollect -- npx -y recollect-mcp

# Gemini CLI, Cursor, Windsurf, Cline, … (JSON config)
{
  "mcpServers": {
    "recollect": { "command": "npx", "args": ["-y", "recollect-mcp"] }
  }
}
```

That's it. Each agent gets the same tools; they all read and write the same database.

## Tools

| Tool | Purpose |
|---|---|
| `memory_save` | Store a durable fact (preference, convention, decision, gotcha). Dedupes; supports superseding old facts. |
| `memory_search` | FTS5 keyword search, most relevant first. Project scope includes globals. |
| `memory_list` | Browse recent memories, paginated. |
| `memory_update` | Edit content/tags/importance in place. |
| `memory_delete` | Remove a memory. |
| `session_start` | Open a work session for the current task. |
| `session_log` | Append a progress note to the active session. |
| `session_end` | Close with a handoff-quality summary, decisions, and open threads. |
| `session_resume` | **The handoff primitive** — recent sessions (active first) with logs, from any agent. Leads with the project brief. |
| `session_search` | FTS across session metadata *and* individual log entries. |
| `project_brief` | Your standing instructions for a project (stack, conventions, do-not-touch), curated in the web UI. |
| `context_resume` | **One-call startup**: brief + recent sessions + recent memories together. |

Plus a `resume-work` MCP prompt and a `memory://recent/{project}` resource for clients that support them.

Memories and sessions are scoped to a **project**, identified by the normalized git remote (`github.com/user/repo` — identical on every machine that clones the repo), falling back to the git root or directory name; `RECOLLECT_PROJECT` overrides. Global memories surface everywhere.

**Secrets:** memories are plaintext and may sync across machines. Agents are instructed never to store credentials, and `memory_save` (plus the CLI and UI) rejects content matching well-known secret formats — store a pointer to your password manager instead.

## Web UI

```bash
recollect ui          # opens http://127.0.0.1:7777
```

Browse every project, search memories and session logs, add/edit/delete memories, and — most usefully — write a **project brief**: a description plus standing notes ("Laravel 11 API, deploys via Forge, never touch the billing module"). Agents receive the brief through `project_brief` and at the top of `session_resume`, so anything you write there becomes permanent instructions for every agent. Loopback-only by design.

## Multiple machines

Run one recollect as the shared hub on any small server (a Forge box, a VPS, a home machine on Tailscale):

```bash
recollect serve --http --port 8787 --token "$RECOLLECT_TOKEN"
```

Then pick a mode per machine:

**Synced (recommended)** — local-first with invisible background sync. Agents keep using the fast local database (and keep working offline); recollect syncs with the hub on start, shortly after every write, and immediately when a session ends. Deletes propagate; conflicts resolve last-write-wins.

```bash
recollect connect https://memory.example.dev --token "$RECOLLECT_TOKEN"
# that's it — every agent on this machine now shares the hub's memory
recollect sync          # manual sync, if you want one
recollect disconnect    # back to local-only
```

**Remote** — agents talk to the hub directly over streamable HTTP (zero local state, online-only). See [docs/remote.md](docs/remote.md) for per-agent connection snippets.

Sync design details (ULID ids, tombstones, clock-skew-safe cursors): [docs/sync.md](docs/sync.md).

## CLI

The same binary doubles as a CLI — so agents *without* MCP support (or you, in a terminal) can still use the memory:

```bash
recollect search "auth refactor"          # search memories
recollect search --sessions "webhooks"    # search sessions
recollect save "Deploys go via Forge" --tags deploy --importance 4
recollect sessions --project api          # recent sessions
recollect export                          # dump everything to Markdown
recollect stats                           # what's in the database
```

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `RECOLLECT_DB` | `~/.recollect/memory.db` | Database file location |
| `RECOLLECT_PROJECT` | cwd basename | Default project scope |
| `RECOLLECT_AGENT` | MCP client name | Attribution recorded on writes |

## Why not …?

**OpenMemory / mem0** — great, but Docker + Postgres + Qdrant for personal memory is a lot of machinery. This is one file. **Markdown handoff files** — portable but unsearchable and per-project; recollect gives you FTS across everything you've ever done. **Built-in agent memory** — lives inside one vendor's tool; the whole point here is that memory belongs to *you*, not the agent.

## Development

```bash
npm install
npm run lint     # typecheck
npm test         # vitest
npm run build    # tsup → dist/
node dist/index.js help
```

Test the MCP surface interactively:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## Roadmap

Optional semantic search (local embeddings via Ollama + sqlite-vec), Markdown import, memory decay/dedupe heuristics, TUI browser.

## License

MIT