Memshelf MCP server

by ignatenkofi·io.github.ignatenkofi/memshelf-mcp·v0.4.0

No reviews yet

Working memory for AI agents: digest-indexed episodes on a git shelf, recalled a section at a time.

A92/100grade A

Write a review Install

What users say

No reviews yet

Be the first

Safety scan

A92/100

full report

Adoption

Growing

0 stars792 downloads/wk

Reviews

Write one

Nobody has reviewed Memshelf yet.

If you have run it, two minutes of your experience saves the next person an afternoon.

Memshelf tools (15, 2 write)

write = sends, deletes, buys or posts

Read from the package source without running it. The installed server may list more.

memshelf_advise
Report what your context window is made of and what you could put down — breakdown plus ranked proposals; writes nothing. Pass your window's occupants (label, size, live or not); with none it reports the shelf alone.
memshelf_doctor
Diagnose shelf integrity: episode schema, digest contract at rest, leaked secrets, ledger consistency, INDEX budget. Read-only; fixes nothing. `check_remote` adds the network probe for a public remote.
memshelf_import
Retro-shelve an exported dialog without pulling it through context: `discover` lists conversations by content markers, `extract` writes one cleaned conversation to a working file for segmenting and shelving.
memshelf_index
Return the shelf INDEX — the small recall entry point. Read it before answering anything about past work, then recall only what you need.
memshelf_initwrite action
Create (or top up) a memory shelf: layout, categories, INDEX preamble, POLICY.md, shelf.yml. Idempotent; never overwrites existing files.
memshelf_lint_digest
Check a digest against the contract while it is still being written — the same validator `memshelf_shelve` runs, writing nothing. `strict` turns warnings into failures.
memshelf_purgewrite action
Drop episodes past `retain_until`, then reindex. Dry run unless `apply=true`; removes working-tree files only, git history keeps them.
memshelf_rebuild
Regenerate the derived files (ledger.tsv, .meta.json, INDEX.md, stats.svg) from the episodes; `check=true` only reports drift. Hand-run it only on a shelf whose bot is not rendering.
memshelf_recall
Fetch a shelved episode by id, or one `## Section` of it, as a data envelope. Prefer the section when it answers the question.
memshelf_resolve
Settle the two-writers-on-parallel-branches conflict: union derived rows, rebuild INDEX, run doctor. Episode conflicts are reported, never auto-merged; safe outside a conflict too.
memshelf_rollup
Archive a period's episodes behind one digest-of-digests you write, shrinking INDEX; nothing is deleted. Not the answer to `index-bloat`.
memshelf_search
Grep the shelf for episodes matching every query token; returns addresses and snippets. Use when the episode id is unknown.
memshelf_shelve
Offload one closed topic to the shelf as a durable, indexed episode — redaction, digest contract and git commit included. Derived files are not written here — they are rendered by `memshelf_rebuild` or the shelf's bot. Details: docs/tools.md.
memshelf_stats
Report the shelf's token economy: standing cost vs shelved mass, claimed compression, realized savings from logged recalls.
memshelf_sync
Fetch and fast-forward the shelf clone to its remote, writing nothing else — for a clone behind the bot's render or another session's shelve. Refuses on a dirty tree or a diverged branch, with the fix.

Public scan report

scanner v0.1.10 · 2026-10-14 · same rubric, same numbers if you re-run it

no findings

Code scan32 source files scanned25/25
–Live reliabilityno gateway calls yet and no remote to proben/a
–Tool poisoningtools not inspected (local package is not executed); not countedn/a
Auth qualitylocal package, no credentials required12/15
Maintenancelast push 1 days ago15/15
Maintainer identityregistry namespace matches repository owner; GitHub account older than a year8/10

Overall 92/100. Components that don't apply are left out of the denominator. Any critical finding is an F.Rubric Appeal a finding JSON

How Memshelf compares

Against every graded Developer tools MCP server, from our own scans and uptime checks. Updated after each scan run.

Safety score: 92/100; higher than 90% of 1,119 Developer tools servers
Tools: 15; the typical Developer tools server has 7
Tools that change things: 13%; typical: 5%. Fewer write tools means less an agent can break
Downloads a week: 792; more than 90% of 436 Developer tools servers with a package

What its tools let an agent do: 13 read · 2 change

Release history: 2 versions in the registry since 2026-09-10, latest 2026-10-07, typically one every 27 days.

Install Memshelf in Claude Code, Cursor or VS Code

claude mcp add memshelf-mcp -- uvx memshelf-mcp

Add to Cursor

What the publisher says

From the Memshelf repository's README, as published. We do not edit it. Read it on GitHub

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

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:

offloaded to a local shelf as Markdown episodes.

Closed conversation topics, research dumps, and bulky tool output are

preserves decisions, rejected alternatives, artifacts, and open threads.

Each episode carries an LLM-written, contract-validated digest that

recalls exact sections via INDEX → episode → section slice over MCP.

The agent keeps only INDEX.md (kilobytes) + digests in context and

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:

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:

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

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

As a Claude Desktop extension — 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/: a /shelve skill plus SessionStart / SessionEnd / PreCompact hooks.

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

Shortened. The full README is on GitHub.

Nothing above is checked by us. What we check is on the safety report.

Memshelf: common questions

Is Memshelf MCP server safe?: Yes, by our scan: it is graded A (92/100). Read the Memshelf safety report
How do I install Memshelf?: It runs on your machine. Copy the Claude Code, Cursor, VS Code or Claude Desktop config from the install section.
Does Memshelf need an API key?: Not as far as the registry entry and our scan can tell: no credentials are declared or required.
Is Memshelf maintained?: The last commit was 22 days ago (2026-10-13). The latest release is v0.4.0.
What can I use instead of Memshelf?: Servers from other publishers that do the same job: Palinode MCP server, Nexusmem MCP server and Agent Memory MCP server. Compare all Memshelf alternatives.
How does Memshelf compare with other Developer tools MCP servers?: safety score 92/100 (higher than 90% of 1,119 Developer tools servers); tools 15 (the typical Developer tools server has 7); tools that change things 13% (typical: 5%. Fewer write tools means less an agent can break). Full comparison.

Alternatives to Memshelf

Same job from other publishers: the closest match first, then the best rated.

All Memshelf alternatives →

Palinode
Inspectable, correctable project memory in git-versioned Markdown for AI agents.
not reviewed
Established
C
Nexusmem
Local-first memory for AI coding agents: shell history with exit codes, git diffs, docs, MCP.
not reviewed
Growing
A
Agent Memory
Git-native project memory for AI coding agents: Markdown source of truth, reviewable, secret-safe.
not reviewed
Growing
A
Akb
Git-backed org memory for AI agents — hybrid search, tables, files & a URI graph over MCP.
not reviewed
Growing
A
Repowise
Codebase intelligence for AI coding agents — graph, git history, docs, decisions, code health.
not reviewed
Established
B