pma-mem

Knowledge Palace

プロジェクトのナレッジを記録して取得します。ストレージバックエンド：Memos（$MEMOS_URL、$MEMOS_TOKEN）。

常時適用されるルール

1. 操作を行う前に、必ず $MEMOS_URL と $MEMOS_TOKEN を確認してください。設定されていない場合は、ユーザーに確認してください。
2. ナレッジの各項目には、必ず type タグを付けてください。
3. 書き込む前に、必ず topicHash で重複を確認してください。
4. 1つのメモには、ナレッジの要点を1つだけ記録してください。複数のトピックを1つのメモにまとめてはいけません。
5. 関連するナレッジの要点は、メモのリレーション（REFERENCE）でリンクしてください。
6. 実装する前に：まず関連するナレッジを検索してください。現在のタスクに適用できる既存の判断、発見、パターンがないか確認してください。

検索するタイミング

エージェントは、次の状況でナレッジベースを検索してください。

• エラーや予期しない動作が発生したとき：#discovery とキーワードで検索してください。以前に同じ問題に遭遇した人がいるかもしれません。
• 技術的な選択をするとき：#decision とキーワードで検索してください。すでに判断が下されていないか、またその理由を確認してください。
• パターンを実装するとき：#pattern とキーワードで検索してください。実証済みの方法を再利用してください。
• 前提を検証するとき：#fact とキーワードで検索してください。その前提をもとに作業を進める前に確認してください。

ナレッジの種類

種類は5つです。フラットなタグで、各メモには必ず1つだけ付けます。

#fact · #event · #discovery · #decision · #pattern

追加のタグは任意で、自由形式です。内容に応じてエージェントが判断します。

分類ルール、内容のガイドライン、品質チェックの詳細については、references/classification.md を参照してください。

メモの形式

## {title}

{content — preserve context and reasoning, not just the conclusion}

#fact

• 末尾のコメントはメタデータです：topicHash（重複判定キー。タイトルの md5 の先頭8文字）と from:（ナレッジの出所。例：session、bkd/issueId、manual）
• タグはメタデータではなく、本文に記載してください

操作

書き込み

AUTH="Authorization: Bearer $MEMOS_TOKEN"
API="$MEMOS_URL/api/v1"

# 1. Check duplicate by topicHash
HASH=$(echo -n "Title here" | md5sum | cut -c1-8)
EXISTS=$(curl -s -H "$AUTH" \
  "$API/memos?filter=content.contains(\"$HASH\")" \
  | jq '.memos | length')

# 2. Create (if not exists)
curl -s -X POST -H "$AUTH" -H 'Content-Type: application/json' \
  "$API/memos" \
  -d '{"content":"## Title\n\nContent\n\n#fact\n\n","visibility":"PRIVATE"}' | jq

# 3. Update (if exists and changed)
curl -s -X PATCH -H "$AUTH" -H 'Content-Type: application/json' \
  "$API/memos/{uid}?updateMask=content" \
  -d '{"content":"...updated..."}' | jq

# 4. Link related memos
curl -s -X PATCH -H "$AUTH" -H 'Content-Type: application/json' \
  "$API/memos/{uid}/relations" \
  -d '{"relations":[{"relatedMemo":"memos/{otherUid}","type":"REFERENCE"}]}' | jq

検索

操作を行う前に、ナレッジを取得するために検索してください。取得した内容をエージェントのコンテキストに渡してください。

# By type
curl -s -H "$AUTH" "$API/memos?filter=tag+in+[\"discovery\"]" \
  | jq '.memos[]|{uid,snippet}'

# By type + keyword
curl -s -H "$AUTH" "$API/memos?filter=tag+in+[\"decision\"]" \
  | jq '.memos[]|.content' | grep -i "keyword"

# Full-text search
curl -s -H "$AUTH" \
  "$API/memos?filter=content.contains(\"keyword\")" \
  | jq '.memos[]|{uid,snippet}'

# Get full content
curl -s -H "$AUTH" "$API/memos/{uid}" | jq '.content'

# Follow links
curl -s -H "$AUTH" "$API/memos/{uid}/relations" \
  | jq '.relations[].relatedMemo'

記録

会話中にユーザーが「覚えておいて」「保存して」「記録して」と言った場合、 またはエージェントが保存する価値のあるナレッジを見つけた場合：

1. 現在の会話から1つ以上のナレッジの要点を抽出する
2. 各要点に種類とタグを割り当て、topicHash を生成する
3. 重複を確認 → 作成または更新 → 要点が複数ある場合はリンクする

エージェントは、次のような内容に遭遇した場合も、積極的に記録を提案してください。

• デバッグによって確認された、わかりにくい技術的事実
• 選択肢を比較検討したうえで下された判断
• 実装中に発見した注意点や落とし穴
• うまく機能した再利用可能なパターンやワークフロー

整理統合

必要に応じて実行します。ユーザーから整理を依頼された場合、または検索中にエージェントが内容の重複したメモを見つけた場合に行います。

1. タググループを読み込みます：curl -s -H "$AUTH" "$API/memos?filter=tag+in+[\"auth\"]&pageSize=100" | jq
2. ほぼ重複する内容、古くなった事実、断片的な内容がないか確認します
3. 1つのメモに統合し、元のメモをアーカイブします。詳細については references/knowledge-sync.md を参照してください

リファレンスパック

• references/classification.md 種類の定義、内容のガイドライン、タグ付けルール、品質チェック、整理統合のルール。
• references/storage-api.md Memos REST API リファレンス（CRUD、フィルター、リレーション、ページネーション、添付ファイル）。
• references/knowledge-sync.md 自動同期ワークフロー：スキャン、抽出、重複確認、差分更新、自動化ガイド。

クイックルーティング

• ナレッジの分類やフォーマット：references/classification.md を読み込みます。
• API の詳細（updateMask、フィルター、エラーコード）：references/storage-api.md を読み込みます。
• タスク管理システムからの自動同期：references/knowledge-sync.md を読み込みます。
• 簡単な記録や検索：上記の操作をそのまま使用します。