mnemos

Mnemos — タスクに応じたメモリーのライフサイクル

機能

Mnemos は、損失を伴うコンテキスト圧縮によって、最も必要な構造化知識が失われるのを防ぎます。作業メモリーを型付きグラフ（MnemoGraph）として扱い、知識の種類ごとに異なる破棄ポリシーを適用します。

• GoalNodes と ConstraintNodes は絶対に破棄されず、あらゆる圧縮後も保持されます
• ResultNodes は破棄前に圧縮されます（要約を保持）
• ContextNodes は活性化の重みが低下すると破棄できます
• CheckpointNodes はセッション再開用にディスクへ保存されます

疲労モデル

Mnemos は「エージェントの疲労」の4つの側面を監視します。すべてフックのデータから受動的に観測するため、手動入力は不要です。

側面	重み	シグナルのソース	測定内容
トークン使用率	0.40	Statusline JSON	コンテキストウィンドウの使用量
スコープの散乱	0.25	PreToolUse のファイルパス	エージェントが行き来しているディレクトリの数
再読み込み率	0.20	PreToolUse の Read 呼び出し	すでに読み込んだファイルをエージェントが再度読む頻度（コンテキストの喪失）
エラー密度	0.15	PostToolUse の結果	失敗しているツール呼び出しの割合（エージェントが苦戦している状態）

疲労状態とアクション：

状態	スコア	アクション
FLOW	0.0–0.4	通常動作
COMPRESS	0.4–0.6	マイクロ統合を実行（ResultNodes を3つ圧縮し、低温の ContextNode を1つ破棄）
PRE-SLEEP	0.6–0.75	チェックポイントを作成し、統合を実行
REM	0.75–0.9	緊急チェックポイントを作成し、作業の終了を検討
EMERGENCY	0.9+	チェックポイントを作成し、ただちに引き継ぎ

使用方法

自動（フックがすべて処理）：

1. Statusline は API 呼び出しのたびに fatigue.json を書き込みます
2. PreToolUse フックは編集の前に毎回疲労状態を読み取り、0.60 以上になると自動でチェックポイントを作成します
3. PreCompact フックは緊急チェックポイントと圧縮マーカーを書き込み、要約担当に保持すべき内容を伝えます
4. SessionStart "compact" は圧縮の直後に実行され、チェックポイント全体を再注入します（主要な復元処理）
5. SessionStart "startup|resume" は新規または再開したセッションで最後のチェックポイントを読み込みます
6. PreToolUse fallback（マッチャーなし）は SessionStart が実行されなかった場合に圧縮マーカーを検出します
7. Stop フックは次のセッションに向けて最終チェックポイントを書き込みます

圧縮後の復元（三層防御）：

Claude Code がコンテキストを圧縮すると（約83%の使用時）、Mnemos は次の三層で処理します。

• Layer 1 (PreCompact)：インラインのチェックポイント内容を含む、保持のための強力な指示を要約担当に出力します。.mnemos/just-compacted マーカーを書き込みます。
• Layer 2 (SessionStart "compact")：主要な再注入処理です。 Claude が圧縮後に再開すると、エージェントがアクションを起こす前にただちに実行されます。マーカーを消費し、新しいコンテキストにチェックポイント全体を注入します。RFC（Wake State Reconstruction）で推奨されている方法です。
• Layer 3 (PreToolUse fallback)：SessionStart が実行されない場合（古いバージョンや特殊なケース）、最初のツール呼び出しで mnemos-post-compact-inject.sh が起動し、マーカーを検出して注入します。これはセーフティネットにすぎません。

その結果、圧縮後には、目標、制約、作業内容、進捗を示す「CONTEXT RESTORED AFTER COMPACTION」ブロックが表示されます。そこから作業を再開できます。

手動 CLI：

mnemos init                    # Initialize .mnemos/
mnemos status                  # Show node counts + fatigue
mnemos fatigue                 # Detailed fatigue breakdown
mnemos checkpoint --force      # Write checkpoint now
mnemos resume                  # Output checkpoint for context
mnemos consolidate             # Run micro-consolidation
mnemos nodes --type goal       # List active GoalNodes
mnemos add goal "Build auth"   # Add a GoalNode
mnemos bridge-icpg             # Import iCPG ReasonNodes
mnemos ingest-claude --all     # Ingest Claude Code transcripts (see below)
mnemos haze --recent 10        # Show per-session haziness scores

Claude のトランスクリプト取り込みと疲労度

Mnemos は、Claude Code のセッションのトランスクリプト（~/.claude/projects/ 配下のセッションごとの JSONL）を取り込み、各セッションの疲労度（エージェントがどの程度苦労したかを示す指標）を評価できます。Stop フックがセッション終了時にこれを自動で実行します。また、手動で実行することもできます。

保存される内容：構造化フィールド（ロール、ツール名、ファイルパス、エラーフラグ、タイムスタンプ）と、各ターンの200文字に切り詰められた、機密情報を除去済みのプレビューのみです。完全な内容は保存されず、シークレット（API キー、トークン、PEM ブロック、JWT、認証情報）は、ディスクに書き込まれる前に除去されます。

疲労度は、以下の5つの指標を重み付けして算出したスコアで、各指標は [0,1] の範囲です。

指標	重み	評価内容
correction_density	0.30	対象となるユーザーターンあたりのユーザーによる修正回数
redo_ratio	0.25	エラー後に再度編集された箇所の割合
first_try_error_rate	0.20	編集後3ターン以内にエラーが発生した割合
orphan_tool_use_rate	0.15	対応する結果がないツール呼び出しの割合
backtrack_norm	0.10	git revert／reset --hard／restore の呼び出し

合成スコアは次の段階に分類されます。clear < 0.25 ≤ cloudy < 0.50 ≤ hazy < 0.75 ≤ lost。

mnemos ingest-claude --all              # ingest every transcript + score
mnemos ingest-claude --session <id>     # one session by id
mnemos ingest-claude --transcript <f>   # a specific JSONL file
mnemos haze --recent 10                 # table of recent sessions
mnemos haze --session <id>              # per-dimension breakdown

取り込みは冪等であり、last_line_offset を使って再開できます。プロジェクトごとに無効にするには、touch .mnemos/claude-log.disabled を実行します。

エージェントへの指示

タスクに取り組む際は、次の手順に従ってください。

1. 最初に GoalNode を作成します： mnemos add goal "what you're trying to achieve" --task-id session-1
2. 不変条件には ConstraintNode を追加します： mnemos add constraint "API backward compatibility" --scope src/api/
3. 長時間かかる処理の前に疲労度を確認します： mnemos fatigue
4. サブゴールの区切りでチェックポイントを作成します： mnemos checkpoint
5. セッション再開時： SessionStart フックがチェックポイントを自動で読み込みます

iCPG との統合

Mnemos は iCPG（Intent-Augmented Code Property Graph）と連携します。

• mnemos bridge-icpg はアクティブな ReasonNode を GoalNode としてインポートします
• 事後条件／不変条件は ConstraintNode になります
• チェックポイントには iCPG の状態（アクティブな意図、未解決のずれ）が含まれます

ストレージ

すべてのデータは .mnemos/（Git の追跡対象外）に保存されます。

• mnemo.db — SQLite の MnemoGraph
• fatigue.json — トークンのライブメトリクス（ステータスラインにより API 呼び出しごとに更新）
• signals.jsonl — 行動シグナルのログ（PreToolUse および PostToolUse フックにより追記）
• checkpoint-latest.json — 最新のチェックポイント
• checkpoints/ — アーカイブ済みのチェックポイント