agent-logbook

Local SQLite long-term memory for AI assistants, served over MCP. Context window = working memory. This database = long-term memory.

Every decision logged, nothing erased: agent-logbook writes distilled facts and decisions to a plain SQLite file as your assistant works, ranks them by relevance and salience so retrieval stays cheap no matter how old the project gets, and keeps a full supersession chain when something changes — so you can always ask "why did we think that before."

Install

pip install agent-logbook

Quickstart

cd your-project
agent-logbook-init

That's it — init detects which agentic tool you're using and wires up both the MCP server registration and the memory-protocol instructions for it.

Works with

Tool	Instructions written to	MCP config written to
Claude Code	CLAUDE.md	.mcp.json
Cursor	.cursor/rules/agent-logbook-memory.mdc	.cursor/mcp.json
GitHub Copilot	.github/copilot-instructions.md	.vscode/mcp.json

init never clobbers an existing config file — it merges in a memory server entry alongside whatever's already there, and the protocol block is idempotent (rerun it as many times as you want). If none of these three are detected, it prints the protocol text and a generic MCP config snippet for you to adapt by hand — see IMPLEMENTATION_GUIDE.md for the manual steps and agent-logbook-init --help for --dry-run and --tool to force a specific one.

Because the underlying intelligence (conflict checks, budgeted retrieval, supersession) lives in the server, not the prompt, any MCP-compatible client gets the same guarantees — the three above are just the ones init knows how to wire up automatically today.

Explore what's stored

agent-logbook-viewer --dir /path/to/projects

Generates a self-contained HTML report comparing every project's memory database it finds — savings metrics (recall count, tokens served, savings ratio) side by side, plus a searchable table of each project's actual stored memories. Point it at one --db path or a parent folder containing several projects.

Docs: IMPLEMENTATION_GUIDE.md (architecture + setup) and TESTING_GUIDE.md (test strategy).

Development

pip install -e ".[dev]" && pytest