Claude Codeで何時間も議論し、設計を決め、ハマりどころを越えた——その会話は、セッションを閉じた瞬間にほとんど消えます。 次に同じプロジェクトを開いても、AIは過去の決定を覚えていません。 この「会話のたびに知識がリセットされる」問題に、別のアプローチで答えるOSSが「Claude Memory Compiler」（リポジトリ名: coleam00/claude-memory-compiler、内部的には LLM Personal Knowledge Base）です。

本記事は、公式READMEとAGENTS.mdを一次ソースに、このプロジェクトが「会話をどう知識へコンパイルするか」を実務目線で整理します。

30秒で理解する Claude Memory Compiler

・Claude Codeとの会話を、検索可能な個人知識ベースへ自動コンパイルするOSS。Andrej Karpathy氏のLLM Knowledge Baseアーキテクチャを、Web記事ではなく「自分の会話」に適用した派生版
・SessionEnd/PreCompactフックが会話を自動キャプチャ→flush.pyがClaude Agent SDKで重要点を抽出→daily/に追記→compile.pyが概念記事へ組み上げ→SessionStartフックで次のセッションに注入、というループ
・検索はRAGもベクトルDBも使わず、markdownのindex.mdをLLMが読んで関連記事を選ぶ方式。個人規模（50〜500記事）ではこの方が精度が高い、というのが設計の前提
・認証はClaude Code組み込みの認証情報を使い、APIキー不要。個人利用はClaudeサブスクの範囲内でカバーされ、別建てのAPI課金は発生しない
・知識は[[wikilinks]]付きの純粋なmarkdown。Obsidianにそのまま載るし、独自の記事タイプも追加できる

このプロジェクトの設計は、LLMコーディングの暴走を止める文脈で語られたKarpathy流CLAUDE.md徹底解説｜LLMコーディング暴走を止める4原則と30kスターの理由とも地続きです。 「AIに長期記憶を持たせる」という同じ問題系を、フックと自動コンパイルで解こうとするのが本プロジェクトの立ち位置です。

Claude Memory Compilerとは何か——「会話＝ソースコード」という発想

最大の発想転換は、AGENTS.mdが冒頭で掲げるコンパイラのアナロジーです。 このプロジェクトは、会話を「コンパイルされるソースコード」として扱います。

コンパイラ世界このプロジェクト役割
ソースコードdaily/会話ログ＝生の素材
コンパイラLLM知識を抽出・整理する
実行ファイルknowledge/構造化された検索可能な知識
テストスイートlint一貫性のヘルスチェック
ランタイムqueries知識を使う段階

ポイントは、人間が手作業で知識を整理しないことです。 あなたは会話をするだけで、抽出・相互参照・保守はLLMが担う。 Karpathy氏のオリジナルが外部のWeb記事をクリップして取り込むのに対し、本プロジェクトは「自分とClaudeの会話」を素材にする点が決定的に違います。

READMEはまた、コスト面の立ち位置も明確にしています。 Anthropicは、Claude Agent SDKの個人利用が既存のClaudeサブスクリプション（Max/Team/Enterprise）でカバーされると明確化しており、メモリのflushに別建てのAPIクレジットは不要です。 READMEはこれを、メモリflushにAPI課金が必要なOpenClawとの差として挙げています。

3層アーキテクチャ——daily / knowledge / AGENTS.md

知識ベースは明確な3層に分かれます。 それぞれ「誰が所有するか」が違うのが理解のカギです。

flowchart TD subgraph L1[Layer 1 daily 会話ログ 追記専用] D1[2026-06-15.md] D2[Sessions / Key Exchanges
Decisions / Lessons / Action Items] end subgraph L2[Layer 2 knowledge LLMが所有] IDX[index.md
全記事の目次 検索の主役] C[concepts 原子的な知識] CN[connections 概念をまたぐ気づき] QA[qa クエリ回答の恒久保存] LOG[log.md 追記専用ビルドログ] end subgraph L3[Layer 3 AGENTS.md] SC[コンパイラ仕様書
記事フォーマットと手順] end D1 --> IDX SC -. 仕様を与える .-> IDX IDX --> C IDX --> CN IDX --> QA

第1層 daily/ は会話ログで、追記専用・後から編集しない「不変の素材」です。 1ファイル1日で、# Daily Log: YYYY-MM-DD の下にセッションごとのContext・Key Exchanges・Decisions Made・Lessons Learned・Action Itemsが並びます。

第2層 knowledge/ はLLMが全面的に所有するディレクトリで、人間は読むがほとんど直接編集しません。 ここがコンパイル結果の「実行ファイル」にあたります。

記事タイプディレクトリ役割
Conceptknowledge/concepts/1記事1テーマの原子的知識。事実・パターン・決定・好み・教訓
Connectionknowledge/connections/2つ以上の概念をまたぐ非自明な関係の統合
Q&Aknowledge/qa/クエリの回答を恒久保存し、将来の検索を賢くする
index.mdknowledge/全記事を1行要約付きで並べる目次。検索時に最初に読む
log.mdknowledge/compile/query/lintの操作を時系列で記録する追記専用ログ

各記事はYAMLフロントマター（title・tags・sources・created・updatedなど）を持ち、本文はObsidian形式の[[wikilinks]]で相互リンクされます。 Concept記事なら、2〜4文のコア説明＋Key Points＋Details＋Related Concepts＋出典のSources、という百科事典スタイルです。

第3層 AGENTS.md は、LLMに「どうコンパイルし、どう保守するか」を教える仕様書、いわば「コンパイラ仕様」です。 記事フォーマット・フック構造・スクリプト内部・コスト・カスタマイズまでが書かれ、AIエージェントがこのシステムを理解・改造・再構築するための情報源になっています。

中心にあるのがindex.mdです。 これは全記事をテーブルで一覧する目次で、検索の主役です。 LLMはどんなクエリでもまずこのindexを読み、関連する記事を選んで全文を読みます。 ベクトル検索の代わりに、この目次がルーティングの役目を果たします。

フックの仕組み——会話を自動キャプチャする3つのフック

このプロジェクトの自動化は、.claude/settings.jsonに登録された3つのフックで成り立ちます。 設定は次のようにシンプルな相対パスで書かれます。

{
  "hooks": {
    "SessionStart": [{ "matcher": "", "hooks": [{ "type": "command", "command": "uv run python hooks/session-start.py", "timeout": 15 }] }],
    "PreCompact":   [{ "matcher": "", "hooks": [{ "type": "command", "command": "uv run python hooks/pre-compact.py", "timeout": 10 }] }],
    "SessionEnd":   [{ "matcher": "", "hooks": [{ "type": "command", "command": "uv run python hooks/session-end.py", "timeout": 10 }] }]
  }
}

それぞれの役割を整理します。

・SessionStart：純粋なローカルI/Oで、API呼び出しなし・1秒未満で完了。knowledge/index.mdと直近のdaily logを読み、additionalContextとしてセッション冒頭に注入する。最大2万文字。これでClaudeは毎回、知識ベースの目次を持った状態で会話を始める
・SessionEnd：stdin経由でフック入力（session_id・transcript_path・cwd）を受け取り、生のJSONLトランスクリプトを一時ファイルへコピー（フック内ではパースせず高速に保つ）。その後flush.pyをフックから切り離したバックグラウンドプロセスとして起動する
・PreCompact：SessionEndと同じ構造で、Claude Codeがコンテキストを自動コンパクトする直前に発火する。空のtranscript_pathを防ぐガードを持つ

ここで効いてくるのが、なぜPreCompactとSessionEndの両方なのかという設計です。 長時間セッションは、閉じる前に何度も自動コンパクトが走ります。 PreCompactがなければ、途中の文脈はSessionEndが発火する前に要約で消えてしまう。 PreCompactは「要約に飲まれる前に中間文脈を捕まえる」安全網なのです。

フックは会話を「捕まえる」だけで、重い処理はしません。 重い抽出はバックグラウンドのflush.pyに逃がし、Claude Codeの操作感を止めない——この責務分離が、常駐型メモリツールを実用にする勘所です。

バックグラウンドのflush.py

flush.pyは両フックから切り離して起動されます（WindowsはCREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS、Mac/Linuxはstart_new_session=True）。 これでClaude Code側のフックプロセスが終了しても生き残ります。

flush.pyの処理は次の流れです。

・CLAUDE_INVOKED_BY=memory_flush環境変数をセットし、フックの再帰発火を防ぐ
・一時.mdファイルから抽出済みの会話文脈を読む
・文脈が空、または同一セッションが60秒以内にflush済みならスキップ（重複排除）
・Claude Agent SDKをallowed_tools=[]・max_turns=2で呼び、「何を保存する価値があるか」をClaude自身に判断させる。結果は構造化された箇条書きか、保存不要ならFLUSH_OK
・結果をdaily/YYYY-MM-DD.mdに追記し、一時ファイルを掃除する
・18時以降の自動コンパイル：ローカル時刻が18時（COMPILE_AFTER_HOUR = 18）を過ぎ、当日のdaily logが前回コンパイル時からハッシュ変化していれば、compile.pyを別のデタッチプロセスとして起動する

この最後の一手が効いています。 cronも手動トリガーもなしに、1日1回コンパイルが自動で走る。 日中はflushが軽くログを溜め、夜にまとめて知識へ組み上げる、という自然なリズムです。

インストール——エージェントに指示するだけ

READMEの推奨は、AIコーディングエージェントに自然文で頼む方式です。

「https://github.com/coleam00/claude-memory-compilerをこのプロジェクトにクローンして。Claude Codeのフックを設定し、会話が自動でdaily logにキャプチャされ、知識ベースにコンパイルされ、次のセッションに注入されるようにして。仕組みの技術リファレンスはAGENTS.mdを読んで。」

エージェントは次を行います。

・リポジトリをクローンし、uv syncで依存をインストールする
・.claude/settings.jsonを自分のプロジェクトにコピーする（既存設定がある場合はフックをマージ）
・次にClaude Codeを開いたときからフックが自動で有効になる

そこからは会話が溜まり始めます。 ローカル時刻18時以降、次のセッションflushが当日ログのコンパイルを自動でトリガーします。 もちろん手動でも実行できます。

uv sync                                   # 依存インストール
uv run python scripts/compile.py          # daily logを手動コンパイル

依存はpyproject.tomlに定義され、claude-agent-sdk>=0.1.29・python-dotenv>=1.0.0・tzdata>=2024.1、そしてPython 3.12以上（uv管理）です。 前述の通りAPIキーは不要で、Claude Codeの~/.claude/.credentials.jsonを使います。

使い方——compile / query / lint の3コマンド

日常運用は3つのスクリプトに集約されます。

uv run python scripts/compile.py                     # 新規/変更daily logをコンパイル
uv run python scripts/query.py "question"             # 知識ベースに質問
uv run python scripts/query.py "question" --file-back # 質問し、回答をKBに保存
uv run python scripts/lint.py                         # 7つのヘルスチェック
uv run python scripts/lint.py --structural-only       # 無料の構造チェックのみ

compile.py——コンパイラ本体

compile.pyはClaude Agent SDKの非同期ストリーミングquery()を使います。 AGENTS.mdのスキーマ・現在のindex・既存の全記事・対象のdaily logをまとめたプロンプトを組み立て、Claudeがdaily logを読み、抽出する概念を決め、ファイルを直接書きます。

async for message in query(
    prompt=compile_prompt,
    options=ClaudeAgentOptions(
        cwd=str(ROOT_DIR),
        system_prompt={"type": "preset", "preset": "claude_code"},
        allowed_tools=["Read", "Write", "Edit", "Glob", "Grep"],
        permission_mode="acceptEdits",
        max_turns=30,
    ),
):

permission_mode="acceptEdits"で全ファイル操作を自動承認し、daily logのSHA-256ハッシュをstate.jsonに記録してインクリメンタルに処理します（未変更ファイルはスキップ）。 --allで強制再コンパイル、--fileで単一ファイル指定、--dry-runも用意されています。

query.py——インデックス誘導の検索

query.pyは知識ベース全体（index＋全記事）をコンテキストに読み込み、LLMが関連を選びます。RAGはありません。

uv run python scripts/query.py "What auth patterns do I use?"
uv run python scripts/query.py "What's my error handling strategy?" --file-back

--file-backを付けると、回答をknowledge/qa/にQ&A記事として保存し、indexとlogを更新します。 これが複利のループです——質問するたびに知識ベースが賢くなる。

lint.py——7つのヘルスチェック

lint.pyは知識ベースの一貫性を保つテストスイートです。

チェック種別検出するもの
Broken links構造存在しない記事への[[wikilinks]]
Orphan pages構造被リンクがゼロの記事
Orphan sources構造まだコンパイルされていないdaily log
Stale articles構造コンパイル後に出典ログが変化した記事
Missing backlinks構造AはBにリンクするがBが返さない
Sparse articles構造200語未満の薄い記事
ContradictionsLLM記事間で矛盾する主張

構造チェックは無料、矛盾チェックだけがLLMを使います。 レポートはreports/lint-YYYY-MM-DD.mdに保存されます。

状態はscripts/state.jsonが追跡し、ingested（daily logのハッシュ・コンパイル時刻・コスト）、query_count、last_lint、total_costを持ちます。 last-flush.jsonはflushの重複排除（session_id＋タイムスタンプ）を管理します。どちらもgitignoreされ自動再生成されます。

ユースケース——どんな人に効くか

このプロジェクトが効くのは、「同じAIと長く付き合う」開発者です。

・プロジェクトの設計判断を忘れたくない：なぜライブラリXをYより選んだか、どのアーキテクチャパターンを採ったかが、会話のたびにconcept記事として蓄積される
・ハマりどころを資産化したい：「Zの落とし穴はWのとき動かないこと」といったLessons Learnedが、次のセッション冒頭に自動注入される
・Obsidianで知識をグラフ化したい：[[wikilinks]]付きmarkdownなので、knowledge/にvaultを向ければグラフビュー・バックリンクがそのまま使える
・チームの暗黙知を形式知にしたい：個人スケールの設計だが、認証パターンやエラーハンドリング戦略の「自分の流儀」を明文化する出発点になる

逆に、Web記事や論文を集めたいだけならKarpathy氏のオリジナル、Claude Codeを常駐デーモン化してチャットから操作したいならClaudeClawとは｜Claude Codeを常駐デーモン化しTelegram/Slackから動かすOSSの方が目的に合います。 本プロジェクトはあくまで「会話→知識の自動コンパイル」に特化しています。

類似アプローチとの違い——RAGメモリツールとの比較

「AIに長期記憶を持たせる」系のツールは多くありますが、設計思想がかなり違います。

観点Claude Memory Compiler一般的なRAGメモリ
検索方式LLMがindex.mdを読み記事を選ぶベクトル類似度（埋め込み）
ストレージ純粋なmarkdown＋wikilinksベクトルDB
素材自分のClaude Codeとの会話任意ドキュメント
蓄積トリガーフック＋18時の自動コンパイル手動インデックス化が多い
課金サブスク枠（APIキー不要）埋め込み/生成API課金が多い
可搬性Obsidianでそのまま開けるDB依存でロックインしやすい

なぜRAGを使わないのか——その答えはKarpathy氏の洞察に尽きます。 個人規模（50〜500記事）では、LLMが構造化されたindex.mdを読む方がベクトル類似度より精度が高い。 LLMは「本当は何を聞いているか」を理解しますが、コサイン類似度は似た単語を拾うだけです。 RAGの仕組みそのものを知りたい場合はRAGとは？仕組み・構築・ベクトルDB選定までの2026年実装マップと読み比べると、この設計判断の意味がよく見えます。

制限と注意点

導入前に押さえておきたい現実的な制約です。

・スケール上限がある：約2,000記事を超えると、index自体がコンテキストウィンドウを超え、ハイブリッドRAGが必要になる。あくまで個人規模の知識ベース向け設計
・コストは記事数に比例して上がる：compileコスト（$0.45〜0.65/daily log）は知識ベースが育つほど増える。既存記事をプロンプトに載せる方式ゆえの性質
・Claude Code前提：フックとClaude Agent SDKに依存するため、他のエージェントへそのまま移植はできない。会話キャプチャはClaude CodeのJSONLトランスクリプト形式に依存する
・LLMが知識を所有する：knowledge/はLLMが書き換える領域で、人間の直接編集は想定されていない。意図しない要約や統合が起きうるため、lintでの一貫性チェックが前提運用になる
・18時という固定トリガー：自動コンパイルはCOMPILE_AFTER_HOUR = 18に紐づく。深夜・早朝中心の作業者はこの値の調整や手動実行を検討する必要がある

これらは欠陥というより「個人スケールに振り切った設計の裏返し」です。 ベクトルDBを立てない代わりにスケール上限があり、サブスク枠で回す代わりにClaude Codeに縛られる——トレードオフを理解した上で使う道具です。

まとめ

Claude Memory Compilerは、「会話＝ソースコード、LLM＝コンパイラ、知識ベース＝実行ファイル」というアナロジーを、Claude Codeのフックとagent SDKで実装したOSSです。 SessionEnd/PreCompactで会話を捕まえ、flush.pyで重要点を抽出し、18時以降にcompile.pyが概念記事へ組み上げ、SessionStartで次の会話に注入する——この一周のループが、手作業なしで個人の知識を雪だるま式に育てます。

RAGもベクトルDBも使わず、markdownのindex.md一枚で検索を成立させる割り切りが最大の特徴です。 個人規模なら、その方がLLMの理解力を活かせる。 Obsidianでそのまま開ける可搬性と、サブスク枠で完結するコスト設計も含め、「自分専用のClaudeに記憶を持たせたい」開発者にとって、試す価値のある設計です。

参照ソース

・coleam00/claude-memory-compiler — GitHub README
・AGENTS.md — Personal Knowledge Base Schema（公式技術リファレンス）
・Andrej Karpathy’s LLM Knowledge Base（オリジナルアーキテクチャ）
・Claude Agent SDK — GitHub