# 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

```bash
pip install agent-logbook
```

## Quickstart

```bash
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](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.

## The seven tools, in plain terms

`agent-logbook` exposes seven MCP tools. Your assistant calls these itself — you never type them — but here's what each one actually does, since the names alone don't tell the whole story:

| Tool | In plain terms | Example |
|---|---|---|
| `recall(query)` | "What do we already know about this?" Ranked, budget-capped retrieval — it never returns more than a fixed token budget, no matter how much history exists. | `recall("auth token expiry")` → finds *"Auth tokens are JWT, 15 minute expiry, refreshed via httpOnly cookie."* |
| `remember(type, content, entity)` | "Write this down." Saves one distilled fact or decision. If a live memory already exists for the same `entity`, it refuses to write and hands back the conflict instead of silently overwriting. | `remember("fact", "Auth tokens are JWT, 15 minute expiry", entity="auth")` → `{"written": true, "id": 2}` |
| `supersede(old_id, new_content)` | "That decision changed — replace it, but keep the history." Nothing is deleted; the old row is marked superseded and linked to the new one. | `supersede(1, "Switched the stack to Django after all")` → old entry hidden from recall, new one becomes the live version, both still visible in `memory_history` |
| `list_open(type)` | "What's still unresolved?" Lists open tasks and questions. | `list_open()` → `[{"type": "task", "content": "Add rate limiting to /login"}]` |
| `set_status(memory_id, status)` | "Mark this done" (or `dropped`, or reopen it with `open`). | `set_status(5, "done")` |
| `memory_history(memory_id)` | "How did we get here?" Walks a memory's full supersession chain, oldest to newest. | `memory_history(1)` → `["Use Postgres for the main store", "Use SQLite (simpler ops)"]` |
| `memory_stats()` | A health check, plus the savings numbers this whole project is about: how many memories exist, how many recalls have happened, and the `savings_ratio` — roughly how many raw reads a budgeted recall is saving you. | `memory_stats()` → `{"total": 3, "live": 2, "recall_count": 2, "savings_ratio": 2.0, ...}` |

## Explore what's stored

```bash
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](IMPLEMENTATION_GUIDE.md) (architecture + setup)
and [TESTING_GUIDE.md](TESTING_GUIDE.md) (test strategy).

## Development

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