基本概念
この章では HMG を使うために知っておくべき概念を説明します：記憶、アトム（スコープを含む）、エッジ、リコール、訂正とガバナンス、引き継ぎとブリーフ。
記憶
HMG の記憶は完全なチャットログではなく、「後で使う情報」です：理由つきの決定、安定した好み、プロジェクト規約、根本原因、検証結果、既知のリスク、次のステップ。
判断基準は 1 つだけ：この情報は将来再利用されるか？将来の決定に影響するか？ はい → 記憶する価値あり。その場の産物（一時的な出力、ログ、一回限りの指示）→ 記憶しない。
詳しい「記憶すべき / すべきでない」の対照表と書き方は ベストプラクティス を参照。
アトム
アトム（atom）は HMG の最小の記憶単位です。memorize で書き込んだ記憶は 1 件ずつアトムになります。
- 各アトムには一意の ID があります：書き込み時に返され、以降の訂正（
correct）、ガバナンス（govern）、履歴確認（history）はすべてこれで正確に対象を指定します - 内容は独立した一文です：決定、根本原因、検証結論など
- メタデータは自動付与：作成時刻、出所（
source）、スコープ（scope）
# 書き込み後に atom id が返る。控えておくこと
hmg memorize "デプロイ前に必ずデータベースマイグレーションを実行する。さもないとスキーマ不一致で起動に失敗する" --source deploy-rule
# あるアトムの完全な変遷を確認
hmg history <atom-id>
スコープ
スコープ（scope）は、記憶がどのコンテキストに属し、どこでリコールに参加するかを示します。4 層構造です：
tenant（誰か）
└─ workspace（どの組織）
└─ repository（どのリポジトリ）
└─ branch（どのブランチ）
- tenant：OS のユーザー名。マシンレベルの身份で、全プロジェクト共通
- workspace / repository：通常は git remote の owner とリポジトリ名
- branch：実験結論と安定した決定を分離する
スコープはリコールの挙動を決めます。たとえば main で「キャッシュは SQLite」と決め、feature/redis-experiment で実験している場合：
- main のセッションでリコールすると SQLite の決定が見える
- feature ブランチの実験結論は main を汚染しない
スコープ {#scope}の決定方法
スコープを手動で管理する必要はありません。 HMG がカレントディレクトリからリアルタイムに推論します：tenant は OS のユーザー名、workspace / repository / branch は git remote と現在のブランチから取得。git がない場合はディレクトリ名にフォールバックします。
- Agent 統合時：スコープはセッションのディレクトリから機械的に推論・注入され、Agent は渡さず、間違えることもありません
- CLI：既定ではカレントディレクトリから推論。
--scope tenant/workspace/repository/branchで明示指定も可能
一時セッションの共有スコープ
プロジェクトに紐付かないセッション（Codex デスクトップの Chats など）は、固定の共有スコープを使います：
<os-username> / personal / chats / main
異なる一時セッション間で記憶は共通です。ただし一時セッションとプロジェクトセッションは互いに分離されます——一時セッションで保存したユーザーの好みはプロジェクトセッションには自動で現れません。必要な場合はプロジェクトセッション内で再度 memorize してください。
エッジ
エッジ（edge）はアトム間の接続です：訂正は訂正した古い記憶を指し、引き継ぎはそのタスクの決定やリスクに紐付き、根本原因はモジュールやファイルに紐付きます。
エッジを手動で管理する必要はありません。直接的な効果は 1 つ：リコール時に一文だけでなく、関係に沿って関連コンテキストも一緒に返ること——ある bug を調べると、当時の決定、検証、その後のリスクまで一緒に返ってきます。
リコール
リコール（recall）は自然言語で過去の記憶を検索することです。HMG は意味、キーワード、グラフ関係など複数の角度から同時に検索します。
query の書き方：名詞句を使い、重要な固有名詞（人名、プロジェクト名、技術名、ファイル名）を残す。口語的なノイズは除きます：
| ❌ 口語的 | ✅ 名詞句 |
|---|---|
| 前に何のデータベースに決めたっけ | データベース選定の決定 |
| あのログインエラーはどう処理したっけ | ログイン 500 の根本原因 |
通常 1 回のリコールで十分です。何度も言い換えて検索し直す必要はありません。
hmg recall "ログイン API 500 の根本原因"
# 聞き方が分からないときは HMG に query を提案させる
hmg suggest-query "ログインがたまに 500"
Agent 統合時の MCP ツールは memory_recall で、query だけを渡します（スコープは自動処理）。
訂正とガバナンス
情報は古くなります。古い情報が間違ったり置き換わったりしたら、追加ではなく訂正してください——追加すると新旧が併存し、リコールが古い情報を返す可能性があります。
correct：内容を変える
| アクション | 意味 |
|---|---|
replace | 新しい内容で古い記憶を置き換える |
confirm-actual | この記憶が実際の事実だと確認する |
confirm-necessary | この記憶が必要な制約だと確認する |
demote-possible | もう必要でないかもしれない記憶を格下げする |
negate（MCP/SDK） | 記憶を偽とマークして無効化する |
hmg correct <atom-id> --action replace \
--reason "認証方式を session cookie から JWT に変更" \
--new-content "認証は JWT を使い、session cookie は使わない。サービス間でステートレスな検証が必要なため"
注意点は 2 つ：
negateは正確に元に戻せない（「否定の取り消し」はない）。間違えて否定した場合はreplaceで正しい内容を書き戻すreplaceを間違えたら、そのアトムに対してさらにreplaceを続ける——常に有効な記憶が 1 件だけであることを保証する
govern：ライフサイクルを管理する
| アクション | 意味 |
|---|---|
quarantine | 隔離：リコールに出なくなるが内容は保持 |
seal | 封印：監査のみ参照可能 |
tombstone | 墓碑化：論理削除 |
derive-lesson | 内容から秘匿化された教訓を抽出し、原文は無効化 |
すべての訂正とガバナンスは監査履歴を保持します。hmg history <atom-id> で完全な変遷を確認できます。機密情報を誤って書いた場合の完全な手順は 機密情報の削除または隔離 を参照。
引き継ぎとブリーフ
**引き継ぎ（handoff）**はタスク終了時に次のセッションへ向けて書く文書で、5 要素を含みます：何をしたか / なぜ / 検証 / リスク / 次のステップ。次のセッションの起動時ブリーフはこれを優先的に呼び出します。
hmg handoff "ログイン 500 を修正：token の期限検証を UTC に変更。検証：200 並列で 500 なし。リスク：旧クライアントが expiry をキャッシュ。次：refresh token のフローを確認。" --source bugfix-login-500
**ブリーフ（agent-brief）**はタスク開始時のコンテキスト要約です：前回の引き継ぎ、重要な決定、既知の問題、未完了事項。Agent 統合時はセッション起動時に自動注入されます。手動の場合：
hmg agent-brief --query "ログイン API のたまに出る 500 を修正する"
観察レイヤー（任意）
観察（observation）は一時的な記録のレイヤーです：コマンド出力、ログ、テスト結果はまず観察レイヤーに入り、選別されたものだけが長期記憶に昇格（promote）します——あらゆる出力を直接記憶にしてノイズが爆発するのを防ぎます。
Agent 統合では観察レイヤーを使いません——長期記憶は agent が自発的に呼ぶ memorize / handoff のみで書き込まれます。観察レイヤーは CLI や自動化パイプライン向けの機能です。
hmg obs review-queue # 昇格待ちの観察を見る
hmg obs promote # 長期記憶に昇格
hmg obs forget --query "ある一時記録"
次：日常利用ガイド