Zikkaron

Zikkaron

*Zikkaron (זיכרון) is Hebrew for "memory."*

Your AI forgets you every time you close the tab. Every architecture decision you explained, every debugging rabbit hole you went down together, every "remember, we're using Postgres not SQLite" correction. Gone. You start the next session a stranger to your own tools.

Zikkaron is a persistent memory engine for Claude Code built on computational neuroscience. It remembers what you worked on, how you think, what you decided and why. Not as a dumb text dump that gets shoved into context, but as a living memory system that consolidates, forgets intelligently, and reconstructs the right context at the right time.

26 subsystems. 24 MCP tools. Runs entirely on your machine. One SQLite file.

Two minutes to never repeat yourself again

pip install zikkaron

Add to your Claude Code config:

{

"mcpServers": { "zikkaron": { "command": "zikkaron" } } }

Tell Claude how to use it. Drop this in your global ~/.claude/CLAUDE.md (your home directory, not per-project):

## Memory

• On every new session, call recall with the current project name
• Before starting any task, call get_project_context for the current directory
• After completing significant work, call remember to store decisions and outcomes

Or just let Zikkaron handle it. On every startup, it automatically syncs ~/.claude/CLAUDE.md with the latest instructions via sync_instructions. You set it up once and never think about it again.

What this actually feels like

Monday. You spend an hour debugging a nasty auth token race condition. Claude helps you trace it to a TTL mismatch between Redis and your JWT config. You fix it. Claude stores the memory.

Thursday. A user reports intermittent logouts. You open Claude Code in the same project. Before you even describe the bug, Claude recalls the Redis TTL fix from Monday, checks if it's related, and asks whether the middleware you added is handling the edge case where Redis restarts mid-session.

That's the difference. Not "here's your conversation history." Real recall. The kind where your tools understand the shape of what you've been building, not just the words you typed last time.

Retrieval that actually works

We tested Zikkaron against LoCoMo (Maharana et al., ACL 2024), the standard benchmark for long conversation memory. 10 conversations, 1,986 questions, everything from simple factual lookups to multi-hop reasoning to adversarial trick questions designed to trip you up.

The thing is, there's no LLM running at query time. No API calls. No billion parameter models. Just a 22MB embedding model, a SQLite file, and a bunch of neuroscience algorithms doing the heavy lifting. Most systems that hit numbers like these need GPT-4 in the loop. Zikkaron gets there with Hopfield energy scoring, spreading activation, and a cross-encoder reranker.

BEAM: 10 million tokens of conversation, one memory system

BEAM (Tavakoli et al., ICLR 2026) is the hardest long-term memory benchmark that exists. 10 conversations, each spanning 10 million tokens. 200 probing questions across 10 memory abilities, including three that no prior benchmark tests: contradiction resolution, event ordering, and instruction following.

Every system in the paper collapses at this scale. The best result reported (the LIGHT framework running on Llama-4-Maverick) scores 0.266. Most abilities drop to near-zero at 10 million tokens. Context-window approaches cannot fit it. RAG approaches drown in noise.

Zikkaron scores 0.404 overall, a 52% improvement over the best system in the ICLR 2026 paper.

Seven of ten abilities beat the published state of the art. The biggest gains are on exactly the abilities where structured memory should help most: contradiction resolution (+226%), temporal reasoning (+133%), and knowledge updates (+73%). These are the abilities where every system in the paper scores near zero, because context-window approaches have no mechanism for tracking how facts change or when events occurred. Zikkaron's thermodynamic decay, reconsolidation, and temporal metadata handle these natively.

The three abilities where LIGHT wins (abstention, event ordering, and summarization) reflect genuine limitations. Abstention requires recognizing when information is absent, which benefits from LIGHT's scratchpad that explicitly tracks what has been discussed. Event ordering requires perfect chronological sequencing, not just retrieving the right events. Summarization requires retrieving many source passages simultaneously, and our retrieval budget covers only a fraction of the relevant content.

One important caveat: the BEAM paper's baselines use GPT-4.1-nano as the reader model. We use Claude Opus 4.6, which is substantially more capable. The instruction-following result (0.750 with a retrieval MRR of just 0.086) demonstrates that reader quality contributes to QA scores independently of retrieval quality. Our retrieval metrics (MRR 0.422, Recall@10 0.353) are model-independent and directly comparable to the paper's baselines.

Benchmark configuration: BEAM-10M split, 10 conversations, 200 questions, pair-chunk ingestion matching the paper's RAG mode, per-rubric binary nugget scoring with int() cast matching the paper's evaluation code, Kendall tau-b via scipy for event ordering, fresh database per conversation.

Hippocampal Replay: Context that survives compaction

Here's a problem nobody talks about. Claude Code has a 200k/1M token context window. During long sessions, when that window fills up, it *compacts*: summarizes older messages, strips tool outputs, paraphrases your instructions. Important nuance evaporates. Decisions you anchored early in the conversation dissolve into vague summaries.

Hippocampal Replay fixes this. Named after the neuroscience phenomenon where your brain replays important experiences during sleep to consolidate them into long-term memory, it treats context compaction as the "sleep" and replays what matters when Claude "wakes up."

How it works:

Before compaction hits, a hook fires. Zikkaron drains your active context: what you were working on, which files were open, what decisions you'd made, what errors were unresolved. It stores all of this as a checkpoint.

After compaction, a second hook fires. Zikkaron reconstructs your context intelligently. Not by dumping everything back in, but by assembling the right pieces: your latest checkpoint, any facts you'd anchored as critical, the hottest project memories, and predictions about what you'll need next based on your usage patterns.

You can also be explicit about what matters:

Tool: anchor

content: "We're using the event-sourcing pattern. All state changes go through the event bus." reason: "Architecture constraint"

Anchored memories get maximum protection. They always survive compaction, no matter what.

One-time setup per project:

Tool: install_hooks

project_directory: "/path/to/your/project"

After that, everything is automatic. You don't think about it. You don't call anything manually. The hooks fire, the context drains, the context restores. Your long sessions just... work.

Zero-gap memory (v1.3.0)

Previous versions still had gaps. You'd work on something for an hour, making incremental progress, and Zikkaron's write gate would block half of it because each small step looked "unsurprising" relative to the last. You'd make a critical architecture decision and it would slowly decay into a gist. You'd come back to a new session and Claude would have no idea what you were just doing.

v1.3.0 fixes all of this:

Adaptive write gate. The system now tracks your last 10 stored memories. When you're clearly working on the same task — same directory, same timeframe, similar content — it lowers the surprisal threshold so incremental progress gets through. The gate still blocks noise. It just stops blocking your work.

Decision auto-protection. When you say "decided to use Redis instead of Memcached" or "chose the event-sourcing pattern over CRUD," Zikkaron detects the decision pattern and automatically marks it as protected. Protected memories never compress and never decay fast. Your decisions outlive your sessions.

Automatic action capture. A PostToolUse hook fires after every single tool call Claude makes. File edits, bash commands, searches — all captured into a lightweight action log. The consolidation daemon periodically processes these into real memories. You don't call remember for routine work. The system just knows.

Session context injection. A SessionStart hook fires on every new session and injects your project context — hot memories, anchored facts, recent actions, last checkpoint — directly into Claude's context window. Claude starts every session already knowing what you were doing.

Micro-checkpointing. Instead of checkpointing every 50 tool calls, the system now auto-checkpoints on significant events: errors encountered, decisions made, high-surprise information. Critical state transitions are captured the moment they happen.

Session coherence. Memories created within the last 4 hours get a heat bonus that fades linearly. You'll never hit the "I just told you this 10 minutes ago" problem again.

All hooks work in both stdio and HTTP transport modes — they access the SQLite database directly, no server communication needed.

Project seeding: cold start solved

Zikkaron builds memory organically over sessions. That's great for ongoing work, but what about when you install it on a codebase you've been working on for a year? You'd spend dozens of sessions before Claude has meaningful coverage of your project. By then, you've already repeated yourself fifty times.

seed_project fixes this. One call, and Zikkaron scans your entire project and creates foundational memories from structure, configs, documentation, CI/CD, e