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

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.

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 (defaults to the directory the agent was launched in); global memories surface everywhere.

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 a shared server and point every machine's agents at it — no file syncing, no separate database server:

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

See docs/remote.md for systemd/Tailscale setup and per-agent connection snippets (Claude Code, Codex, Cursor/Gemini).

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

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

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