memory-protocol

Memory Protocol

価値： フィードバック — 蓄積された知識が、セッションをまたいだ複合的なフィードバックループを生み出します。今日学んだことが、明日の作業を加速させます。

目的

Memento MCP ナレッジグラフを使用して、セッションをまたいでプロジェクトの知識を体系的に保存し、呼び出す方法をエージェントに教えます。

長期記憶（トレーニングデータ）と短期記憶（コンテキストウィンドウ）は優れていますが、現在のコンテキスト外にあるプロジェクト固有の知識を保持する中期記憶は不十分です。Memento はセッションやプロジェクトをまたいでナレッジグラフを永続化し、このギャップを埋めます。

解決する課題：セッション間でのコンテキストの喪失、既知の問題のデバッグの繰り返し、確立された規約の再発見、同じ誤りに対するユーザーからの訂正の繰り返し。

実践

Memento MCP が利用可能か確認する

先に進む前に、Memento MCP ツール（mcp__memento__semantic_search、mcp__memento__create_entities など）が利用可能であることを確認します。

Memento MCP ツールが利用可能でない場合は、作業を中止してユーザーに伝えてください：

「memory-protocol スキルには Memento MCP が必要ですが、mcp__memento__* ツールを利用できません。メモリの永続化を有効にするには、Memento MCP サーバー （https://github.com/gannonh/memento-mcp）をインストールして設定してください。これがないと、このスキルは機能しないため、セッションをまたぐメモリを使わずに作業を進めます。」

その後、メモリプロトコルの実践を使わずに作業を続けてください。ファイルベースの代替手段を試してはいけません。

アンチパターン：Memento が利用可能な場合のファイルベースのメモリ

このスキルが有効で、Memento MCP ツールが利用可能な場合は、セッションをまたぐ知識の保存にファイルベースのメモリシステムを使用しないでください。これには、組み込みの memory/ ディレクトリ、MEMORY.md インデックス、自動メモリ機能、その他のファイルベースの永続化メカニズムが含まれます。セッションをまたぐメモリの保存には、Memento MCP ツールのみを使用してください。

ファイルベースのメモリシステムと Memento は、セッションをまたいで知識を永続化するという同じ目的を果たします。両方を使うと、知識が分断されます。ファイルに保存された知識は Memento の検索から見えず、Memento の知識はファイルの読み取りから見えません。どちらか一方を選んでください。このスキルが読み込まれている場合は、Memento を選択します。

注：これは WORKING_STATE.md（セッションをまたぐメモリではなく、クラッシュ復旧のための基盤）やプロジェクトのドキュメントファイル（メモリではなく、成果物）の使用を禁止するものではありません。

作業前の振り返り — 必須

重要な作業を始める前に、関連する過去の知識を必ず振り返ってください。 この手順は必須です。「簡単そうだから」や、以前のセッションで 覚えたと思っているからといって、省略しないでください。セッション間で 記憶は保持されません。

振り返りのタイミング：

• 重要な作業を始めるとき
• アーキテクチャや設計上の決定を行うとき
• プロジェクトの慣例が不明なとき
• ユーザーに質問する前（すでに回答されている場合があります）

エラーをきっかけとする振り返りについては、以下の専用セクションを 参照してください。

振り返りを行うたびに、マルチディメンショナル検索（次のセクション）を 適用してください。

振り返りの方法 — 次の3つの手順をすべて実行してください：

1. 検索： mcp__memento__semantic_search — 現在の作業を説明するクエリを 指定し、上限を10にします。返されるのは要約のみで、全体像ではありません。

2. 開く： mcp__memento__open_nodes — 検索で返された関連エンティティ すべてについて、open_nodes を呼び出し、完全なエンティティを取得します。 すべての観察事項、すべての関係、完全なコンテキストを確認してください。 この手順を省略してはいけません。 セマンティック検索で返されるデータは一部のみです。完全なエンティティには、 検索結果の要約に含まれていない重要な詳細（注意事項、修正、関連する警告）が 含まれていることがよくあります。open_nodes を省略すると、不完全な 情報に基づいて行動することになります。

3. たどる： 開いたエンティティの relations をたどって、関連する知識を 見つけます。関連エンティティごとに open_nodes を呼び出してください。 結果が関連しなくなるまで、探索を続けます。depends_on、contradicts、 supersedes、part_of のような関係は、行動の仕方を変える情報を示すことが よくあります。たとえば、回避策に依存する修正、後に訂正された慣例、 置き換えられた決定などです。

手順2または3を省略すると、ナレッジグラフの目的が損なわれます。 単純なキーワード検索だけでも手順1は実行できます。ナレッジグラフの価値は、 知識同士のつながりにあります。検索するだけで、エンティティを開いたり 関係をたどったりしなければ、誤りを防げたはずの反証情報、訂正、依存関係を 見落とすことになります。

重要： mcp__memento__read_graph は使用しないでください。記憶は すべてのプロジェクトにまたがっており、グラフが大きすぎて役に立ちません。

マルチディメンショナル検索

振り返りのたびに、検索を少なくとも2回行う必要があります。1回だけでは いけません。その理由は、エージェントが技術的なトピックは一貫して検索する 一方で、同じ過ちの繰り返しを防ぐプロセスやワークフローに関する学びを 見落としがちなためです。過去のセッションログには、エージェントが機能名だけを 検索し、実施中の作業の種類に関するプロセス上の学びを検索しなかったために、 同じユーザーからの指摘（チームメンバーの使い方、ADR プロセス、TDD ワークフロー、ビルドコマンド、承認プロセス）が繰り返されているパターンが 記録されています。

必須の検索観点：

1. 技術的なクエリ： 具体的なトピック、エラー、機能、またはドメインの概念
2. プロセスに関するクエリ： この種類の作業に関する学び（ミス、 修正、ワークフロー上の知見、この種の作業における慣例）

これから行うこと...	併せて検索すること...
TDD 作業	「TDD プロセスのミス」、「ペア作業の行き来からの学び」
エージェント／サブエージェントの起動	「チームメンバーの使い方」、「エージェントの連携上の問題」
エラーのデバッグ	「デバッグのワークフロー上のミス」、過去のエラーの発生例
ADR の作成	「ADR プロセス」、「ADR のミス」
コミット／PR／マージ	「コミットの慣例」、「承認プロセス」
プロセス上のあらゆる手順	「[プロセス] に関する修正」、「[プロセス] から得た教訓」

この表はすべてを網羅しているわけではありません。原則は、「この具体的な 内容について何を知っているか」だけでなく、「この種類の作業を行うことに ついて何を学んだか」と常に問いかけることです。

エラー発生時の想起 — 必須

エラー発生時の想起は、エージェントがメモリーの検索を最も怠りがちな場面であるため、一般的な想起のトリガーとは分けて説明します。よくあるパターンは次のとおりです。エラーが発生すると、エージェントはすぐに一からデバッグを始め、何度も修正を試み、過去に同じ問題が解決されていないか確認するのは、かなり後になってからです（確認しないこともあります）。これは時間を無駄にし、過去の作業を繰り返すことになります。

次の場合に発動します：

• エラーメッセージ、スタックトレース、または予期しない動作が発生したとき
• テストが失敗したとき
• フックが失敗したとき（pre-commit、CI、リンター）
• ユーザーからプロセスの修正を指示されたとき（「いいえ、代わりに X をしてください」）
• すぐに思いつく明白な修正で解決しない問題が発生したとき

ルール： 修正を試みる前に、必ずメモリーを検索してください。3 回失敗してからではありません。10 分間デバッグしてからでもありません。その前に検索してください。

多次元検索を適用します：

• 具体的なエラーメッセージまたは症状を検索します
• この種の状況に関するプロセス上の学びを検索します（例：「Node.js モジュールエラーのデバッグ」、「このプロジェクトでのテスト失敗のパターン」）

ユーザーから指摘を受けた場合： この指摘（または類似の指摘）がすでにメモリーに保存されていないか検索します。保存されていた場合は、想起できなかったことを認め、最新のコンテキストを加えてメモリーを強化します。

発見後の保存

一見して分からない問題を解決したとき、規約を学んだとき、または決定を下したときは、すぐに保存してください。後回しにすると、コンテキストを失います。

保存する内容：

• 一見して分からない問題の解決策（検索語としてエラーメッセージも含めます）
• 作業中に判明したプロジェクトの規約
• アーキテクチャ上の決定とその理由
• ワークフローやスタイルに関するユーザーの好み
• ツールの癖や回避策
• ユーザーからの指摘、特にプロセスに関する指摘

保存しない内容：

• 明白な情報や十分に文書化された情報
• 一時的な値やセッション固有の事実
• 冗長な説明（簡潔で検索しやすい項目にします）

作成する前に、必ず検索します。まず mcp__memento__semantic_search を使ってください。関連するエンティティが存在する場合は、重複して作成せず、mcp__memento__add_observations で情報を追加します。

エンティティ名： <Descriptive Name> <Project> <YYYY-MM> （例：「Cargo Test Timeout Fix TaskFlow 2026-01」）

観察事項の形式：

• プロジェクト固有：「Project: <name> | Path: <path> | Scope: PROJECT_SPECIFIC | Date: YYYY-MM-DD | <insight>」
• 一般：「Scope: GENERAL | Date: YYYY-MM-DD | <insight>」
• 各観察事項は、それだけで意味が通じる完全な文にします

関係 — エンティティの作成または更新後は、必ず 1 つ以上作成します。 mcp__memento__create_relations を使って、関連するエンティティにリンクします。関係の種類には能動態を使用します：implements、extends、depends_on、discovered_during、contradicts、supersedes、validates、part_of、related_to、derived_from。

エンティティの種類の表、観察事項の形式のガイド、関係の表、探索戦略、例については、references/memento-protocol.md を参照してください。

サブエージェントの責任

このプロトコルは、メインエージェントと、作業を委任されたサブエージェントの両方に適用されます。サブエージェントに指示する際は、メモリープロトコルの要件を明示してください。

サブエージェントは次のことを行う必要があります：

• 委任されたタスクを始める前に Memento を検索する
• 多次元検索（技術面とプロセス面の両方のクエリ）を適用する
• 作業中に新たな知見を得た場合は保存する
• 該当する場合は、既存のエンティティとの関係を作成する

Factory メモリー

パイプラインまたはファクトリーワークフロー内で実行する場合、パイプラインは今後の実行を最適化するため、運用上の学びを .factory/memory/ に保存します。

記録する学びの種類：

• CI のパターン： どのような種類の変更が CI の失敗を引き起こすか
• 手戻りのパターン： ゲートごとによくある手戻りの原因
• ペアの有効性： どのエンジニアのペアが、どの分野で最も効果的か
• 分野ごとのホットスポット： 指摘が頻繁に発生するファイルとモジュール

単独で利用するユーザーは Factory メモリーを無視できます。上記の標準的なメモリー運用は、引き続き変更ありません。

古くなったナレッジを整理する

メモリーが正確でなくなったことに気づいた場合（API が変更された、慣習が廃止された、バグが上流で修正されたなど）、更新するか削除してください。誤ったメモリーは、メモリーがないよりも悪いものです。

整理のきっかけ：

• メモリーが現在観察される動作と矛盾している
• 参照されているファイルや API が存在しなくなっている
• 慣習が明らかに変化している

コンテキストが失われる前に保存する

コンテキストの圧縮前、または自然な中断点で、未保存の発見を積極的に保存し、切り詰めによってナレッジが失われるのを防いでください。ナレッジが消えてしまう前の最後の機会です。

長時間実行セッション用の WORKING_STATE.md

単一のタスクを超えるセッション（パイプラインの実行、複数スライスにまたがる TDD、チーム連携など）では、コンテキスト圧縮やクラッシュに備えて WORKING_STATE.md ファイルを維持してください。

• 場所： .factory/WORKING_STATE.md（パイプラインモード）またはプロジェクトのルート
• 更新頻度： 重要な状態変化のたびに
• 読み込み頻度： セッション開始時、圧縮後、中断後

形式と例の詳細は references/working-state.md を参照してください。

セルフリマインダープロトコル

統合されたセルフリマインダープロトコル（頻度、まとめて再読み込みするリスト、圧縮後のルール）については、テンプレートディレクトリの CONSTRAINT-RESOLUTION.md を参照してください。

適用に関する注意

すべてのモードで推奨事項です。想起と保存の規律は自己管理してください。 read_graph の使用禁止はゲート条件です。このツールは役に立たない結果を返し、自然な抑止力として機能します。

厳守すべき制約：

• 重要なタスクに取り組む前に想起すること：[RP] -- Memento が利用できない場合は、その不足を記録し、メモリーなしで作業を続行して、ユーザーに伝えてください。

制約

• 「検索は少なくとも2回。1回だけでは不可」：2回の検索とは、問題の異なる側面を探る、意味的に異なるクエリを使うことです。「auth middleware」と「authentication middleware」を検索するのは、同義語を使った1回の検索であり、2回ではありません。意図は、技術的な側面（どの技術やパターンか）とプロセスの側面（どのような決定や慣習があるか）の両方を探ることです。
• 「重要なタスク」の基準：その結果がプロジェクトのコンテキスト（慣習、過去の決定、アーキテクチャ上の選択、ドメイン知識）に左右される場合、そのタスクは重要です。プロジェクトの履歴に関係なく、十分な能力を持つエージェントなら誰でも同じ結果を出す場合、そのタスクは些細なものです。迷ったら想起してください。不要な検索のコストは数秒ですが、関連するコンテキストを見落とすと手戻りが発生します。

検証

このスキルに沿った作業を完了したら、次の項目を確認してください。

• タスクを開始する前にメモリーを検索した（semantic_search）
• 技術的なトピックだけでなく、プロセスやワークフローに関する知見も検索した（多次元検索）
• 修正を試みる前に、重要なエラーごとにメモリーを検索した
• 発見事項を構造化された観察内容を含む Memento エンティティとして保存した
• 関連するエンティティを create_relations でリンクした
• サブエージェントにメモリープロトコルに従うよう指示した
• 古くなった、または矛盾するメモリーを未修正のまま残していない
• 長時間実行セッションで WORKING_STATE.md を維持した
• セルフリマインダープロトコルに従った（5～10メッセージごとに状態を再読み込みした）

依存関係

このスキルには Memento MCP が必要です。ワークフローを強化するため、次のものと連携します。

• debugging-protocol： 4段階の調査を始める前にメモリーを検索する
• user-input-protocol： 同じ質問を繰り返さないよう、ユーザーの回答を保存する
• tdd： セッション間でテストパターンとドメインモデリングの知見を保存する
• pipeline： パイプラインコントローラーは WORKING_STATE.md とセルフリマインダーを使い、長時間の自律実行中も役割の規律を維持する
• ensemble-team： チームコーディネーターはセルフリマインダーを使い、複数エージェントのセッション中に役割の逸脱を防ぐ

依存関係が見つかりませんか？次のコマンドでインストールしてください：

npx skills add jwilger/agent-skills --skill debugging-protocol