io.github.ignatenkofi/memshelf-mcp (MCP Server)

The io.github.ignatenkofi/memshelf-mcp MCP server provides “working memory for AI agents,” storing information as digest-indexed episodes on a git shelf. It supports recalling content one section at a time, enabling agents to retrieve specific portions of previously stored material.

🛠️ Key Features

Working memory for AI agents
Digest-indexed episodes
Storage on a git shelf
Section-at-a-time recall

🚀 Use Cases

Persisting and reusing agent context across steps
Retrieving a specific section of prior stored episodes for follow-up reasoning

⚡ Developer Benefits

Structured episode indexing via digests
Deterministic recall granularity (one section at a time)

⚠️ Limitations

Available details describe memory, storage, and section recall; no additional tool interfaces, configuration, or constraints are provided in the source data.

memshelf-mcp

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

text

                              _          _  __
 _ __ ___   ___ _ __ ___  ___| |__   ___| |/ _|
| '_ ` _ \ / _ \ '_ ` _ \/ __| '_ \ / _ \ | |_
| | | | | |  __/ | | | | \__ \ | | |  __/ |  _|
|_| |_| |_|\___|_| |_| |_|___/_| |_|\___|_|_|
  ____________________________________________
 | 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:

Closed conversation topics, research dumps, and bulky tool output are offloaded to a local shelf as Markdown episodes.
Each episode carries an LLM-written, contract-validated digest that preserves decisions, rejected alternatives, artifacts, and open threads.
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 / doctor):

bash

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

jsonc

// 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:

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

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.

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