feat(memory): add retrieval history, usage, activation, and reversible graph feedback #259

目的

マスターの「NGRから取り入れる4機能を全部対応」という指示により、github-rag-mcpへ、検索履歴、資料のselected/validated/used記録、活性度と時間減衰、有効な関係の強化と誤った強化の取り消しを一貫した永続feedback機能として実装する。4機能をつなぐtrace/provenance契約を同一PRで完成させる。

確認済みの前提

• 現行main 87fb833。Worker MCPは1リクエストごとのstateless serverで、getMcpAuthContext().propsに認証済みgithubUserIdがある（src/mcp.ts / src/index.ts / src/oauth.ts）。
• 既存IssueStoreはglobal Durable ObjectのSQLite、D1 DB_FTSはsearch_docsとdoc_edgesを持つ。memory専用テーブル/モジュールを追加でき、新たなサービスやPython/モデルの配布を要しない。
• searchはsearch/scan/fetch各モードを持つ。graph_resultsはresultsから分離され、既存graphはwiki slug mentionを双方向に1〜2hop辿る。queryNeighborsはorigin/hopだけを返すため、creditには実際の各edgeを保存する拡張が必要。2hopのorigin→終点を架空の直接edgeとして強化してはならない。
• vector_idは一時的な取得handleで移行実績がある。長期のmemory識別子はrepo/type/URLやpath、issue/comment/review ID等のcanonical情報から構成し、vector IDだけに依存させない。
• NGR参照: D:/Users/hal/Codex/neuron-graph-rag/src/neuron_graph_rag/{engine.py,feedback.py,evidence_feedback.py,storage.py}、src/neuron_graph_rag_mcp/server.py。activationは半減期による指数減衰、feedbackはtraceへの所属、順序、idempotency、saved credited pathとdeltaを管理する。NGR自体のコードは変更しない。
• 過去判断 spec(search): return graph-derived results as a separate axis instead of score-0 rows in results #234 はkeywordとgraphの融合をやめ、graphはhop昇順・relevance scoreなし、keywordのscore/rankを維持する契約。今回もこの境界を保持する。新しいtrace/source handle等のmetadata追加は今回の機能として明記する。
• bridgeのtools/listは静的mirror。現在schema drift checkはsearchのみを検査するので、今回追加する全tool/入出力契約もWorker↔bridgeで一致を検証する必要がある。

要求

検索履歴と資料ID

• 成功したsearch/scan/fetch呼び出しをUTC timestamp・query/filter/mode・返した資料/両軸・検索設定とともに永続化し、trace_idを返す。0件も記録する。未成立/失敗を成功した履歴として残さない。
• 返した資料は安定したsource_idとprovenanceを持つ。同じ実体の異なるversion/eventをcredit時に誤って同一視しない。本文やsecretの不要な複製はしない。
• 同じGitHubユーザーで使うクライアント間で共有する。認証済みprincipalはサーバー側で決め、caller指定user IDを信用しない。他ユーザーのtrace/history/feedbackを読み書きできない。
• 履歴一覧/trace詳細を読むMCP機能を提供。limit/cursorなどで入力・出力・DB readを制限し、source usage、outcome、activationと取り消し履歴を確認できる。raw queryやsource情報をログへ出さない。
• 履歴の書込に失敗したとき、保存されていないtraceを成功扱いで発行しない。既存searchを継続可能にする場合はmemory失敗を明示しfeedback不可にする等、fail-closedな結果にする。

資料の利用記録

• record_source_use相当のMCP APIでtraceの資料についてselected→validated→usedを明示的に記録する。意味と呼出し方をserver instructions / tool descriptionで明記する。
• selectedは調査対象として選んだ、validatedは正確な出典を確認して利用可と判断した、usedは実際の回答/判断に使用した、という区別を保つ。検索だけをusedやconfirmedと解釈しない。
• 存在しないtrace/source、別principalのhandle、順序違反を拒否し、batchは原子的に適用する。
• idempotency_key付きで、同payloadのretryは同receiptを返し、同keyの異なるpayloadは拒否する。既記録stageの再送でactivation/evidence/weightを増やさない。

活性度と減衰

• 検索でのretrievedと明示的usageから、種別の違いがわかる上限付きactivationを保存する。search activationとgraph reinforcementは別状態。
• 半減期を使った指数減衰（NGR既定3600秒を起点に、設定値/上限/加算量を実装・文書で固定）。clock逆行はelapsed=0、数値は有限・非負。cronを要せず読取/更新時に計算する。
• search結果およびhistoryで現在のactivation・更新日時を参照できる。
• 学習をretrievalへ反映するopt-in（例use_memory）は明確な契約にする。keywordのscore/rank/fusion/rerank、graphのhop昇順と軸分離を維持し、activation/learned strengthをrelevance scoreとして偽装しない。graphの同hop内候補に学習が実際に効く形を用意し、初期状態は既存と等価。

関係の強化と取り消し

• used済み資料のconfirmed outcomeで、traceに保存された実際のcredited graph pathだけを上限付きで強化する。retrieved/selected/validated/usedだけではgraphを強化しない（confirmed-only方式）。新しい辺やlexical/zero-hop辺を捏造しない。
• 独立traceの確認にのみ追加の証拠を与え、重複確認/retry/同trace重複では二重加算しない。無限強化を避ける減衰/上限を文書化する。
• corrected/rolled_backで因果的に指定された実際の寄与deltaを取り消す。superseded等を扱う場合もauditとactive状態を保持する。後から他traceが同edgeを強化していても、その有効な寄与を失わせない。曖昧な取消しはmutateせず明確なerror/非適用理由を返す。
• ledger/receiptにsaved path、適用delta、理由、timestamp、active/reversed状態を残し、retry・並行リクエストでも原子的に一貫させる。
• ingest/reindexによるdoc_edgesのdelete/insertやvector ID移行でlearned stateを取り違えない。元のmention topologyを壊さず、principal別のlearned stateを保持する。

実装・完了条件

• 既存SQLite DOのmemoryテーブルを独立moduleとして利用する案を第一候補とし、既存テーブルを消したりresetしたりしない。必要なD1 schema変更がある場合は同PRに移行と手順を含める。
• Workerとstdio bridgeの新API/schema、annotations、server instructions、requirements/READMEを同PRで同期する。searchは履歴保存というwriteを持つためreadOnlyHintも実挙動に合わせる。
• 公開version/tag/releaseは今回はまだ作成しない。実装→PR→CI→親review→mergeまで行い、デプロイ/公開版に必要な具体的手順・移行・artifactを揃えてからマスターへversion/typeを提示する。
• 回帰テスト: 時刻つきtrace、0件/scan/fetch/graph、principal分離、安定source ID、段階遷移、idempotency conflict、batch rollback、半減期/上限/逆時刻、2hop実path credit、独立確認/重複排除、interleaved強化後の厳密な取消し、並行更新/reindex、default keyword/graph契約、Worker↔bridge全tool契約。テストは実DBや本番学習状態を汚さない。
• mainに全4機能が存在し、CI green。履歴・used・confirmed・取消しをつなぐin-process実演例と実行結果を残す。検索品質が向上したとの主張は別評価なしでは行わない。

対象ファイル

src/mcp.ts、src/store.ts、src/graph.ts、src/types.ts、新規memory/feedback modulesとtests、mcp-server/server/{tools.js,index.js}、mcp-server/test、schema/contract検査、READMEの日英版とdocs/0-requirementsの日英版、該当memory仕様。必要な設定/移行ファイルも含む。NGR repo、認証credential、既存client設定、本番memory DBはこの実装段階では変更しない。