memshelf-mcp

# memshelf-mcp

> Put your agent's memory on a shelf, hand it the index.

[![PyPI](https://img.shields.io/pypi/v/memshelf-mcp)](https://pypi.org/project/memshelf-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/memshelf-mcp)](https://pypi.org/project/memshelf-mcp/)
[![Glama](https://glama.ai/mcp/servers/ignatenkofi/memshelf-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ignatenkofi/memshelf-mcp)
[![ci](https://github.com/ignatenkofi/memshelf-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ignatenkofi/memshelf-mcp/actions/workflows/ci.yml)
[![security](https://github.com/ignatenkofi/memshelf-mcp/actions/workflows/security.yml/badge.svg)](https://github.com/ignatenkofi/memshelf-mcp/actions/workflows/security.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-ignatenkofi.github.io%2Fmemshelf--mcp-blue.svg)](https://ignatenkofi.github.io/memshelf-mcp/)
[![Sibling: docshelf](https://img.shields.io/badge/sibling-docshelf--mcp-green.svg)](https://github.com/ignatenkofi/docshelf-mcp)

```text
                              _          _  __
 _ __ ___   ___ _ __ ___  ___| |__   ___| |/ _|
| '_ ` _ \ / _ \ '_ ` _ \/ __| '_ \ / _ \ | |_
| | | | | |  __/ | | | | \__ \ | | |  __/ |  _|
|_| |_| |_|\___|_| |_| |_|___/_| |_|\___|_|_|
  ____________________________________________
 | INDEX >> | E-01 | E-02 | E-03 | E-04 | ... |
 |__________|______|______|______|______|_____|
        memory shelves for AI agents
```

## What this is

Long-running agent sessions burn tokens re-sending history and lose detail
to lossy auto-compaction. **memshelf** applies the
[docshelf](https://github.com/ignatenkofi/docshelf-mcp) pattern — tiny index
in context, bodies fetched on demand — to the agent's own working memory:

1. Closed conversation topics, research dumps, and bulky tool output are
   offloaded to a local shelf as Markdown **episodes**.
2. Each episode carries an LLM-written, contract-validated **digest** that
   preserves decisions, rejected alternatives, artifacts, and open threads.
3. The agent keeps only `INDEX.md` (kilobytes) + digests in context and
   **recalls** exact sections via INDEX → episode → section slice over MCP.

Positioning in one sentence: *claude-mem's loop, git's substrate, docshelf's
navigation* — episodic memory you can grep, diff, review, and carry between
hosts. Private and local by default: the standard storage mode is a local
git repo with **no remote configured**. The tool is public; the memory
never is.

## Measured, not promised

One week of dogfooding on the live shelf — full numbers and methodology in
[`docs/demo.md`](docs/demo.md):

| Measure | Result |
|---|---|
| Episodes on the shelf | 34 |
| Standing cost in every session (INDEX + digests) | ~8.6K tokens |
| Shelved mass those episodes replace | ~1.9M tokens — **≈220 : 1** |
| One question answered from memory | ~1.8K tokens (INDEX + one episode) |
| Recall test: fresh agent, INDEX path only | **5 / 5** — zero misses, zero over-fetch |

Tokens are counted as chars/4 everywhere, so the *ratios* are
estimator-independent; absolute counts move with the tokenizer.

## Quick start

As an **MCP server**:

```bash
# Claude Code
claude mcp add memshelf -- uvx memshelf-mcp
```

```jsonc
// Claude Desktop (claude_desktop_config.json)
{
  "mcpServers": {
    "memshelf": { "command": "uvx", "args": ["memshelf-mcp"] }
  }
}
```

As a **Claude Desktop extension** — [`adapters/claude-desktop/`](adapters/claude-desktop/):
an `.mcpb` bundle installed from *Settings → Extensions*, with a **Default
shelf** setting so calls need not repeat the path. Nothing has to be installed
alongside it — not even Python.

As a **Claude Code plugin** — [`adapters/claude-code/`](adapters/claude-code/):
a `/shelve` skill plus SessionStart / SessionEnd / PreCompact hooks.

Or from the **shell** (`pip install memshelf-mcp`, Python ≥ 3.10) — the same
loop, no MCP:

```bash
memshelf init   --shelf ~/my-shelf --name "My working memory"
memshelf shelve --shelf ~/my-shelf --slug 2026-07-23-topic --kind topic \
  --digest "What was decided, what was rejected and why, what stays open." \
  --section "Decisions=What was decided, and what was rejected instead — one line each."
memshelf recall --shelf ~/my-shelf --id 2026-07-23-topic --section Decisions --log
memshelf stats  --shelf ~/my-shelf   # claimed + realized savings
memshelf doctor --shelf ~/my-shelf   # exit 1 on integrity errors
```

`pip install 'memshelf-mcp[semantic]'` adds an embedding sidecar so `search`
also finds paraphrases and the other language (`memshelf semantic build
--shelf ~/my-shelf` once; `MEMSHELF_SEMANTIC=off` turns it off). Optional:
the base install stays grep-only and as light as it is.

## Tool surface

One verb per job; the same names over MCP (`memshelf_*`) and in the CLI
(long-form descriptions: [`docs/tools.md`](docs/tools.md)):

| Tool | What it does |
|---|---|
| `init` | Create (or top up) a memory shelf: docshelf layout, fixed categories |
| `shelve` | Offload one closed topic as a durable, indexed episode; `--amend` rewrites in place |
| `lint_digest` | Validate a digest against the contract without touching the shelf |
| `import` | Retro-shelve a whole exported dialog without pulling it through context |
| `index` | Return the shelf INDEX — the small recall entry point |
| `recall` | Fetch an episode by id, or a single `## Section` of it |
| `search` | Grep the shelf; returns matching episodes |
| `stats` | The shelf's token economy: standing cost vs shelved mass, claimed vs realized |
| `advise` | What your context is made of and what you could put down — proposals only |
| `rebuild` | Regenerate every derived file from the episodes |
| `rollup` | Archive a period behind one digest-of-digests |
| `purge` | Drop episodes past `retain_until`, then reindex — dry run by default |
| `resolve` | Settle multi-writer conflicts: regenerate derived, union the recall log |
| `doctor` | Diagnose: episode schema, digest contract at rest, secret shapes, index bloat |
| `prune-splits` | CLI only — remove H2 split directories git never got (migration for #109) |
| `tags` | CLI only — episodes grouped by frontmatter tag (#18) |
| `graph` | CLI only — who mentions whom: cross-episode id references as JSON or Mermaid (#18) |
| `retro` | CLI only — one quarter of the shelf as a Markdown retrospective (#18) |
| `fork` | CLI only — bootstrap a fresh session from INDEX + selected episodes or sections (#18) |
| `mirror` | CLI only — INDEX (± episodes) as one self-contained HTML page for phone-side reading (#18) |
| `semantic` | CLI only — `build` / `status` / `drop` the embedding sidecar that turns `search` hybrid; lives outside the shelf, needs `pip install 'memshelf-mcp[semantic]'` (#17) |
| `search-bench` | CLI only — hit@1 / hit@k / MRR of grep vs hybrid on a `query<TAB>expected-id` file (#17) |

## The rules the tools enforce

**The digest is a contract, not a convention.** It is the only thing read at
recall before fetching a body, so a weak one devalues the whole episode.
`lint_digest` runs the same validator as `shelve` with no side effects
(`--strict` turns warnings into failures); errors block a shelve, warnings do
not — a pure reference digest legitimately carries no decision marker. A
rejected digest is a feature: the tool prints exactly what to fix and writes
nothing.

**`--amend` re-runs the whole pipeline** — redaction, the digest contract,
composition — so an amended episode is exactly as guarded as a fresh one,
which a hand-edit of the file never is. Amending a slug that is not on the
shelf is an error, not a create.

**The episode is the source; everything else is output.** `ledger.tsv`,
`INDEX.md`, `stats.svg` and each category's `.meta.json` are derived:
`shelve` writes and commits the episode alone, `rebuild` renders the rest —
delete all four and `rebuild` restores them byte-identically. That is what
makes two sessions shelving in parallel a non-event: the merge is clean by
construction. On a shared shelf, let a bot own the derived files on `main` —
ready-to-copy workflows in [`adapters/shelf-repo/`](adapters/shelf-repo/);
`rebuild --adopt` migrates an older shelf once, `rebuild --check` is the
CI guard.

Two consequences worth stating plainly, because getting them wrong costs a
merge conflict:

* **`doctor` reports `no-ledger-row` and `stale-index` immediately after a
  correct `shelve` — on every branch, `main` included.** Nothing is broken:
  the episode is written, the derived files are not rendered yet. They clear on
  the next `rebuild` — the bot's run, on a shelf that has one.
* **Do not rebuild and commit the derived files by hand to silence them.**
  That is exactly the conflict class the split removes: a hand-regenerated
  `ledger.tsv`/`INDEX.md`/`stats.svg` meets the bot's, and the merge stops
  being clean by construction. Wait for the renderer; on a shelf without a bot,
  run `memshelf rebuild --shelf .` as its own step.

If those warnings persist for a *day* while episodes keep arriving, that is a
different state — the renderer is not lagging, it is stopped — and `doctor`
says so separately, as `derived-stale` at error severity. The day is counted
from when the renderer could first see the work, not from the ledger's last
commit: an episode pushed minutes ago onto a shelf whose ledger has not moved
since yesterday says nothing about the renderer, and saying otherwise sent
readers to a manual `rebuild`, which is the conflict this whole split exists
to avoid.

That arrival is read from this clone's reflog for the tracked upstream — the
one local record of *when the ref moved here*. A commit date is not a
substitute: it says when the episode was written, and «shelve now, push when
confirmed» is a documented way to work, so the two can be a working day apart.
Where the reflog cannot say — a fresh clone starts an empty one, which is what
CI and ephemeral agent sessions run in — `doctor` report