Metadata-Version: 2.4
Name: convo-mem
Version: 0.1.1
Summary: A memory bank distilled from coding-agent session history, served over MCP
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6
Requires-Dist: zstandard>=0.22
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == "mcp"

<!-- mcp-name: io.github.new-aige-codez/memtool -->

# 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

```bash
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:

```bash
pip install -e ".[mcp]"
```

## Use

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

```json
{
  "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.

```bash
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

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