zipmem-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. It is intentionally complete: reading it should be enough to fully understand the project's purpose, architecture, data contracts, runtime behavior, and known limits.

---

1. What this project is

zipmem-mcp is an open-source, local-first MCP (Model Context Protocol) server + CLI that gives terminal AI agents (Claude Code and similar) an endless, low-token long-term memory. It compresses session history via Anchored Compacting and persists it to a single JSON file under .zipmem/, so a new session can restore full project context at near-zero token cost.

It runs entirely on the local machine: no cloud, no API keys, no AI calls on the server side. The only runtime dependencies are @modelcontextprotocol/sdk and zod.

The problem it solves

• Long agent sessions bloat the context window. Prompt caching reduces cost but not window occupancy.
• A ~5-minute idle invalidates the cloud KV cache, forcing full-price re-reads of huge histories.
• Manual "summarize the session" is lossy and tedious; dumping raw terminal logs just relocates the bloat.

Anchored Compacting (the core philosophy)

Instead of storing the session, store its meaning:

• Blueprints — architecture, schemas, decisions, conventions, dependency choices → preserved verbatim.
• Anchors — code blocks are never stored; they become coordinates [file_path -> line_range -> concept]. The agent re-reads the file on demand to expand one.
• Lessons — multi-step bug hunts distilled into one-line summary + root-cause/fix, to prevent regressions.
• Everything else (raw code, dead ends, verbose logs, pleasantries, read-only file dumps) is discarded.

The key architectural bet

Compaction intelligence lives in a prompt directive, not in server code. The agent (LLM) produces the structured payload; the server only validates, normalizes, deduplicates, merges, and persists. This keeps the server dependency-free, zero-latency, and key-free. The server can never compact on its own — it has no LLM.