agent-memory

エージェントメモリ — 昇格は主張するものではなく、実績で得るものです

ポータビリティ： 標準ライブラリのみ。データベース、埋め込み、ネットワーク、LLM 呼び出しはありません。

問題

プロジェクトの CLAUDE.md は、階層が一つしかなく、削除の仕組みもないメモリシステムです。永続させるべき事実も、その場限りの好みもすべて同じ常時読み込みファイルに入り、重要な記述は付随的な記述に埋もれていきます。セッション中に学んだ事実は、誰かが書き留めない限り、終了時に消えてしまいます。

解決策は、ストレージを増やすことではなく、段階的な昇格の仕組みです。 主張は繰り返し現れることで、常時読み込まれるコンテキストに昇格していきます。最後の段階は人間が確認します。

4 つの階層

階層の違いは、保存形式ではなく注入ポリシーです。

階層	保持するもの	注入されるタイミング	コミット
L0	セッションの生トランスクリプト	なし	いいえ（すでにディスク上にあります）
L1	候補となる原子情報	関連性がある場合、プロンプト時	いいえ（gitignore 対象）
L2	このプロジェクトのコンテキスト	毎回のセッション開始時	はい、採用後
L3	プロジェクトをまたいで安定したペルソナ	常時	はい、採用後

ゲート

重要そうに聞こえたからといって、昇格することはありません。繰り返し現れた場合に昇格します。

• L0 → L1 — 明示的なマーカーが検出されます（指示、訂正、明示された好み、名前付きの教訓、再現可能な失敗）。ルールベースで高精度を重視し、再現率は意図的に低くしています。
• L1 → L2 — 2 つ以上の異なる暦日にまたがる、3 つ以上の異なるセッション。明言された主張は 2 セッションで昇格しますが、異なる日であるというルールは引き続き適用されます。検証済みの主張は 1 回の観測で昇格し、日数の条件が免除される唯一の経路です。
• L2 → L3 — 2 つ以上の異なるプロジェクトで保持され、30 日以上経過し、異議がないこと。

2 つのゲートは推測せず、昇格を拒否します。 テキストが編集されている主張は、証拠だけでは昇格しません。フラグが検出されたこと自体が、情報源に機密性があった証拠です。また、字句フィルターが秘密情報を 1 つ見つけたからといって、すべてを検出できた証明にはなりません。未解決の矛盾がある主張は、人間が解決するまで L1 に留められます。既存の主張が黙って上書きされることはありません。

使い方

# what is remembered, and what is blocking the next promotion
python3 scripts/memory_inspect.py --tier L1

# where did this line come from — sessions, days, transcript, quoted source
python3 scripts/memory_inspect.py --why "PR base branch is dev"

# every claim with an open contradiction, both directions of the join
python3 scripts/memory_inspect.py --contested

# dry-run the promotion pass; writes nothing
python3 scripts/memory_promote.py

3 つのフックがループを無人で実行します。SessionStart は L2 + L3 を注入し、UserPromptSubmit は関連する L1 の原子情報を呼び出し、SessionEnd は情報を取得してステージングします。各フックは AGENT_MEMORY_SESSIONSTART=0、AGENT_MEMORY_USERPROMPTSUBMIT=0、AGENT_MEMORY_SESSIONEND=0 で個別に無効化できます。すべてのフックはフェイルオープンで動作します。メモリシステムが壊れても、失うのはメモリだけで、セッションが中断されることはありません。

厳守事項

1. 書き込む前に秘匿化します。 すべての原子情報は、ディスクに書き込まれる前にフィルターを通ります。編集された情報は昇格対象から隔離されます。
2. 提案のみを行い、適用はしません。 昇格内容は .memory/staged/ に配置されます。明示的な /cs-memory adopt のみが CLAUDE.md に変更を加え、その前に必ずバックアップを作成します。
3. 捏造せず、出典を示します。 すべての原子情報には、それを生み出したトランスクリプトの行への参照が付属します。--why の解決結果が ambiguous の場合は、推測せずに何も表示しません。誤った出典を示すことは、出典を示さないことよりも悪いためです。
4. 異議のある主張を事実として提示しません。 注入はされます。矛盾を隠すほうが悪いためです。ただし、必ずタグを付けます。
5. コミットされる階層にパスを含めません。 昇格時に、OS のユーザー名を含むバックポインタープレフィックスを削除します。

問いかけ

ストアを信頼する前に、これらの問いを 1 つずつ考えてください。

1. 行動に移る前に、最後に実際に読んだ CLAUDE.md の行はどれですか？
2. エージェントが正しいことを忘れるのと、誤ったことを覚えるのとでは、どちらを望みますか？
3. 記憶された 2 つのルールが食い違うとき、誰が、いつ判断しますか？
4. .memory/ 全体を削除する理由になるのは、どのようなことですか？

設計の根拠、未決定事項、フィールドスキーマについては、../../DESIGN.md を参照してください。