Skip to main content
Glama
agent-logbook

agent-logbook

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

Related MCP server: MCPMem

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.

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

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

Available Tools

7 tools
list_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

    A3.6/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency2/5

    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.

    Tool Count5/5

    Seven tools is an appropriate number for a memory/logbook system. Each tool handles a distinct operation without being too many or too few.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides 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
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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 npm
      9
      MIT