memtool

A memory bank distilled from coding-agent session history, served over MCP.

memtool reads the transcripts your coding agent already writes, extracts the decisions, failures, knowledge and open threads buried in them, and files each one as a record that cites the exact turn it came from. The bank is plain Markdown on disk — greppable, diffable, and readable without this tool.

The CLI is the product. The MCP server and the skills are shells over it.

Install

pip install convo-mem              # the pipeline
pip install "convo-mem[mcp]"       # ...plus the retrieval server

The command is memtool. The distribution is convo-mem because an unrelated package already holds memtool on PyPI — and holds the memtool import name with it, so sharing either would collide in site-packages.

From a checkout, for development:

pip install -e ".[mcp]"

Use

memtool status                 # what project, sessions and bank this dir resolves to
memtool init                   # build a bank from session history
memtool lint                   # nightly sweep: revisit triggers, clustering, views
memtool verify --calibrate 20  # model triage of the review queue
memtool mcp                    # the MCP retrieval server (stdio; blocks)
memtool skills install         # put the six skills where your agent looks
memtool <command> --help

Every command derives its project from the current directory (the git root, or the main repo when you are in a worktree) and its bank from <project>/memory, prints what it resolved and where each value came from, and accepts --project PATH to operate on another project. .memconfig.yaml overrides any of it and is never required.

Work directories (.memtool-init/, .memtool-verify/, …), the stripped transcript corpus and the chunk corpus live under the current directory. MEMTOOL_HOME overrides that if you want them somewhere fixed.

MCP

Any MCP client can read the bank. Four tools: list_sessions, search_session, read_session, get_record — every response capped at ~4k estimated tokens, paging anchors instead of silent truncation.

{
  "mcpServers": {
    "memtool": {
      "command": "memtool",
      "args": ["mcp"],
      "_comment": "or zero-install: uvx --from 'convo-mem[mcp]' memtool mcp",
      "env": { "MEMTOOL_PROJECT": "/path/to/your/project" }
    }
  }
}

--project, --bank and --stripped work as flags too; MEMTOOL_PROJECT, MEMTOOL_BANK and MEMTOOL_STRIPPED are the environment equivalents, since clients configure servers through either. Resolution is reported on stderr — stdout is the protocol.

Skills

Six Agent Skills ship in the package: recall, related, remember, status, unblock, update. recall is the guardrail — it checks the bank before you explore an idea, rather than after.

memtool skills list                        # where each client looks, what is there
memtool skills install                     # -> .agents/skills (Cursor reads it too)
memtool skills install --client claude     # or claude | cursor | codex | all
memtool skills install --client all --global

One source, copied on demand. list distinguishes current from stale, because a drifted copy an agent still follows is the failure worth catching.

Running from a checkout without installing

PYTHONPATH=src python -m convo_mem.cli <command>

Requirements

Python 3.11+, PyYAML and zstandard (pruned sessions are read back through the zstd archive). The [mcp] extra takes mcp>=1.2 and works on both SDK major versions: 2.x renamed FastMCP to MCPServer and removed the old import path, so the server accepts either. Verified against 1.29.1 and 2.1.0.

The extraction pipeline calls Claude models and is calibrated against specific ones; reading a bank over MCP has no such dependency.