engram-memory

Engram 永続メモリ — プロトコル

Engram は、セッションやコンテキストの圧縮を越えて保持される永続メモリシステムです。 エージェントは、有効化を待たずにこのプロトコルに従わなければなりません。

利用可能なツール

Codex に実際に公開されている Engram ツールを、登録名で使用してください。 以下の名前は論理名です。利用可否と検出方法は、Codex のホスト固有のツールインターフェースに従い、共通のブートストラップや遅延ツールの区分には従いません。

• mem_save、mem_search、mem_context、mem_session_summary

• mem_get_observation、mem_save_prompt、mem_current_project、mem_judge、mem_compare

• mem_update、mem_review、mem_pin、mem_unpin、mem_suggest_topic_key

• mem_session_start、mem_session_end、mem_doctor、mem_capture_passive

積極的な保存のトリガー（必須 — ユーザーに頼まれるまで待たない）

次のいずれかが発生したら、すぐに、頼まれる前に mem_save を呼び出してください。

決定や規約の後

• アーキテクチャまたは設計上の決定がなされた
• チームの規約が文書化または確立された
• ワークフローの変更が合意された
• トレードオフを踏まえてツールまたはライブラリが選定された

作業の完了後

• バグ修正が完了した（根本原因を含める）
• 実装に、ひと目では分からない手法を採用した機能が完了した
• 重要な内容を含む Notion／Jira／GitHub の成果物を作成または更新した
• 設定変更または環境構築を行った

発見の後

• コードベースについて、ひと目では分からないことを発見した
• 注意点、エッジケース、または予想外の動作を見つけた
• パターン（命名、構成、規約）が確立された
• ユーザーの好みや制約が分かった

ユーザーによる確認または却下の後

• ユーザーが提案を承認した（「それで進めましょう」「そうしましょう」「いいですね」「賛成です」「完璧です」、またはユーザーの言語での同等の表現）
• ユーザーが選択肢や手法を却下した（「いいえ、X のほうがよいです」「それではなく」、またはユーザーの言語での同等の表現）
• ユーザーが好みを示した（「Y より X が好みです」「いつもこの方法で進めてください」、またはユーザーの言語での同等の表現）
• 選択肢やトレードオフを提示した後、ユーザーが決定した
• エージェントが提案した場合でも、話し合いが明確な方針の決定に至った

セルフチェック — すべてのタスクの後に自問してください：

「自分またはユーザーは、今、決定を下したり、提案を承認したり、好みを示したり、バグを修正したり、ひと目では分からないことを学んだり、規約を確立したりしたか？ 該当する場合は、今すぐ mem_save を呼び出す。」

mem_save の形式：

• title：動詞＋内容 — 短く、検索しやすいもの（例：「UserList の N+1 クエリを修正」「Redux より Zustand を選択」）
• type：bugfix | decision | architecture | discovery | pattern | config | preference
• scope：project（デフォルト）| personal | global
• topic_key（任意ですが、継続的に扱うトピックでは推奨）：architecture/auth-model のような安定したキー
• content： What：何をしたかを一文で Why：その動機（ユーザーの依頼、バグ、パフォーマンスなど） Where：影響を受けたファイルまたはパス Learned：注意点、エッジケース、意外だったこと（なければ省略）

トピックの更新ルール（必須）

• 異なるトピックで互いに上書きしてはいけません（例：アーキテクチャ上の決定とバグ修正）
• 同じトピックが発展した場合は、新しい観察を作成するのではなくメモリを更新（upsert）するため、同じ topic_key を指定して mem_save を呼び出してください
• キーが分からない場合は、まず mem_suggest_topic_key を呼び出し、その後は一貫して同じキーを再利用してください
• 修正対象の正確な ID がすでに分かっている場合は、mem_update を使用してください

メモリを検索するタイミング

ユーザーが何かを思い出すよう求めた場合――「覚えている？」「思い出して」「何をしたっけ」「どう解決したっけ」など、ユーザーの言語での同等の表現や、過去の作業への言及があった場合：

1. まず mem_context を呼び出します。最近のセッション履歴を確認します（高速で低コストです）。
2. 見つからない場合は、関連するキーワードを指定して mem_search を呼び出します（FTS5 全文検索）。
3. 一致する内容が見つかった場合は、完全な省略なしの内容を取得するために mem_get_observation を使用します。

次の場合も、積極的にメモリを検索します。

• 以前に取り組んだ可能性のある作業を開始するとき
• ユーザーが、こちらにコンテキストがないトピックに言及したとき――過去のセッションで扱われていないか確認します
• ユーザーの最初のメッセージでプロジェクト、機能、問題に言及されたとき――返信する前に、そのメッセージのキーワードを使って mem_search を呼び出し、過去の作業を確認します

回答の送信保証

メモリ操作は内部的な記録管理であり、ユーザー向けの回答には含めません。完了した作業への返信を作成する前に、必要なメモリ作業を完了してください。ターンの最後のメッセージとして回答全体を送信し、その後にツールを呼び出さないでください。メモリ操作が失敗した場合や追加対応が必要な場合も、回答は送信してください。

セッション終了プロトコル（必須）

セッションを終了する前、または「完了しました」「以上です」と伝える前に、必ず次の構成で mem_session_summary を呼び出してください。

目標

[このセッションで取り組んでいたこと]

指示

[判明したユーザーの好みや制約――なければ省略]

発見事項

• [技術的な知見、注意点、見落としやすい学び]

達成事項

• [重要な詳細を含む完了項目]

次のステップ

• [次のセッションに引き継ぐ未完了事項]

関連ファイル

• path/to/file — [そのファイルの役割、または変更内容]

これは任意ではありません。省略すると、次のセッションは何も分からない状態から始まります。 要約の保存によってセッションが終了するわけではありません。エージェントによる要約とは独立して、Codex の SessionEnd フックがセッションの終了処理を担います。

パッシブキャプチャ — アダプター固有の安全策

タスクまたはサブタスクを完了したら、番号付き項目を含む「## 重要な学び：」セクションを追加してください。 自動キャプチャはアダプター固有です。Codex の SubagentStop フックは、条件に合う委任先／サブエージェントの出力を転送し、サーバー側で抽出します。メインエージェントの通常の返信は、このフックでは自動的にキャプチャされません。また、このセクションを記載するだけでは、保存は保証されません。重要かつ検証済みの知識を保存する場合は、主な方法として mem_save を使用してください。

例：

重要な学び：

1. bcrypt の cost=12 は、サーバーのパフォーマンスに適したバランスです
2. 競合状態を防ぐには、JWT リフレッシュトークンをアトミックにローテーションする必要があります

学びのセクションを含む任意のテキストを mem_capture_passive(content) に直接渡して呼び出すこともできます。 この明示的な抽出方法は安全策であり、mem_save の代わりにはなりません。

コンパクション後

コンパクションまたはコンテキストのリセットに関するメッセージが表示された場合、あるいはコンテキストに「FIRST ACTION REQUIRED」と表示された場合：

1. 直ちに、コンパクションされた要約の内容を使って mem_session_summary を呼び出します。コンパクション前に行った作業を保存します
2. 次に mem_context を呼び出して、以前のセッションから追加のコンテキストを復元します
3. その後で初めて、作業を続けます

手順 1 を省略しないでください。省略すると、コンパクション前に行った作業がすべてメモリから失われます。

Codex セッションの紐付け

Codex は、mcp__engram__mem_* および mcp__plugin_engram_engram__mem_* を対象とするネイティブの PreToolUse コマンド engram hook codex-pre-tool-use を登録します。対応する Engram の書き込み／セッションツールでは、引数を紐付ける前に、権威ある Codex ホストセッションをサーバーで確認済みの Engram ID に解決します。書き込みには session_id、セッションの開始／終了には id を使用します。mem_session_end では session_id ではなく id を使用します。この ID を創作したり、上書きしたりしないでください。読み取り専用ツールに変更はありません。不正な入力や、確認できないホストセッションの解決があった場合、変更を伴う呼び出しは拒否されます。

ライフサイクルフックは、登録または更新後に確認済みの ID も提供します。直接接続するクライアントやフックで捕捉されないクライアントでは、この ID を、書き込みの帰属付けに session_id（mem_save、mem_save_prompt、mem_session_summary、mem_capture_passive）、mem_session_end に id として、そのまま再利用してください。確認できない場合、再開時のサフィックスを再構築したり、ID を推測したりしないでください。

フォールバック：ツールが予期せず利用できない場合は、engram setup codex を実行して Codex を再起動してください。セットアップによって、Codex の権威ある [mcp_servers.engram] 登録が修復されます。Codex が公開する実際のツール名を使用してください。