memshelf-mcp

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

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

Status: M0 complete (Cases A + B), M1 tool surface shipped. The pattern was validated with zero code on a live shelf — measured numbers in docs/demo.md — and the M1 server/CLI now enforces it: memshelf_shelve / recall / index / search / stats / doctor, plus a Claude Code plugin (adapters/claude-code/). Sibling project of docshelf-mcp, which provides the storage/index layer.

What this is

Long-running agent sessions burn tokens re-sending history and lose detail to lossy auto-compaction. memshelf applies the docshelf 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 → SUBINDEX navigation 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.

Quick start

As an MCP server (tools memshelf_init / shelve / recall / index / search / stats / resolve / doctor):

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

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

Or from the shell (pip install memshelf-mcp) — the same loop, no MCP:

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=..."
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

Two sessions shelved on parallel branches and the merge collides in INDEX.md / ledger.tsv / .meta.json / stats.svg? That is the multi-writer conflict class (#58) and it resolves mechanically:

memshelf resolve --shelf ~/my-shelf            # union appends, rebuild derived, doctor
memshelf resolve --shelf ~/my-shelf --commit   # same + complete the merge commit

Conflicting episodes are content, not mechanics — resolve reports them and steps aside.

A rejected digest is a feature: the tool prints exactly what to fix and writes nothing. Measured results from a week of dogfooding are in docs/demo.md.

The memory is vendor-portable, and that is now a measured fact, not a design intention: the same live shelf has been read and cross-written by Claude Code (Anthropic) and Gemini CLI (Google) through one shelf-spec server — protocol and field notes in docs/portability.md.

Documents

Doc	What it covers
docs/MANIFEST.md	Problem, the bet, hero scenarios, principles, non-goals
docs/ARCHITECTURE.md	Episode format, digest contract, storage modes, triggers, MCP tool surface, portability model, privacy, failure modes
docs/LANDSCAPE.md	Prior-art survey (2026-07), platform built-ins, positioning, risks
docs/ROADMAP.md	Milestones M0–M3 with exit criteria
docs/DECISIONS.md	Decision log
docs/M0.md	M0 experiment protocol and results (complete): cases, token ledger, recall test
docs/demo.md	Measured numbers from the dogfood shelf: compression, recall test, doctor findings
docs/portability.md	One memory, multiple AIs — the 2026-07-27 experiment: the dogfood shelf read and written by Claude Code (Anthropic) and Gemini CLI (Google) through the same shelf-spec server
docs/examples/	A worked episode file and a memory-shelf INDEX
adapters/claude-code/	Claude Code plugin: /shelve skill + SessionStart/SessionEnd/PreCompact hooks

Origin

Designed as RFC-0001 in the docshelf-mcp repo (#42, #43, #44); this repo is the project's home from 2026-07-13 on. The docshelf copy is frozen as a historical snapshot.

Related projects

• docshelf-mcp — the sibling project and storage layer: PDFs/Markdown → chat-project-friendly document shelves with the same index-and-fetch economics (measured: ~3.7K tokens vs 1.2M per question). memshelf was born as RFC-0001 in its repo and reuses its splitter/indexer/read/search verbatim.
• The dogfood memory shelf is a private repo — by design (MANIFEST principle 5): the tool is public, the memory never is.

License

MIT — see LICENSE.

---

mcp-name: io.github.ignatenkofi/memshelf-mcp