Zikkaron

Zikkaron（זיכרון）はヘブライ語で「記憶」を意味します。

タブを閉じるたびに、あなたのAIはあなたのことを忘れてしまいます。説明したアーキテクチャの決定、一緒に潜ったデバッグの迷路、そして「覚えておいて、PostgresではなくSQLiteを使っているんだ」という修正のひとつひとつ。すべて消えてしまいます。次のセッションを、自分のツールにとっての他人として始めることになります。

Zikkaronは、計算神経科学に基づいて構築されたClaude Code用の永続メモリエンジンです。何に取り組んだか、どのように考えるか、何を決定し、なぜそうしたかを記憶します。コンテキストに押し込まれるだけの単純なテキストダンプではなく、統合し、知的に忘却し、適切なタイミングで適切なコンテキストを再構築する、生きたメモリシステムです。

26のサブシステム。24のMCPツール。完全にあなたのマシン上で動作します。SQLiteファイルは1つだけ。

二度と繰り返さないための2分

pip install zikkaron

Claude Codeの設定に追加してください：

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

Claudeに使い方を教えます。これをグローバルの ~/.claude/CLAUDE.md（プロジェクトごとではなく、ホームディレクトリ）に置いてください：

## 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

あるいは、Zikkaronに任せるだけでも構いません。起動のたびに、sync_instructions を使って ~/.claude/CLAUDE.md を最新の指示と自動的に同期します。一度設定すれば、あとは何も考える必要はありません。

Related MCP server: memory-mcp

実際の体験はこんな感じ

月曜日。 厄介な認証トークンの競合状態のデバッグに1時間費やします。Claudeは、それがRedisとJWT設定の間のTTL不一致に起因すると特定するのを手伝ってくれます。修正すると、Claudeはその記憶を保存します。

木曜日。 ユーザーが断続的なログアウトを報告します。同じプロジェクトでClaude Codeを開きます。バグを説明する前に、Claudeは月曜日のRedis TTL修正を思い出し、関連するかどうかを確認し、追加したミドルウェアがRedisのセッション途中再起動というエッジケースを処理しているかどうかを尋ねます。

それが違いです。「これが会話履歴です」ではありません。本当の想起です。あなたのツールが、前回入力した言葉だけでなく、あなたが構築してきたものの全体像を理解する、そういう想起です。

実際に機能する検索

私たちはZikkaronを、長い会話の記憶の標準ベンチマークである LoCoMo（Maharana et al., ACL 2024）でテストしました。10の会話、1,986の質問。単純な事実検索からマルチホップ推論、あなたを混乱させようとする敵対的なトリック質問まで、あらゆるものが含まれます。

重要なのは、クエリ時にLLMが動作していないことです。API呼び出しもありません。数十億パラメータのモデルもありません。あるのは22MBの埋め込みモデル、SQLiteファイル、そして重労働を担う一連の神経科学アルゴリズムだけです。このような数値を達成するほとんどのシステムは、GPT-4をループに組み込む必要があります。Zikkaronは、Hopfieldエネルギー・スコアリング、拡散活性化、クロスエンコーダー・リランカーによってそこに到達します。

BEAM：1000万トークンの会話をひとつのメモリシステムで

BEAM（Tavakoli et al., ICLR 2026）は、現存する中で最も難しい長期記憶ベンチマークです。10の会話があり、それぞれが1000万トークンに及びます。10の記憶能力にわたる200のプローブ質問があり、そのうち3つ（矛盾解決、イベント順序付け、指示追従）は、これまでのどのベンチマークもテストしていません。

このスケールでは、論文内のすべてのシステムが崩壊します。報告された最良の結果（Llama-4-Maverick上で動作するLIGHTフレームワーク）は0.266です。ほとんどの能力は1000万トークンでほぼゼロに落ち込みます。コンテキストウィンドウ方式では収まりません。RAG方式はノイズに溺れます。

Zikkaronは総合0.404を記録し、ICLR 2026論文の最良システムから52%の改善を達成しました。

10の能力のうち7つが、発表された最先端を上回りました。最大の改善は、まさに構造化メモリが最も役立つはずの能力、つまり矛盾解決（+226%）、時間推論（+133%）、知識更新（+73%）で達成されています。これらは、論文内のすべてのシステムがほぼゼロに近いスコアとなる能力です。コンテキストウィンドウ方式には、事実がどのように変化したか、いつイベントが発生したかを追跡するメカニズムがないからです。Zikkaronの熱力学的減衰、再固定化、時間メタデータは、これらをネイティブに処理します。

LIGHTが勝る3つの能力（棄権、イベント順序付け、要約）は、実際の限界を反映しています。棄権には、情報が存在しないことを認識する必要があり、これは、何が議論されたかを明示的に追跡するLIGHTのスクラッチパッドの恩恵を受けます。イベント順序付けには、正しいイベントを検索するだけでなく、完全な時系列順序付けが必要です。要約には、多くのソースパッセージを同時に検索する必要があり、私たちの検索予算は関連コンテンツの一部しかカバーしません。

重要な注意点が1つあります。BEAM論文のベースラインは、リーダーモデルとしてGPT-4.1-nanoを使用しています。私たちは、はるかに高性能なClaude Opus 4.6を使用しています。指示追従の結果（検索MRRがわずか0.086で0.750）は、リーダーの品質が検索品質とは独立にQAスコアに寄与することを示しています。私たちの検索メトリクス（MRR 0.422、Recall@10 0.353）はモデルに依存せず、論文のベースラインと直接比較可能です。

ベンチマーク構成：BEAM-10M分割、10の会話、200の質問、論文のRAGモードに一致するペアチャンク取り込み、論文の評価コードに一致するint()キャスト付きのルーブリックごとのバイナリナゲットスコアリング、イベント順序付けにはscipyによるKendall tau-b、会話ごとに新しいデータベース。

海馬リプレイ：圧縮を生き延びるコンテキスト

誰も語らない問題があります。Claude Codeには200k/1Mトークンのコンテキストウィンドウがあります。長時間のセッション中にそのウィンドウが満杯になると、圧縮が行われます。古いメッセージを要約し、ツールの出力を削り、あなたの指示を言い換えます。重要なニュアンスは蒸発します。会話の早い段階で固定した決定は、曖昧な要約に溶けていきます。

Hippocampal Replayはこれを修正します。脳が睡眠中に重要な経験を再生して長期記憶に固定するという神経科学の現象にちなんで名付けられたこの機能は、コンテキストの圧縮を「睡眠」とみなし、Claudeが「目覚めた」ときに重要なことを再生します。

仕組み：

圧縮が発生する前に、フックが発火します。Zikkaronはアクティブなコンテキストを排出します。何に取り組んでいたか、どのファイルが開いていたか、どのような決定を下したか、どのエラーが未解決だったか。これらすべてをチェックポイントとして保存します。

圧縮後、2番目のフックが発火します。Zikkaronはコンテキストを知的に再構築します。すべてをそのまま戻すのではなく、適切な断片を組み立てます。最新のチェックポイント、重要として固定した事実、最もホットなプロジェクト記憶、そして使用パターンに基づく次に必要になるものの予測です。

何が重要かを明示することもできます：

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

固定された記憶は最大限の保護を受けます。何があっても、常に圧縮を生き延びます。

プロジェクトごとの一度きりの設定：

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

その後は、すべて自動です。考える必要はありません。手動で何かを呼び出す必要もありません。フックが発火し、コンテキストが排出され、コンテキストが復元されます。長いセッションが、ただ...機能するのです。

ゼロギャップメモリ（v1.3.0）

以前のバージョンにはまだギャップがありました。1時間かけて何かに取り組み、少しずつ進歩しても、Zikkaronの書き込みゲートはその半分をブロックしていました。なぜなら、それぞれの小さなステップが前のステップに比べて「驚きがない」ように見えたからです。重要なアーキテクチャ決定を下しても、それはゆっくりと要旨へと劣化していきました。新しいセッションに戻ると、Claudeはあなたが何をしていたのかまったくわかりませんでした。

v1.3.0はこれらすべてを修正します：

適応型書き込みゲート。 システムは現在、最後に保存された10件の記憶を追跡します。同じタスク（同じディレクトリ、同じ時間枠、類似したコンテンツ）に明確に取り組んでいる場合、驚きのしきい値を下げて、段階的な進歩が通過できるようにします。ゲートは依然としてノイズをブロックします。ただ、あなたの作業をブロックするのをやめるだけです。

決定の自動保護。 「MemcachedではなくRedisを使うことにした」とか「CRUDではなくイベントソーシングパターンを選んだ」と言うと、Zikkaronは決定パターンを検出し、自動的に保護済みとしてマークします。保護された記憶は決して圧縮されず、急速に減衰することもありません。あなたの決定はセッションよりも長生きします。

自動アクションキャプチャ。 Claudeが行うすべてのツール呼び出しの後に PostToolUse フックが発火します。ファイル編集、bashコマンド、検索——すべて軽量なアクションログにキャプチャされます。統合デーモンが定期的にこれらを処理して実際の記憶にします。日常的な作業のために remember を呼び出す必要はありません。システムが自動的に把握します。

セッションコンテキスト注入。 新しいセッションのたびに SessionStart フックが発火し、プロジェクトのコンテキスト（ホットな記憶、固定された事実、最近のアクション、最後のチェックポイント）をClaudeのコンテキストウィンドウに直接注入します。Claudeは、あなたが何をしていたかをすでに知った状態で、すべてのセッションを開始します。

マイクロチェックポイント。 50回のツール呼び出しごとにチェックポイントを作成する代わりに、システムは現在、重要なイベント（遭遇したエラー、下した決定、高い驚きの情報）で自動チェックポイントを作成します。重要な状態遷移は、発生した瞬間にキャプチャされます。

セッションの一貫性。 過去4時間以内に作成された記憶は、線形に減衰するヒートボーナスを得ます。「10分前に言ったばかりだよ」という問題に再び直面することはありません。

すべてのフックはstdioとHTTPの両方のトランスポートモードで動作します。SQLiteデータベースに直接アクセスするため、サーバー通信は不要です。

プロジェクトシーディング：コールドスタートの解決

Zikkaronはセッションを通じて有機的に記憶を構築します。進行中の作業には最適ですが、1年間取り組んできたコードベースにインストールした場合はどうでしょうか？Claudeがプロジェクトを有意義にカバーするまでに、何十ものセッションを費やすことになります。その頃には、すでに50回も同じことを繰り返しているでしょう。

seed_projectはこの問題を解決します。1回の呼び出しで、Zikkaronはプロジェクト全体をスキャンし、構造、設定、ドキュメント、CI/CD、エントリーポイント、コンポーネント別サマリーから基礎となるメモリを作成します。Claudeは、プロジェクトが何であるか、何で構築されているか、どのように編成されているかを既に把握した状態で次のセッションを開始します。

# CLI
zikkaron seed /path/to/your/project

# Preview without storing
zikkaron seed /path/to/your/project --dry-run

または、Claude Code内からMCPツールとして呼び出すこともできます：

Tool: seed_project
  directory: "/path/to/your/project"

抽出される内容：

• プロジェクト概要 — 名前、技術スタック、ファイル数、ディレクトリツリー

• 設定ファイル — package.json、pyproject.toml、Cargo.toml、go.mod、および15以上のその他のファイル。regexスクレイピングではなく、適切にパースされます（TOMLはtomllib、JSONはjson）。依存関係、スクリプト、ワークスペース、ビルドバックエンド — すべて抽出されます。

• ドキュメント — README、ARCHITECTURE、CONTRIBUTING、CLAUDE.md、CHANGELOG

• CI/CD — GitHub Actions、GitLab CI、Jenkins、Travis、Azure Pipelines

• エントリーポイント — main.*、index.*、app.*、server.*、__main__.py

• コンポーネント別サマリー — monorepo対応。最上位レベルのディレクトリだけでなく、ネストされた設定ファイル（packages/web/package.json、services/api/Cargo.toml）を探すことでサブプロジェクトの境界を検出します。

再実行を前提とした設計。 再シードすると、古いシードメモリに追記するのではなく、きれいに置き換えられます。プロジェクトが進化したら再シードすることで、メモリは現在の状態を反映します。すべてのシードメモリは識別用に_seedタグが付けられます。

ヒートの差別化。 すべてのシードメモリが同等というわけではありません。プロジェクト概要とドキュメントは、コンポーネントのファイル一覧（0.5）よりも高いヒート（0.85-0.9）で始まります。Claudeは重要な情報を最初に提示します。

LongMemEval

当社は、チャットアシスタントにおける長期的なインタラクティブメモリを評価する現在の標準である完全なLongMemEvalベンチマーク（Wu et al., ICLR 2025）を実行しました。6つのカテゴリにわたる500の人間が厳選した質問が、それぞれ約40セッションの会話履歴（約115kトークン）に埋め込まれています。このベンチマークは、LoCoMoではテストされないことをテストします：アシスタントが言ったことを想起できるか（ユーザーだけでなく）、情報が時間とともに変化するタイミングを追跡できるか、自分が知らないことを知っているか、数週間離れたセッションをまたいで推論できるか、です。

このデータセットに対する論文の最高報告検索性能は、Recall@10で78.4%でした。Zikkaronは検索ループにLLMを一切使わずに96.7%を達成しています。

カテゴリ別の検索結果の内訳：

知識更新が完璧なMRRを獲得したのは、ヒートベースの減衰が、同じ事実の古いバージョンより新しい情報を自然に上位へ押し上げるためです。これはベンチマーク向けに設計されたわけではありません。熱力学モデルがそう動作するというだけです。

時間的推論は最も難しいカテゴリであり、当社のMRRが0.902と最も低くなっていますが、それでも正しいメモリが通常は上位2件に入ることを意味します。「何週間前にXに参加したのか」のような質問はセッションのタイムスタンプとの照合を必要としますが、当社の埋め込みベースの検索は、メモリコンテンツに直接埋め込む時間メタデータを通じてこれを処理します。

完全なQA評価（Claudeを読み手と判定者の両方として使用）では、全体精度75.6%を達成し、知識更新（85.9%）とアシスタント想起（94.6%）で際立った性能を示しました。マルチセッション推論（54.9%）が主なギャップですが、これは読み手の統合の問題であり、検索の問題ではありません。マルチセッションの質問では95.8%の確率で正しいセッションを取得できています。読み手は、それらの間で情報を結び付ける作業をもう少し行う必要があるだけです。

ベンチマーク構成：LongMemEval_Sバリアント、ラウンドレベルのメモリ分解、質問ごとの新しいデータベース、500の質問をエンドツーエンドで評価。

内部の科学

Zikkaronは、データベースが行を保存するようにはメモリを保存しません。むしろ、脳が経験を扱うようにメモリを扱います。

メモリには温度があります。 すべてのメモリは高温で始まります。アクセスし続ければ高温を保ちます。アクセスしなければ冷えていきます。しきい値を下回ると圧縮されます：最初は要点に、次にタグに、そして最終的には完全に消えていきます。これはバグではありません。これは率歪み最適忘却（rate-distortion optimal forgetting）であり、脳が何を保持する価値があるかを判断するために使うのと同じ数学的枠組みです。重要なメモリは圧縮に抵抗します。驚きを与えるメモリはヒートが上昇します。退屈で冗長なメモリは静かに消えていきます。

ストレージには門番がいます。 すべてに記憶される価値があるわけではありません。Zikkaronは既に知っていることの予測モデルを維持し、期待に反する情報だけを保存します。同じことを二度伝えると、書き込みゲートは二度目の試みをブロックします。これは予測コーディングです：大脳新皮質が感覚入力をフィルタリングするために使うのと同じメカニズムです。予測誤差だけが通過できます。

検索はメモリを変化させます。 新しいコンテキストでメモリを想起すると、それは単に受動的に返されるだけではありません。検索コンテキストと保存コンテキストを比較し、不一致が十分にあれば*再固定化（reconsolidates）*します：現在真実であることを反映するようにメモリを更新します。深刻な不一致は古いバージョンをアーカイブし、新しいバージョンを作成します。これは実際の神経科学です。Naderらは2000年に、想起されたメモリは不安定になり書き換えられ得ることを示しました。コードベースが進化するにつれて、Zikkaronのコードベースに関するメモリも進化します。

メモリはスペースを競い合います。 エングラムスロットのプールがあり、各スロットは使用時に急上昇し時間とともに減衰する興奮性スコアを持ちます。新しいメモリが到着すると、最も興奮性の高いスロットに入ります。同じスロット内のメモリは時間的にリンクされ、内容に共通点がなくても関連する経験の連鎖を形成します。これは、実際のニューロンがCREB依存の興奮性を通じてエングラムを割り当てる方法をモデル化しています。

バックグラウンド統合は睡眠のように動作します。 アイドル状態になると、アストロサイトデーモンが起きて最近の経験を処理します。エンティティと関係を抽出し、知識グラフを構築し、類似重複をマージし、因果連鎖を発見し、ランダムなメモリペアが比較されて新しい接続が生まれる「夢のリプレイ」を実行します。4つのドメイン特化プロセスが、コード構造、アーキテクチャ上の決定、エラ

高度なセットアップ

ソースから

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

SSEトランスポート

stdioの代わりに永続的なバックグラウンドサーバーとして実行:

zikkaron --transport sse

次にClaude CodeをそのURLに向けます:

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

デフォルトポートは8742です。--portで上書きできます。データベースはデフォルトで~/.zikkaron/memory.dbになり、--db-pathで上書きできます。

設定

すべての設定はZIKKARON_環境変数プレフィックスを使用します:

完全なリストはzikkaron/config.pyにあります。

テスト

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

全サブシステムをカバーする34のテストファイルにわたる998のテスト。

参考文献

Ramsauer et al. "Hopfield Networks is All You Need" (ICLR 2021, arXiv:2008.02217)

Nader, Schafe, LeDoux. "Fear memories require protein synthesis in the amygdala for reconsolidation after retrieval" (Nature 406, 2000)

Osan, Tort, Bhatt, Amaral. "Three outcomes of reconsolidation" (PLoS ONE, 2011)

McClelland, McNaughton, O'Reilly. "Why there are complementary learning systems in the hippocampus and neocortex" (Psychological Review 102, 1995)

Sun et al. "Organizing memories for generalization in complementary learning systems" (Nature Neuroscience 26, 2023)

Stachenfeld, Botvinick, Gershman. "The hippocampus as a predictive map" (Nature Neuroscience 20, 2017)

Whittington et al. "The Tolman-Eichenbaum Machine" (Cell 183, 2020)

Spirtes, Glymour, Scheines. Causation, Prediction, and Search (MIT Press, 2000)

Kanerva. Sparse Distributed Memory (MIT Press, 1988)

Frady, Kleyko, Sommer. "Variable Binding for Sparse Distributed Representations" (IEEE TNNLS, 2022)

Toth et al. "Optimal forgetting via rate-distortion theory" (PLoS Computational Biology, 2020)

Josselyn, Frankland. "Memory allocation: mechanisms and function" (Annual Review Neuroscience 41, 2018)

Rashid et al. "Competition between engrams influences fear memory formation and recall" (Science 353, 2016)

Zhou et al. "MetaRAG: Metacognitive Retrieval-Augmented Generation" (ACM Web, 2024)

ライセンス

MIT