メインコンテンツまでスキップ

ベストプラクティス

記憶すべきこと​

判断基準——いずれか 1 つを満たせば記憶する価値あり：

  • 将来再利用する：次回もこの情報を使う
  • 決定に影響する：将来の選択を助けられる
  • 繰り返しの説明を減らす：毎回説明し直さなくてよい
  • リスクを下げる：既知の坑/制約を覚えておけば避けられる

典型的に記憶すべきもの：理由つきの決定、根本原因、安定した制約、ユーザーの安定した好み、検証結論、既知のリスク、次のステップの予定。

Agent 統合時の簡易判断：この情報は次のセッションでも役立つか？ はい → 保存。今のタスクだけで使う → 保存しない。

記憶すべきでないこと​

絶対に記憶しない：

  • secret / token / パスワード / 認証情報（secret vault を使う）
  • 完全なログ、完全なコマンド出力
  • 一時的なデバッグの断片（console.log、一時変数）
  • 未確認の推測

記憶しない方がよい：

  • 一回限りの指示（「今回はこうして」）
  • 流水帳（「さっき X をインストールした」）
  • コードから直接推論できる情報（記憶は不要）

質の高い記憶の書き方​

4 要素：簡潔、検証可能、コンテキストつき、理由つき。ノイズを積まない。

書き換え前 / 書き換え後​

❌ 書き換え前（悪い例）：

text
さっきログインモジュールにチェックを追加して、token の期限を比較した。前に問題があったみたいだけど、たぶん直ったはず。ついでに moment ライブラリを使った

問題点：理由がない、検証できない、流水帳のよう、無関係な詳細（moment）まで積んでいる。

✅ 書き換え後（良い例）：

text
ログインのたまに出る 500 の根本原因は、token の期限検証をローカルタイムゾーンで expiry と比較していたこと。修正は UTC での比較に統一し、moment への依存を外してネイティブの Date に変更。200 件の並列ログインで 500 なしを検証済み。

書き方の約束​

  • 独立した平叙文 1 つ：当時の会話から切り離しても理解できる。「決定：」のような接頭辞はつけない（HMG が記憶の種類と確信度を自動推論する）
  • 記憶 1 件は 1 文：毎回 1〜3 件、各 1〜2 文。長文を書かない
  • 会話の言語で保存：日本語の会話は日本語で、英語の会話は英語で保存
  • 出所を明記：ユーザーが口頭で言ったことは user（より権威あり）、agent が自分でまとめたことは agent。後の訂正時に「この記憶は当初誰が言ったか」を追跡できる
  • 先に重複チェックは不要：HMG が内部で正確な重複排除を行う。意味の近い古い記憶がすでに見えているなら、correct で更新し、新規追加しない

質の高い引き継ぎの書き方​

handoff の 5 要素：何をしたか / なぜ / 検証 / リスク / 次のステップ。これは次のセッションへの引き継ぎ文書で、セッション起動時のブリーフが優先的に呼び出します。

引き継ぎテンプレート​

text
何をしたか: <一言で変更>
なぜ:       <動機/根本原因>
検証:       <何を実行/結果>
リスク:     <懸念/境界>
次のステップ: <予定>

良い例と悪い例​

❌ 悪い例：直した、たぶん大丈夫

✅ 良い例：ログイン 500 を修正：token の期限検証を UTC に変更。理由：旧ロジックはローカルタイムゾーンで誤判定。検証：200 並列で 500 なし。リスク：旧クライアントが expiry をキャッシュしている可能性。次：refresh token のフローを確認。

リコールのノイズを減らす方法​

方法説明
具体的な queryログイン 500 の根本原因 は ログイン より良い
名詞句を使うPostgreSQL コネクションプール設定 は「前に何のデータベースに決めたっけ」より良い。重要な固有名詞（人名/プロジェクト名/技術名/ファイル名）を残す
スコープを正しく使うプロジェクト情報を tenant に置かない。Agent 統合時はスコープは自動推論なので心配不要
古い情報はすぐ訂正新旧の併存を放置しない
質の低い記憶を書かない源头でのノイズ削減が最も効果的
--profile compact を使うAgent には簡潔な結果を
ノイズ句をフィードバックhmg noise-feedback "あるノイズ句" で HMG にフィルタを学習させる
bash
# 繰り返し現れるノイズ結果は HMG にフィードバック
hmg noise-feedback "npm install 成功"   # この句を検索時に降権する

危険な操作の注意​

日常利用で心配すべきことはほとんどありません。注意が必要なのは 3 つだけです：

  • 認証情報は記憶に入れない：API キー、パスワード、接続文字列は hmg secret store の金庫へ。誤って記憶に書いた場合は、すぐ hmg govern <atom-id> --action tombstone --destroy-payload で消去。
  • tombstone / seal は不可逆：実行前に atom を間違えていないか確認（hmg history <atom-id> で確認可能）。一時的に隠したいだけなら quarantine（復元可能）。
  • store を Git にコミットしない：store ディレクトリにはインデックスとバイナリが含まれるので .gitignore へ。バックアップはディレクトリのコピーで十分。

次：統合