Zikkaron

Persistent memory for Claude Code. 26 cognitive subsystems, 18 MCP tools, runs locally on SQLite.

The Problem

Every time you start a new Claude Code session, it forgets everything. Architecture decisions, debugging history, project conventions, file patterns you explained three times already — all gone. You end up re-explaining your entire codebase from scratch.

Zikkaron fixes this. It gives Claude Code a persistent memory that survives across sessions, consolidates over time, and surfaces the right context when you need it.

Quick Start

pip install zikkaron

Add to your Claude Code MCP config (~/.claude/settings.json):

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

Done. Claude Code now has persistent memory.

Make Claude use it automatically

Add this to your project's CLAUDE.md:

## Memory — Zikkaron
- On every new session, call `recall` with the current project name to load prior context
- Before starting any task, call `get_project_context` for the current working directory
- After completing any significant task, call `remember` to store what was done, decisions made, and outcomes

What It Looks Like

Session 1 — You're debugging a tricky auth issue:

Tool: remember
  content: "Auth tokens expire silently when Redis cache is cold-started.
            Fix: added token refresh middleware in auth/middleware.py.
            Root cause was TTL mismatch between Redis and JWT expiry."
  context: "myapp backend debugging"
  tags: ["auth", "redis", "debugging"]

Session 2 — Days later, a related bug appears. Claude automatically recalls:

Tool: recall
  query: "authentication token issues"

> Memory #42 (heat: 0.87): Auth tokens expire silently when Redis cache
> is cold-started. Fix: added token refresh middleware in auth/middleware.py.
> Root cause was TTL mismatch between Redis and JWT expiry.

No re-explaining. No digging through old conversations. It just remembers.

How It Works

Zikkaron isn't a text file that gets loaded on startup. It's a memory engine built on computational neuroscience:

• Predictive coding write gate — Only stores what's actually new. Redundant information is filtered at ingest.
• Heat-based salience — Frequently accessed memories stay hot. Unused ones decay naturally, like biological memory.
• Sleep consolidation — Background process replays memories, discovers cross-project connections, and compresses old knowledge.
• Reconsolidation — Memories update when retrieved in new contexts, staying accurate as your codebase evolves.
• Fractal hierarchy — Memories cluster into summaries at multiple scales. Drill down from high-level architecture to specific implementation details.
• Knowledge graph — Entities and relationships are extracted and linked. Personalized PageRank surfaces contextually relevant memories.
• Causal discovery — Learns cause-effect relationships from your coding sessions using the PC algorithm.
• Successor representations — Memories that co-occur in similar contexts cluster together, even when their content differs.

All data stays on your machine in a single SQLite database. No cloud, no API calls, no telemetry.

MCP Tools

Zikkaron exposes 18 tools over MCP:

Architecture

Zikkaron runs as a local MCP server. All data stays on your machine in a single SQLite database with WAL mode, FTS5 full-text search, and sqlite-vec for vector similarity.

26 subsystems organized into five tiers:

Advanced Setup

From source

git clone https://github.com/amanhij/Zikkaron.git
cd Zikkaron
pip install -e .

SSE transport

For running as a persistent background server instead of stdio:

zikkaron --transport sse

Then configure Claude Code to connect via URL:

{
  "mcpServers": {
    "zikkaron": {
      "type": "sse",
      "url": "http://127.0.0.1:8742/sse"
    }
  }
}

Default port: 8742. Override with --port. Database defaults to ~/.zikkaron/memory.db, override with --db-path.

Configuration

All settings are configurable via environment variables with the ZIKKARON_ prefix:

See zikkaron/config.py for the full list.

Testing

python -m pytest zikkaron/tests/ -x -q

891 tests across 33 test files covering all subsystems.

References

License

MIT