ahmetakyurt/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*:
| Raw session content | What zipmem keeps |
| --- | --- |
| 200-line code block you just wrote | [src/auth/oauth.ts -> 15-42 -> PKCE flow with refresh-token rotation] |
| A 6-step debugging saga | A one-line **lesson**: _"Stripe webhook must be idempotent — it retries on 5xx"_ |
| Architecture you designed | A **blueprint**, preserved verbatim |
| Repetitive logs, dead ends, pleasantries | _Discarded_ |
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
Requires Node.js ≥ 18.
Quick start
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):
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:
Verify what's registered (and at which scope) from inside the project that isn't working:
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."