zipmem-mcp

Endless semantic memory for terminal AI agents — without the bloated context window.

zipmem-mcp is a local-first MCP server + CLI that lets agents like Claude Code carry an entire project's history across sessions while keeping the live context window small. It works by Anchored Compacting: stripping semantic noise, replacing massive code blocks with file-coordinate anchors, and preserving architectural blueprints, schemas, and hard-won lessons verbatim.

No cloud. No API keys. No AI calls on the server side. Your memory lives in a single human-readable JSON file under .zipmem/.

The problem

Long, high-intensity agent sessions fill up the context window:

• Prompt caching only saves money, not space. Cached or not, every re-read of a giant terminal history still consumes window tokens.
• A 5-minute idle invalidates the cloud KV cache. The next turn re-reads the whole history at full price.
• Manual "summarize the session" is lossy and tedious, and dumping raw terminal logs just moves the bloat around.

The approach: Anchored Compacting

Instead of storing the session, zipmem stores its meaning:

Anchors are coordinates, not code — the agent re-reads the file on demand when it actually needs the detail. The result is an endless memory loop where the window stays small but nothing foundational is ever lost.

The intelligence lives in the prompt, not the server. zipmem init injects a Constitutional Directive into your CLAUDE.md. The agent itself produces the compact, structured payload; the server only validates, deduplicates, merges, and persists. That keeps the server dependency-free and instant.

Install

npm install -g zipmem-mcp

Requires Node.js ≥ 18.

Quick start

# 1. Initialize in your project root (once per project)
cd your-project
zipmem init

# 2. Register the MCP server with Claude Code
#    (add -s user to make it available in every project — see below)
claude mcp add -s user zipmem-mcp -- npx zipmem-mcp

That's it. zipmem init:

• creates .zipmem/state.json (your memory store),
• injects the Constitutional Directive into CLAUDE.md (or memory.md, or creates CLAUDE.md),
• adds .zipmem/ to .gitignore (keep memory local — see Shared memory),
• records a checkpoint mode (balanced by default; pass --checkpoint=conservative|aggressive to change it).

From the next session on, the agent loads memory automatically at the start and compacts automatically when you say goodbye or it nears its context limit. You don't run anything by hand.

Manual MCP config

If you register MCP servers via a JSON config (claude_desktop_config.json or similar):

{
  "mcpServers": {
    "zipmem-mcp": {
      "command": "npx",
      "args": ["zipmem-mcp"]
    }
  }
}

The server reads CLAUDE_PROJECT_DIR (set automatically by Claude Code) to find the project's .zipmem/. It otherwise falls back to the nearest .zipmem/ ancestor of the working directory.

Using zipmem across multiple projects

zipmem works per-project, and getting it running everywhere depends on two separate, independent steps. If it works in one project but seems dead in another, one of these is almost always the reason:

1. Register the MCP server at the right scope. Claude Code's claude mcp add defaults to local scope — the server is then only visible inside the one directory where you ran it. In any other project the tools simply don't exist. To register it once for all your projects, use user scope:

claude mcp add -s user zipmem-mcp -- npx zipmem-mcp

Verify what's registered (and at which scope) from inside the project that isn't working:

claude mcp list

If zipmem-mcp isn't listed there, that's the problem — re-add it with -s user (or -s project to share it with a repo via a committed .mcp.json).

2. Run zipmem init in every project. This is per-project, not per-machine. Registering the server is not enough on its own, because init is what:

• creates that project's .zipmem/state.json (without it there's no memory to load), and
• injects the Constitutional Directive into that project's CLAUDE.md. Without the directive the agent never learns to call the tools — the server is running but nothing triggers it, so it looks like "zipmem doesn't work here."

cd your-other-project
zipmem init

Heads-up on project resolution. The server locates memory via CLAUDE_PROJECT_DIR → the nearest .zipmem/ ancestor → cwd. If a project has no .zipmem/ of its own but sits inside another project that does, the agent can silently read/write the parent project's memory. Running zipmem init in each project gives it its own .zipmem/ and avoids this.

Quick checklist when a project "doesn't work":

How the loop works

Session start ──► agent calls zipmem_load_memory ──► regains full context (few tokens)
      │
      │   ... work ...
      │
"we're done" message / context pressure ──► agent calls zipmem_save_and_compact
                                         │
                                         ▼
                          validate → dedup-merge → prune → write .zipmem/state.json

MCP tools

The tool descriptions are written so the agent knows when and why to call them without you prompting it.

Heads-up about exit / quit: these are Claude Code's own CLI commands — they close the terminal instantly, before the agent gets a turn, so they do not trigger zipmem_save_and_compact. To get a clean final save, send a normal chat message first ("we're done", "save", "goodbye"), let the agent compact, then quit. Otherwise durability falls back to your last checkpoint + next-session recovery.

Checkpoint vs. save — the one-line version

Checkpoint = cheap, frequent, "don't lose my progress" insurance (recovered only on the next session if you crash). Save & compact = the authoritative commit to long-term memory that a future zipmem_load_memory reads back. Many checkpoints during a session; one save at the end.

Checkpoint modes

zipmem_checkpoint is the main cost ↔ safety knob. Each checkpoint is agent-generated output, so frequent checkpoints mean more durability but more tokens. You pick the cadence at init time and it's baked into the injected directive (the server treats every checkpoint identically — only the instruction to the agent changes):

zipmem init --checkpoint=balanced     # default