How to give Claude Code persistent memory across sessions
Claude Code is stateless by design. Every new session, it starts with no memory of previous work. Iranti adds a persistent memory layer via MCP — one command to set up, and your agent stops starting from scratch.
The problem with session-scoped memory
Claude Code is powerful within a session. It reads files, traces execution, reasons about your codebase, and makes decisions. But when the session ends, none of that reasoning persists. The next session, it re-discovers things it already figured out: the same config key, the same architectural decision, the same bug that was already explained and fixed.
For short tasks, that's fine. For anything long-running — a feature development cycle, a migration, an ongoing debugging effort — the accumulated context loss is expensive. The agent re-reads files it already understood, asks questions it already answered, and makes decisions without the full history.
Iranti solves this with a persistent MCP memory layer that Claude Code writes to and reads from automatically, across sessions and across context window boundaries.
Setup in one command
Iranti ships a stdio MCP server that Claude Code connects to through a project-local .mcp.json. The fast path:
iranti claude-setup writes a .mcp.json to the project root, adds an CLAUDE.md with the Iranti protocol, and registers Claude Code hooks for SessionStart and UserPromptSubmit. Open Claude Code in that project and the Iranti tools are available immediately.
What Claude Code can now do
With Iranti connected, Claude Code gains a set of MCP tools for structured, persistent memory:
iranti_writeStore a fact at a specific entity + key. Survives session end, process restart, and context window overflow.
iranti_attendInject relevant memory before a turn — retrieves facts the agent is likely to need based on the current task.
iranti_queryExact lookup by entity and key. Deterministic: same address always returns the same fact.
iranti_searchHybrid search (lexical + vector) when the exact key isn't known.
iranti_checkpointSave the current task state — what's done, what's next, open risks — so the next session can resume cleanly.
iranti_handshakeSession start ritual: loads operating context, recent decisions, and relevant project state from memory.
What changes in practice
The most immediate change is that Claude Code stops re-reading files it already understood. When a fact — an architectural decision, a config value, an important constraint — is in Iranti, the agent can retrieve it with a single token-efficient lookup instead of re-reading the source file.
We measured this in B14 (Context Economy): over a 15-turn coding session, the Iranti arm used 37% fewer input tokens than the no-memory arm. The gap compounds across turns — the longer the session, the larger the savings.
The second change is continuity. A session that ends mid-task can checkpoint its state. The next session starts by calling iranti_handshake, which loads the checkpoint and relevant context. The agent picks up where it left off without needing a re-briefing from the user.
The third change is shared memory across tools. If you use Codex, GitHub Copilot, or a custom Claude API client alongside Claude Code, they can all point at the same Iranti instance. Facts written in one tool are immediately available in any other.
Honest limits
Iranti's memory is structured — facts need to be written explicitly usingiranti_writewith an entity and key. It doesn't automatically extract memory from the conversation. The agent needs to follow the Iranti protocol (handshake, attend, write, checkpoint) for memory to accumulate reliably.
The current version requires a local PostgreSQL instance with pgvector. Setup handles most of the bootstrap automatically, but it is a real infrastructure dependency. A hosted version that removes this requirement is planned.