memshelf — Manifest

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

Working title: memshelf. Naming alternatives (chatshelf, recall-shelf, context-shelf) are tracked in the Open questions section of ARCHITECTURE.md.

The problem

Long-running agent sessions accumulate context faster than they consume it: conversation turns, research results, verbose tool output, intermediate artifacts. Three bad things follow:

  1. Token burn. The same accumulated history is re-sent and re-processed on every turn. Most of it is never referenced again.
  2. Context rot. Model attention degrades as the window fills; the important 5% drowns in the transient 95%.
  3. Lossy, opaque forgetting. When the window overflows, auto-compaction summarizes with no user control, no durable artifact, and no way to get the detail back. Ask “what did we decide about X three weeks ago?” and the honest answer is gone.

Chat projects have the mirror problem: users re-upload and re-explain the same background in every project because there is no cheap, navigable place for a conversation’s residue to live.

The bet

The docshelf pattern — tiny index in context, bodies fetched on demand — is not specific to documents. It works for anything that can be serialized to Markdown and addressed by a stable path. The agent’s own memory qualifies.

The economics are already measured on the document side: docshelf’s benchmark shows ~3.7K tokens per answered question vs 1.2M for dumping the collection. memshelf inherits that math; the only new costs are the one-time digest written at offload time and the occasional recall fetch.

Hero scenarios (the wedge)

Positioning in order of priority:

  1. The dialog that must not die. A weeks-long working thread — course prep, a research arc, a slow refactor — where today the choice is “burn tokens re-sending history” or “lose the reasoning to compaction”. memshelf is the rescue lane: the thread stays light, and any past decision stays one fetch away. This is the primary story; everything else supports it.
  2. The context advisor. Most users overload context unknowingly — a dead topic still occupying 30K tokens, many-repo sessions dragging in stacked instruction files, stale research dumps. memshelf’s advisor surfaces where the window went and which closed episodes are shelvable (see ROADMAP M2). It is both a trigger mechanism and the discovery/ onboarding moment: “show me what’s eating my context” is the first-run experience.
  3. The archive as raw material. Because episodes are structured Markdown with frontmatter, downstream reuse is nearly free: tag- and graph-views over decisions, retrospectives across a quarter of sessions, and forking a sub-thread — bootstrapping a fresh session from INDEX plus a chosen episode, continuing an old discussion branch without dragging the rest of its history along. None of this is v1 scope; all of it is why the substrate is open (see ROADMAP M3).

Principles

  1. Memory is plain local files; git is a layer, not a requirement. Markdown + JSON sidecars: human-greppable, editable in any editor, portable across tools and vendors, legible even if all memshelf tooling disappears tomorrow. Three storage modes, escalating deliberately: plain (a local directory, no git at all), git-local (default: local repo with auto-commit and no remote configured — history and rollback with zero exfiltration surface), git-remote (explicit opt-in, private remotes only, for multi-machine sync). The fear of “accidentally committing something sensitive” is solved by the absence of a remote, not the absence of git: a local repo with no remote is exactly as private as a plain folder.
  2. The index lives in context; the memory does not. The only artifact permanently in the window is INDEX.md (kilobytes). Everything else is fetched by address, section-sized, on demand.
  3. The agent writes its own memory. Digests are composed at offload time, by the agent that still has the full context — not by a separate summarizer service reading transcripts after the fact. Context locality is the cheapest and most accurate summarization there is; the tool layer only validates the contract (see ARCHITECTURE → Digest contract).
  4. Digest-first. An episode is exactly as useful as its digest. A digest must preserve decisions, rejected alternatives (with reasons), produced artifacts, and open threads — because those are what future turns actually ask about. Bad digests turn the shelf into write-only memory; the design treats digest quality as the top risk.
  5. Private by default. Conversations contain PII and secrets. The default shelf is private/local and is read over MCP (read_document), never via public raw URLs. The raw-URL path is an explicit opt-in for shelves that are genuinely public. A redaction pass runs before anything is written.
  6. Compose with docshelf, don’t fork it. Storage layout, splitting, indexing, search, reading, URL providers — all docshelf, used as a library and/or MCP server. memshelf adds the three layers docshelf deliberately doesn’t have: capture, digesting, and trigger policy.
  7. Explicit over magic (v1). Offloading is a visible action with a visible result; recall is a deliberate index-guided fetch. No auto-RAG injection of “relevant memories” into every prompt — that reintroduces the token burn and pollutes context with false positives.
  8. Persistence at write time; exfiltration never by accident. Unlike docshelf (which stays out of git on purpose), a memory shelf in a git mode auto-commits its own repo on every shelve: sessions are ephemeral, and memory that isn’t persisted the moment it is written is memory lost. This is a deliberate, documented departure from docshelf’s non-goal — scoped strictly to the shelf’s own repo. Pushing is never automatic: adding a remote is a separate guarded step, and doctor fails a memory shelf whose remote is publicly visible.
  9. Host-agnostic core, thin adapters. v1 ships a Claude Code adapter (hooks + skill), but the core library, the episode format, and the MCP/CLI surfaces contain nothing Claude-specific. The shelf a Claude session writes today must be recallable from any other MCP client — or any LLM with mere file access — tomorrow. See ARCHITECTURE → Portability model.

Non-goals

Relationship to docshelf

  docshelf memshelf
Content Documents a human curates (manuals, papers, recipes) Episodes the agent curates (topics, investigations, session digests)
Write path Passive: human drops a file Active loop: triggers decide when to offload
Summaries Human-written titles/descriptions LLM-written digests under a validated contract
Git Deliberately hands-off Auto-commit on shelve (own repo only)
Visibility default Public raw-URL friendly Private, MCP read path
Reused as-is — splitter, indexer, SUBINDEX, search, read, doctor, providers

Success criteria

  1. A working session that has produced >200K tokens of history keeps its live context under a configured budget and still answers “what did we decide about X and why” correctly via recall.
  2. Token savings measured on ≥2 real projects with the methodology of docshelf’s benchmarks/token_savings.py (shelved-and-recalled vs carried-in-context).
  3. A human opening the shelf cold can reconstruct the project’s history from INDEX + digests alone, without reading raw sections.