memory-management

メモリ管理

Claude が同じ間違いを繰り返さず、会話をまたいで学習したパターンを常に適用できるようにする永続メモリシステムです。

4 つのツール

• mcp__claude-recall__load_rules - 作業を始める前に、すべての有効なルールを読み込みます。クエリは不要です。
• mcp__claude-recall__store_memory - ルールや学習内容を保存します。この会話ですぐに有効になります。
• mcp__claude-recall__search_memory - キーワードでメモリを検索します。判断を下す前に、該当するメモリを探すために使用します。
• mcp__claude-recall__delete_memory - ID を指定して特定のメモリを削除します。まず search_memory を使って ID を確認してください。

使用するタイミング

読み込み（リコール）

• すべてのセッションで最初に実行 — Read／Glob／Grep を含む、あらゆるツール呼び出しより前に load_rules を呼び出します。ルールは編集だけでなく、調査にも反映させる必要があります。
• コンテキストの圧縮後 — コンテキストが圧縮された場合や会話が長くなった場合は、もう一度 load_rules を呼び出します。以前のルールが失われている可能性があります。
• タスク領域の切り替え時 — ある領域から別の領域に移るとき（例：テスト → データベース → CI）は、新しい領域をクエリにして search_memory を呼び出します。
• ファイルを変更する前 — ファイル固有の慣例を確認するため、ファイルパスまたはモジュール名を指定して search_memory を呼び出します。

保存（記録）

• ユーザーから作業の修正を受けたとき - metadata.type: "correction" を指定して store_memory を呼び出します
• ユーザーが好みを伝えたとき - metadata.type: "preference" を指定して store_memory を呼び出します
• 課題を解決した後 - metadata.type: "failure" を指定して store_memory を呼び出します
• DevOps／ワークフローのルール - metadata.type: "devops" を指定して store_memory を呼び出します

主要な指示

1. 行動する前に必ずルールを読み込む — セッションで最初に行うこととして、ファイルを読む前に load_rules を呼び出します。ルールは編集だけでなく、調査の進め方にも反映させます。
2. 読み込んだルールを適用する — 読み込み後、作業を進める前に、現在のタスクに適用されるルールを明示します。ルールが計画と矛盾する場合は、ルールに従います。該当するルールがない場合は、その旨を伝えます。読み込んでも適用しないのは、読み込まないのと同じです。
3. 適用したルールを本文中に引用する — ルールが作業に影響した場合は、(applied from memory: <rule>) の形式で示します。無関係な説明の末尾ではなく、影響を受けた操作のそばに引用を記載します。
4. ユーザーが「recall」／「remember」／「store this」と言ったら Claude Recall を使う — これらのキーワードのいずれかをユーザーが使った場合は、必ず mcp__claude-recall__store_memory を使います。このような依頼に対して、ネイティブのメモリディレクトリ（~/.claude/projects/*/memory/）には書き込まないでください。Claude Recall はユーザーが希望するメモリシステムです。
5. 保存する前に確認する — store_memory を呼び出す前に、保存する内容をユーザーに伝え、確認を求めます。
6. 修正内容はすぐに記録する — ユーザーによる修正は最優先です（それでも事前に確認します）。
7. 秘密情報は決して保存しない — API キー、パスワード、トークン、個人を特定できる情報は保存しません。

クイックリファレンス

ルールの読み込み（すべてのタスクの前）

mcp__claude-recall__load_rules({})

すべての有効な設定、修正、失敗、DevOps ルールを 1 回の呼び出しで返します。決定的かつ完全です。

メモリの保存（重要な出来事があったとき）

mcp__claude-recall__store_memory({
  "content": "Description of what to remember",
  "metadata": { "type": "preference|correction|devops|failure" }
})

保存されたルールを activeRule フィールドと、すぐに適用するための _directive とともに返します。再度 load_rules を呼び出す必要はありません。

同一セッション内のルール

store_memory を呼び出すと、応答には次の内容が含まれます。

• activeRule：ルールとして整形された保存内容
• _directive：そのルールをすぐに適用するための指示

つまり、会話の途中で保存されたルールは、再読み込みしなくてもすぐに有効になります。

保存される内容

自動記録（保存操作は不要）

ユーザーが次のように言うと、システムは自動的に記録します。

• 「X が好みです」／「常に X を使ってください」／「X はしないでください」-> 設定
• 「Y には X を使います」／「テストは X に置きます」-> プロジェクトの慣例
• 「これは [type] のプロジェクトです」-> プロジェクトのコンテキスト

手動で保存する必要がある内容

次の内容は明示的に保存します。

修正（最優先）：

User: "No, put tests in __tests__/ not tests/"
-> Store: "CORRECTION: Test files go in __tests__/ directory, not tests/"
   metadata: { "type": "correction" }

複雑なワークフロー：

-> Store: "Deploy process: 1) npm test 2) docker build 3) push to ECR 4) kubectl apply"
   metadata: { "type": "devops" }

学習サイクル（失敗 -> 修正 -> 成功）：

-> Store: "REST API failed due to CORS. Solution: Use GraphQL endpoint instead."
   metadata: { "type": "failure" }

メモリの優先順位

1. 修正 - ユーザーが明示的に誤りを修正した内容（最優先）
2. DevOps - Git、テスト、デプロイ、アーキテクチャのパターン
3. 設定 - コードスタイル、ツールの選択、規約
4. 失敗 - 学習サイクルと過去のミス

保存してはいけないもの

以下は保存しないでください。

• API キー、トークン、パスワード、シークレット
• 個人のメールアドレス、電話番号、住所
• 認証情報を含むデータベース接続文字列
• 機密性の高い設定値全般

安全に保存できるもの：

• 「認証には JWT を使用します」（認証情報ではなくパターン）
• 「API のベース URL は https://api.example.com です」（機密情報ではありません）
• 「本番環境では PostgreSQL、テストでは SQLite を使用します」（ツールの選択）

スキルの結晶化

メモリが蓄積されると、Claude Recall は .claude/skills/auto-*/ にスキルファイルを自動生成します。 これらは今後のセッションでネイティブに読み込まれるため、ツール呼び出しは不要です。

仕組み： 各 store_memory の後、システムはスキルを形成するのに十分なメモリがトピックにあるかを確認します（ほとんどの種類では 3 件以上、設定では 5 件以上）。条件を満たすと、Claude Code が自動的に読み込む SKILL.md ファイルを書き込みます。

CLI コマンド：

• claude-recall skills list — 生成されたスキルを確認します
• claude-recall skills generate --force — 強制的に再生成します
• claude-recall skills clean --force — 自動生成されたすべてのスキルを削除します

自動キャプチャフック

Claude Recall は、6 つの Claude Code イベントにフックを登録し、自動キャプチャ、ジャストインタイムのルール注入、結果追跡を行います。MCP ツールの呼び出しは不要です。

フック	イベント	内容
correction-detector	UserPromptSubmit	自然言語から、ユーザーによる修正、好み、プロジェクトに関する知識をキャプチャします
memory-stop	Stop	直近のトランスクリプトエントリ 6 件から、修正、好み、失敗、DevOps のパターンをキャプチャします
precompact-preserve	PreCompact	コンテキスト圧縮の前に、最大 50 件のトランスクリプトエントリを対象に、より広範な確認を行います
session-end-checkpoint	SessionEnd	セッションが任意に終了した場合（clear、prompt_input_exit、logout）、{completed, remaining, blockers} タスクチェックポイントを自動保存します。Claude Code の 1.5s SessionEnd タイムアウト内に収まるよう、切り離されたワーカーを起動します。Pi では、session_shutdown イベントハンドラーを通じて同等の機能を利用できます。
rule-injector	PreToolUse	ジャストインタイムのルール注入。 各ツール呼び出しの前に、有効なルールの中から tool_name + tool_input に一致するものを検索し、上位 3 件を（未加工の失敗は除外して）アクションの近くにある <system-reminder> ブロックとして注入します。これにより、ルールの読み込みにおけるギャップを解消します。注意がすでに別の場所に移った後、50,000 トークンも前にルールを表示するのではなく、判断の瞬間に表示します。各注入は、結果との相関分析のため rule_injection_events に記録されます。Pi では、before_agent_start ハンドラー内のターンごとの注入を通じて同等の機能を利用できます。
rule-injection-resolver	PostToolUse / PostToolUseFailure	記録された rule_injection_events にツールの結果（成功／失敗）を反映します。injector と組み合わせることで、従来の壊れた (applied from memory: ...) 引用正規表現に代わる、「このルールは実際に役立つのか」を判断する新しいシグナルになります。

主な動作：

• Claude Haiku による LLM 優先の分類 — 正規表現では見逃すような「ここではタブを使います」や「テストは __tests__/ に置きます」といった自然な発言を検出します
• 自動で設定不要：Claude Code のセッション環境から ANTHROPIC_API_KEY を取得します
• API キーがない場合や API 呼び出しが失敗した場合は、正規表現によるフォールバックに切り替わります
• バッチ分類：Stop フックと PreCompact フックは、すべてのテキストを 1 回の API 呼び出しで送信します
• Jaccard 類似度（しきい値 55%）による準重複検出で、冗長な保存を防ぎます
• DB の過剰な増加を防ぐイベントごとの上限：3 件（Stop）、5 件（PreCompact）
• 自動チェックポイントの品質ゲート：LLM がタスクはすでに完了していると検出した場合、保存を拒否します。手動チェックポイントは保持されます
• 常に 0 で終了します — フックが Claude をブロックすることはありません

セットアップ： claude-recall setup --install を実行して、.claude/settings.json にフックを登録します。新規または変更されたフックがリリースノートに記載されているアップグレード（hooksVersion の更新）の後は、アクティブなプロジェクトごとに再実行してください。冪等性があるため、フックがすでに最新の場合は何もせず、変更も行いません。

ワークフローの例

新しいタスクの開始

1. User: "Add user authentication"

2. Load rules first:
   mcp__claude-recall__load_rules({})

3. Response includes:
   ## Preferences
   - auth_method: JWT with httpOnly cookies
   ## Corrections
   - Never use localStorage for auth tokens

4. Implement using JWT + httpOnly cookies (not sessions, not localStorage)

5. User approves -> Done (no need to store, just applied existing knowledge)

ユーザーが作業を修正する

1. You: Created auth with localStorage tokens

2. User: "No, we always use httpOnly cookies for security"

3. Fix the code

4. Ask: "I'd like to remember: always use httpOnly cookies for auth tokens, never localStorage. Store this?"

5. User: "Yes"

6. Store the correction:
   mcp__claude-recall__store_memory({
     "content": "CORRECTION: Always use httpOnly cookies for auth tokens, never localStorage",
     "metadata": { "type": "correction" }
   })

7. Response includes activeRule - apply it immediately

課題の克服

1. Tried: Redis sessions for auth
   Failed: "Session sync issues in k8s cluster"

2. User suggested: "Try stateless JWT"

3. Implemented JWT -> Works!

4. Ask: "I'd like to remember: Redis sessions fail in k8s due to sync issues; use stateless JWT instead. Store this?"

5. User: "Yes"

6. Store the learning:
   mcp__claude-recall__store_memory({
     "content": "Auth in k8s: Redis sessions failed (sync issues). JWT stateless tokens work correctly.",
     "metadata": { "type": "failure", "learning_cycle": true }
   })

トラブルシューティング

ルールの読み込みで何も返されない：

• まだ履歴のない新しいプロジェクトである可能性があります
• 学んだルールを store_memory で保存してください

自動キャプチャで見逃したものがある：

• 適切なタイプを指定して手動で保存してください
• 今後の load_rules 呼び出しで見つかるようになります

---

学習ループ：ルールを読み込む -> 適用する -> 実行する -> 結果をキャプチャする -> 次回はさらに改善する