pce-memory AGENTS.md

pce-memory とは

プロジェクトの知識（設計決定、規約、好み、タスク）を永続化し、セッションを跨いで想起するためのMCPサーバーです。

---

利用フロー

1. activate     → タスク開始前に intent-aware な想起を行う（topology walk で関連 claim を自動展開）
2. observe      → 会話ログ・作業メモ・機密を raw micro memory として一時記録
3. distill      → raw 観測を durable 候補に蒸留
4. promote      → reviewable candidate を meso/macro memory に昇格
5. feedback     → 想起した知識の有用性をフィードバック
6. rollback     → 無効になった durable memory を append-only で修復（topology-based blast radius 付き）
7. link_claims  → claim 間のリンク作成（supports/extends/contradicts/supersedes/related）
8. graph_audit  → knowledge graph の健全性監査（orphan/cycle/scope hole/hub 検出）

upsert は already-distilled な durable knowledge の escape hatch としてのみ使ってください。通常の raw -> durable 変換経路では使いません。

---

いつ activate するか

以下の状況で pce_memory_activate を呼び出してください：

• 新しいタスクを開始するとき - 関連する過去の決定を確認
• 設計判断が必要なとき - 既存のアーキテクチャ決定を参照
• 命名や規約を確認したいとき - プロジェクト固有のルールを想起
• エラーに遭遇したとき - 過去の類似問題の解決策を検索

// 例: API設計前に関連知識を想起
{
  "intent": "design_decision",
  "q": "API 命名規約 RESTful",
  "scope": ["project", "principle"],
  "kind_filter": ["fact", "preference", "policy_hint"],
  "memory_type_filter": ["knowledge", "procedure", "norm"],
  "allow": ["answer:task"],
  "top_k": 10
}

---

いつ observe するか

以下の情報は pce_memory_observe で記録してください：

• session スコープの作業文脈 - 「このファイルを編集中」「デバッグ中の仮説」
• 生ログや一時メモ - チャット断片、ツール出力、HTTPレスポンス、ファイル読み取り結果
• secret/PII を含む可能性がある内容 - fail-safe に一時保存し、durable claim 化しない

// 例: セッション作業メモを一時記録
{
  "source_type": "chat",
  "content": "Issue #65 の observe 互換経路を削除中"
}

補足:

• observe は raw-only です。durable claim を inline で作成しません
• single_claim_v0 のような旧 extraction mode は使いません
• extract: { \"mode\": \"noop\" } は互換性のために残っていても raw-only のままです
• durable 化したい場合は distill -> promote を使ってください

---

いつ upsert するか

以下の情報だけを pce_memory_upsert で記録してください：

• すでに distill 済みとみなせる durable knowledge
• project または principle に置くべき確定事項
• provenance を付けて追跡可能にしたい事実・好み・手順・ポリシー
• 技術・ファイル・概念の関係が明確な場合は、entities / relations も同じ upsert に含めてください