セッションを跨ぐ「記憶」

Handoff はセッション間の引き継ぎ（タスク、決定事項、ブロッカー）を管理するツールですが、もっと長い時間軸で生きる知識があります。「この関数は必ず atomic_write 経由で呼ぶ」「このディレクトリのテストは実バイナリで走らせる」といった、プロジェクト固有の教訓やルールです。

v0.13 で追加した プロジェクトメモリ は、こうした知識を .handoff/memory/ に永続化し、必要なタイミングでエージェントのコンテキストに自動注入します。

4 つのメモリツール

ツール	役割
`handoff_memory_save`	メモリを保存する。完全一致は重複として報告、類似は conflict として返しエージェントにマージを委ねる
`handoff_memory_query`	プロンプトや編集ファイルに関連するメモリを BM25 + スコープパスブーストで検索する
`handoff_memory_delete`	ID（またはプレフィックス一致）でメモリを削除する
`handoff_memory_cleanup`	完全重複の自動マージ、類似クラスタ・古いメモリの推薦、注入記録の GC を行う

辞書なしで日本語も検索できる

メモリの検索と重複判定には lexsim を使っています。形態素辞書を使わず、文字 n-gram のみで日本語と英語の両方をトークナイズするため、追加の辞書データなしでサブミリ秒のインメモリ検索が可能です。

ワンコマンドで自動注入を有効化

メモリの検索は手動で呼ぶこともできますが、Claude Code のフックを設定すると毎回のプロンプト入力時に関連メモリが自動的にコンテキストへ注入されます。

handoff-mcp setup

このコマンドひとつで 3 つのフックがインストールされます。

UserPromptSubmit — プロンプト入力のたびに関連メモリを自動注入
PreToolUse — ファイル編集時にそのファイルにスコープされたメモリを注入
SessionStart — セッション開始時にメモリストアの重複整理を実行

~/.claude/settings.json を手で編集する必要はありません。

handoff-mcp setup --check      # 設定状態を確認
handoff-mcp setup --uninstall  # フックを削除して自動注入を停止

フックは毎回のプロンプトで発火するため、オーバーヘッドが気になる場合は --uninstall で停止できます。手動でのメモリ呼び出しは引き続き使えます。

重複と類似をエージェントに任せる

同じ教訓を二度保存しようとすると、handoff_memory_save は既存メモリとの類似度を検出し、conflict として返します。このとき、サーバーは勝手にマージしません。新旧両方のテキストをエージェントに提示し、merge_into でマージするか force: true で別に保存するかの判断を委ねます。

handoff_memory_cleanup はセッション開始時に自動で走り、完全一致のメモリは安全にマージしつつ、類似クラスタや長期間参照されていないメモリをレコメンドとして返します。

メモリ設定

すべて handoff_update_config で変更可能で、既存プロジェクトへの影響はありません。

設定	デフォルト	説明
`memory_enabled`	`true`	マスタースイッチ。false にすると全メモリツールが無効化
`memory_dup_threshold`	`0.72`	この類似度以上で近似重複と判定
`memory_query_min_score`	`0.5`	この関連度以下のメモリは返さない
`memory_query_limit`	`5`	1 回のクエリで返すメモリの最大件数
`memory_stale_days`	`60`	参照されない日数がこれを超えると古いメモリとして推薦
`memory_injected_gc_days`	`14`	注入記録の GC 対象となる日数

インストール・更新

cargo install handoff-mcp          # Rust ユーザー
npm install -g handoff-mcp-server  # npm ユーザー

Handoff の実績ページを見る