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

# 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

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

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

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.

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 for per-agent connection snippets.

Sync design details (ULID ids, tombstones, clock-skew-safe cursors): 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:

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

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

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

Test the MCP surface interactively:

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