project-memory について
project-memoryは、調査や試行錯誤に手間がかかったプロジェクト固有の知見を保存し、後続のエージェントが再利用するためのスキルです。Pythonスクリプトで読み込み、検索、追記を行い、記録基準や古い項目の更新方法も定めています。
主な機能
- 01作業開始前にプロジェクトの知見を読み込む
- 02部分一致で記録を検索
- 03キーを指定して知見を追加・更新
- 04項目を重複排除し展開表示
- 05知見の種類と確信度を記録
活用シーン
- 01コード変更前にプロジェクト固有の知見を確認
- 02作業に関連する既存の解決策を検索
- 03調査に時間を要した後で検証済みの修正を記録
- 04古いと確認された知見を修正
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/project-memoryを入力して読み込まれたか確認します。
同梱ファイルreferences/store-operations.mdscripts/memory.py
詳細
目的とワークフロー
何度も失敗を重ねたり、見つけるために多くの検索や時間、トークンを費やしたプロジェクト固有の解決策を記録し、次のエージェントが同じ作業を繰り返さずに済むようにします。
- プロジェクトで作業を始めるとき — 頼まれるのを待たず、コードを読んだり変更したりする前に
loadを実行します。その領域で作業する前に、関連するキーを検索します。 - 何かを学んだとき、または作業を終えたとき — 以下の記録基準を確認し、該当する学びがあれば
addを実行します。保存した項目を報告します。該当するものがなければ、報告は不要です。
スクリプト
読み書きはすべて、このスキル独自のディレクトリにある
scripts/memory.py を通して行います。echo で JSON を手作業で作成しないでください。引用符や
バックスラッシュを含む知見があると、ファイルがひそかに破損します。
python3 が必要です（標準ライブラリのみで、パッケージは不要です）。見つからない場合は、その旨を伝え、シェルでの文字列構築に切り替えないでください。
_MEM="<this skill's directory>/scripts/memory.py"
python3 "$_MEM" --help
| コマンド | 処理内容 |
|---|---|
load | このプロジェクトのメモリを、キーごとに重複を除き、階層化して表示します |
load --all | 同じ内容を、すべての項目について詳細まで展開して表示します |
load --json | 同じ内容を JSON 配列として表示します |
add | 学びを 1 件追加し、必要に応じて古い項目を統合します |
search QUERY | 部分文字列で学びを絞り込みます |
stats | 種類ごとの件数と平均信頼度を表示します |
path | このプロジェクトの保存先パスを表示します |
Load（最初に実行）
python3 "$_MEM" load
出力は、知識がほかの場所にも記載されているかどうかに基づいて階層化されています。pitfall、pattern、
preference は、プロジェクト内のほかの場所には記録されていないため、全文を表示します。architecture と tool は、
AGENTS.md とコードにすでに記載されており、エージェントがこれから読むため、キーの一覧だけを表示します。
## Only recorded here (pitfall, pattern, preference)
- **n-plus-one-products** (9/10) — Product.includes(:variants) needed in catalog controller
## Index — 42 more, run `search <key>` for the full text
- **architecture**: no-orm-raw-sql, events-are-append-only
- **tool**: rg-over-grep
保存件数がどれほど増えても、すべてのキーが常に一覧に表示されます。詳細を省略するのはかまいませんが、
項目の存在を隠してはいけません。存在を確認できないキーは、検索されることもないからです。これから作業する内容に関連するキーがあれば、その領域に手を付ける前に
search <key> を実行します。
python3 "$_MEM" search n-plus-one-products
すでに重複は除去されています。同じキーでは、最新の項目が優先されます。NO_LEARNINGS は新しい
プロジェクトを意味します。そのまま作業を続けてください。破損した行は中断せずにスキップし、報告します。
ストア全体を読みたい場合は、--all ですべてを展開します。
load の最後には記録を促すリマインダーが表示されます。--json と --all では表示されません。
Add
実際に起きたことに基づいて各項目を作成し、条件を満たす項目は、ユーザーに各項目の記入や承認を求めずに記録します。保存した内容を報告します。
- Type — 実際に問題が起きた場合は
pitfall、有効だと分かった作業方法にはpattern、ユーザーが希望する進め方にはpreferenceを使います。この 3 種類は全文が読み込まれます。architectureとtoolはプロジェクトの構成を説明するもので、リポジトリ内のファイルにすでに記載されているため、キーのみが読み込まれます。項目の重要度や表示方法ではなく、内容に応じて種類を選んでください。 - Key — ケバブケースを使い、学びの内容が分かるキーにします。多くの項目は
loadでキーだけが表示されるため、lesson-001は実質的に見つけられませんが、n-plus-one-productsなら見つけられます。スクリプトは汎用的なキーと番号付きのキーを拒否します。 - Insight — 再利用できる簡潔な学びを記述します。該当する条件、避けるべき失敗した方法、検証済みの解決策とその根拠または場所を含めます。根本原因が確認できている場合は記載し、未確定の内容にはその旨を明記します。
- Confidence — 1～10
python3 "$_MEM" add \
--type pitfall \
--key n-plus-one-products \
--insight 'Product.includes(:variants) needed in catalog controller — N+1 caused 3s load' \
--confidence 9 \
--files 'app/controllers/catalog_controller.rb'
スクリプトはタイムスタンプ、ブランチ、スラッグを補完します。--source の既定値は
user-stated です。ほかのスキルから実行する場合は、そのスキル名を渡してください。
既存のキーを再度追加すると、その項目を更新できます。load には最新の項目だけが表示されます。古い学びを修正する前に、古い学びが誤りだった場合 に従ってください。
根本原因が同じ項目を統合する前に、コマンド、保持ルール、統合されたキーの復元方法について、 項目の統合 を読んでください。
記録する価値のある内容
- 確信度が7以上の内容に限ります。
- プロジェクト固有の教訓に限ります。一般的なプログラミング知識はここには記録しません。
AGENTS.mdに書くべき内容でしょうか？ それなら、そちらに書いてください。このストアに記録するのは、作業中に初めて明らかになったこと、つまり何が壊れたのか、最終的にどの修正が有効だったのか、次回はユーザーがどのように進めてほしいのかです。- 技術的な教訓については、失敗を繰り返した後に検証済みの解決策を得た場合、または相当な調査や時間、トークンを費やして初めて有効な方法を見つけた場合に記録します。そのエントリーは、類似のケースで同じコストを繰り返さずに済むものである必要があります。
- 避けるべきだった失敗ルート、有効だった方法、その方法が適用できる条件、根拠を残します。再試行回数、トークン総数、所要時間を捏造しないでください。調査に多大なコストがかかったと認識するのに、測定したコストは必要ありません。
- 通常の成功、一般的なアドバイス、作業記録、推測に基づく修正は保存しません。明示されたユーザーの好みは、同じプロジェクト固有のルールに従う限り、記録の対象になります。
- タスクリストや未解決のバグは記録しません。それらはプロジェクトのイシュートラッカーまたは
AGENTS.mdに記録してください。
古い教訓が通用しなくなった場合
- 既存のエントリーを読み、前提条件を現在のバージョン、環境、入力、使用方法と比較します。ソースコードの根拠または目的を絞った再現によって問題を調査します。失敗が1回あっただけでは、無効だとは判断できません。
- 一時的な問題やエントリーの適用条件外での使用と、同じ条件下でその方法が機能しなくなったケースを区別します。原因が解明されていない場合は、古い教訓を誤りだと書き換えず、不確実性を報告します。
- 無効であることが確認できたら、承認を求めず、同じキーを指定して
addを使い、現在の教訓を置き換えます。根拠、影響を受ける条件、検証済みの代替策を記録します。代替策がわからない場合は、失敗した方法を推奨し続けず、その限界を明記します。古い方法が引き続き有効な条件は残し、適用可能な吸収関係も維持します。 - 修正内容を確認するため、エントリーを読み返します。追記専用の履歴を維持し、ストアの行を手動で編集または削除しないでください。
他のスキルやエージェントが学びを記録する方法
作業を委任する場合、メインエージェントは各ワーカーのプロンプトに、関連する保存済みの教訓を含めます。ワーカーは、コストのかかった試行錯誤で得た知見と根拠、および古くなっている疑いのあるエントリーを、ストアに直接書き込まず、メインエージェントに返します。メインエージェントは、承認を求めずに、条件を満たす教訓や確認済みの修正を検証、重複排除し、記録します。
呼び出しは1回で、フォーマットの重複はありません。
python3 <project-memory>/scripts/memory.py add \
--type pitfall --key '<key>' --insight '<concise reusable lesson>' \
--confidence 8 --source '<skill-or-agent-name>' --files '<file>'
同じルールが適用されます。確信度が7以上で、プロジェクト固有であり、実際に遭遇した内容に限ります。
保存とエクスポート
共有ストアは ~/.mystack/projects/<slug>/learnings.jsonl です。
場所やフォーマットを確認するには、
保存形式とプロジェクトの識別を読んでください。
引き継ぎやプロジェクト文書用にメモリのエクスポートを依頼された場合は、 エクスポートを読んでください。自動的にプロジェクト文書へ追記しないでください。