agent-logbook
The agent-logbook server provides a local SQLite-backed long-term memory system for AI assistants, enabling structured storage, retrieval, and lifecycle management of facts, decisions, tasks, and questions across sessions.
Recall (
recall): Retrieve ranked, relevant memories using a keyword query within a configurable token budget (default 1500 tokens), optionally filtered by memory type.Remember (
remember): Persist a distilled fact, decision, task, question, or note. Automatically detects conflicts for the same type+entity to prevent silent overwrites; supports aforceflag to bypass this.Supersede (
supersede): Replace an outdated memory with an updated version while keeping the full history chain intact — nothing is ever deleted.List Open (
list_open): View all unresolved tasks and questions, optionally filtered by type, to aid planning.Set Status (
set_status): Mark a task or question asdone,dropped, or reopen it withopen.Memory History (
memory_history): Walk the full supersession chain for any memory to see how a fact or decision evolved over time.Memory Stats (
memory_stats): Get health metrics including total/live memory counts, open items, recall frequency, tokens served, and asavings_ratioshowing retrieval efficiency vs. reading the full corpus.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agent-logbook remember the user prefers dark mode"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-logbookRelated MCP server: MCPMem
Quickstart
cd your-project
agent-logbook-initThat'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 |
|
|
Cursor |
|
|
GitHub Copilot |
|
|
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.
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 |
| "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. |
|
| "Write this down." Saves one distilled fact or decision. If a live memory already exists for the same |
|
| "That decision changed — replace it, but keep the history." Nothing is deleted; the old row is marked superseded and linked to the new one. |
|
| "What's still unresolved?" Lists open tasks and questions. |
|
| "Mark this done" (or |
|
| "How did we get here?" Walks a memory's full supersession chain, oldest to newest. |
|
| A health check, plus the savings numbers this whole project is about: how many memories exist, how many recalls have happened, and the |
|
Explore what's stored
agent-logbook-viewer --dir /path/to/projectsGenerates 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]" && pytestAvailable Tools
7 toolslist_openB
List open tasks and questions (optionally filter by type: 'task' or 'question'). Call when planning what to do next.
Inputs: type. Returns: result
memory_historyB
Show the full supersession chain for a memory — how a fact/decision evolved over time. Useful for 'why did we think X before?' questions.
Inputs: memory_id (required). Returns: result
memory_statsA
Counts of total/live memories and open items. Cheap health check. Also reports token-usage metrics: recall_count, avg_tokens_per_recall, total_tokens_served (lifetime tokens returned by recall), live_corpus_tokens (estimated tokens across all live memories), and savings_ratio (live_corpus_tokens / avg_tokens_per_recall — roughly how many recalls it would take to read the whole corpus instead of a budgeted slice; null if no recalls have happened yet).
Inputs: no named parameters. Returns: result
recallA
Retrieve relevant long-term memories for the current task. Call this at
the START of any task before doing work. Returns ranked memories (facts,
decisions, open tasks/questions) within a token budget, plus a count of
open items. query should be a few keywords describing the task.
Inputs: query (required), types, budget_tokens. Returns: result
rememberA
Persist ONE distilled memory after completing a work block. type is one
of: fact, decision, task, question, note. content must be 1-2 sentences,
self-contained, in past/declarative form (a distillation — never a raw
transcript). entity is a short slug for what it concerns (e.g. 'auth',
'db-choice'). If a live memory already exists for the same type+entity,
this returns a CONFLICT without writing — then either supersede(old_id,...)
to update it, ask the user which stands, or retry with force=true to keep
both.
Inputs: type (required), content (required), force, entity. Returns: result
set_statusB
Mark a task/question as 'done' or 'dropped' (or reopen with 'open').
Inputs: status (required), memory_id (required). Returns: result
supersedeA
Replace an outdated memory with an updated one. The old memory is kept in the chain for history (never deleted). Use this when a decision or fact has changed.
Inputs: old_id (required), new_content (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose: listing open items, showing memory history, stats, recalling, remembering, setting status, and superseding. No two tools overlap in functionality.
Names are inconsistent: some are verb_noun (list_open, set_status), some are noun_noun (memory_history, memory_stats), and others are single verbs (recall, remember, supersede). No uniform pattern.
Seven tools is an appropriate number for a memory/logbook system. Each tool handles a distinct operation without being too many or too few.
The tool set covers creation, retrieval, update (via supersede and set_status), and history for memories. Missing explicit deletion or a way to list all memories, but these gaps are minor for the intended purpose.
Maintenance
Related MCP Connectors
Persistent personal memory for AI assistants: search what you told it before and save new facts.
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Persistent memory for AI assistants: store, search, and connect knowledge across conversations.
Persistent memory for AI agents, for code, research and everyday life. Stale facts retire.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceProvides persistent local memory functionality for AI assistants, enabling them to store, retrieve, and search contextual information across conversations with SQLite-based full-text search. All data stays private on your machine while dramatically improving context retention and personalized assistance.3-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to store and retrieve memories with semantic search capabilities using vector embeddings. Provides persistent memory storage with SQLite backend for context retention across conversations.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to have persistent, self-hosted memory across sessions and devices, storing context in a SQLite database you control.1MIT
- AlicenseNot gradedqualityDmaintenanceProvides AI assistants with persistent memory across sessions using local SQLite and keyword search, allowing storage and retrieval of user preferences, project context, and decisions.31 npm9MIT