lipluscodex · Sep 30, 2026 · Sep 30, 2026 · Sep 30, 2026
diff --git a/README.ja.md b/README.ja.md
@@ -95,7 +95,15 @@ GitHub webhooks + GitHub API
 
 ## MCP Tools
 
-この MCP サーバーが公開するツールは 1 つに統合されています。意味検索、時系列 activity scan、doc 本文取得、`vector_id` 指定の保存済み本文取得のいずれも `search` のパラメータ経由で扱えます。以前の build で分かれていた `get_issue_context` / `get_doc_content` / `list_recent_activity` は削除され、用途は下記パラメータに吸収されました。
+この MCP サーバーは `search` と3つの非公開 feedback ツールを公開します。意味検索、時系列 activity scan、doc 本文取得、`vector_id` 指定の保存済み本文取得のいずれも `search` のパラメータ経由で扱えます。以前の build で分かれていた `get_issue_context` / `get_doc_content` / `list_recent_activity` は削除され、用途は下記パラメータに吸収されました。
+
+### 非公開 feedback ツール
+
+成功検索は既定で UTC trace を保存し、資料の版を指す `source_id` と現在 activation を返します。`memory_history` で履歴・利用段階・取消し audit を読み、`record_source_use` で selected→validated→used、`record_outcome` で confirmed または receipt を指定した corrected/rolled_back を記録します。検索だけでは used/confirmed になりません。保存不可の結果には trace がなく feedback 不可です。半減期3600秒、activation は各 channel 上限10（total20）、graph strength 上限5です。成功検索に DO request と保存コストが加わります。
+
+live inline doc/wiki 本文は返した本文の SHA-256 で版を識別し、`github_live` provenance を持ちます。stored fetch と graph 本文は index snapshot の版で、索引 timestamp が同じでも live 本文の変更は別 source_id になります。
+
+[仕様・移行・合成実演](docs/2-feedback-memory.ja.md) を参照してください。0008 を Worker deploy より先に適用し、新 schema JSON を bridge artifact に同梱します。検索品質向上は未評価です。
 
 ### `search`
 
@@ -134,8 +142,9 @@ bot (`sender.login` が `[bot]` で終わる) と trim 後 10 文字未満の bo
 | `until` | ISO 8601 文字列 | `updated_at < until` の結果だけを残します。 |
 | `include_content` | boolean | 上位 doc 結果に本文を inline する (既定 `false`)。 |
 | `vector_ids` | string[] | 保存済み本文の取得。読み出す行の `vector_id`、1 回あたり最大 50 件。他モードより優先され、指定時は `query` / `sort` と全 filter が無視されます。下記「保存済み本文の取得」参照。 |
-| `graph_expand` | boolean | opt-in の GraphRAG 拡張（search モードのみ）。`true` のとき fusion 後の上位結果を seed に Decision-Structure の mention グラフ（D1 `doc_edges`）を辿り、関連 wiki ページを `graph_hop` / `graph_from` 付きで別配列 `graph_results` として返す（下記「検索の 2 軸」参照）。既定 `false` は標準ハイブリッド検索とバイト単位で同一（グラフ未参照）。 |
+| `graph_expand` | boolean | opt-in の GraphRAG 拡張（search モードのみ）。`true` のとき fusion 後の上位結果を seed に Decision-Structure の mention グラフ（D1 `doc_edges`）を辿り、関連 wiki ページを `graph_hop` / `graph_from` 付きで別配列 `graph_results` として返す（下記「検索の 2 軸」参照）。既定 `false` は標準ハイブリッドの順位を保つ（グラフ未参照）。trace metadata は追加される。 |
 | `graph_hops` | number | `graph_expand` のグラフ探索深度（1 または 2、既定 1）。`graph_expand` が `false` のときは無視。 |
+| `use_memory` | boolean | 既定 false。true は最大200 graph 候補を同 hop 内で learned strength 順にしてから返却上限へ絞る。keyword の score/rank は維持。 |
 
 #### `type` 値
 

diff --git a/README.md b/README.md
@@ -95,7 +95,15 @@ See:
 
 ## MCP Tools
 
-This MCP server exposes a single consolidated tool. All retrieval modes — semantic search, time-ordered activity scan, inline doc content fetch, and stored-content fetch by `vector_id` — are reached through `search` via its parameter set. Earlier builds split these across `get_issue_context`, `get_doc_content`, and `list_recent_activity`; those tools have been removed and their use cases now fold into the parameters below.
+This MCP server exposes `search` and three private feedback tools. All retrieval modes — semantic search, time-ordered activity scan, inline doc content fetch, and stored-content fetch by `vector_id` — are reached through `search` via its parameter set. Earlier builds split these across `get_issue_context`, `get_doc_content`, and `list_recent_activity`; those tools have been removed and their use cases now fold into the parameters below.
+
+### Private feedback tools
+
+Successful retrieval writes a UTC trace by default, returning version-specific `source_id` and current activation. `memory_history` reads history, stages and reversal audit; `record_source_use` records selected→validated→used; `record_outcome` confirms a saved path or corrects/rolls back one named receipt. Retrieval alone is never usage or confirmation. Memory failure emits no usable trace. Half-life is 3600 seconds, each activation channel caps at 10 (total 20), and relation strength caps at 5. Successful retrieval adds a DO request and storage cost.
+
+Live inline doc/wiki bodies use the returned-text SHA-256 version and `github_live` provenance. Stored fetch and graph bodies refer to the index snapshot; changed live text has another source ID even with the same index timestamp.
+
+See the [specification, migration and synthetic lifecycle](docs/2-feedback-memory.md). Apply 0008 before Worker deployment and include the new schema JSON in bridge artifacts. Retrieval quality improvement has not been evaluated.
 
 ### `search`
 
@@ -134,8 +142,9 @@ Bot-authored comments (`sender.login` ending in `[bot]`) and comments shorter th
 | `until` | ISO 8601 string | Keep only results with `updated_at < until`. |
 | `include_content` | boolean | Inline raw content on top doc results (default `false`). |
 | `vector_ids` | string[] | Stored-content fetch. The `vector_id` values of the rows to read back, max 50 per call. Takes precedence over the other modes: `query`, `sort` and every filter are ignored when present. See [Stored-content fetch](#stored-content-fetch). |
-| `graph_expand` | boolean | Opt-in GraphRAG expansion (search mode only). When `true`, after fusion the top results seed a traversal of the Decision-Structure mention graph (D1 `doc_edges`); related wiki pages come back in a separate `graph_results` array tagged `graph_hop` / `graph_from` — see Retrieval axes below. Default `false` = byte-identical to standard hybrid retrieval (no graph read). |
+| `graph_expand` | boolean | Opt-in GraphRAG expansion (search mode only). When `true`, after fusion the top results seed a traversal of the Decision-Structure mention graph (D1 `doc_edges`); related wiki pages come back in a separate `graph_results` array tagged `graph_hop` / `graph_from` — see Retrieval axes below. Default `false` preserves standard hybrid ranking (no graph read); trace metadata is added. |
 | `graph_hops` | number | Graph traversal depth for `graph_expand` (1 or 2, default 1). Ignored when `graph_expand` is `false`. |
+| `use_memory` | boolean | Default false. True orders up to 200 graph candidates by learned strength within equal hops before the output cap. Keyword scores/ranks are preserved. |
 
 #### `type` values
 

diff --git a/docs/0-requirements.ja.md b/docs/0-requirements.ja.md
@@ -83,16 +83,7 @@ Responsibilities:
 - semantic retrieval と structured retrieval の tool を公開する
 - downstream agent がそのまま使える形式で state を返す
 
-スキーマの source of truth は Worker 側の tool 定義。client proxy
-(`mcp-server/server/tools.js`) は `tools/list` を Worker へ転送せず、`search`
-params の静的ミラーから応答する（起動時を auth/network なしに保つため）。ミラーは
-手動保守ゆえ、Worker に param を足して proxy を忘れると、MCP クライアントが
-`additionalProperties: false` で黙って落とし Worker に届かない（gh#157）。
-`scripts/check-schema-drift.mjs` を CI で実行し、proxy の `search` スキーマが Worker
-からズレたら build を失敗させる。両者は同期せずに出荷できない。
-比較する軸は 2 つ、param 名と enum param の値。名前だけの比較では proxy の `type`
-enum から `wiki_doc` が抜けたまま気付けず、Worker は受け付けるのにクライアント側で
-値が弾かれていた（gh#181）。
+Worker の Zod contract を source of truth とし、bridge は生成した静的 JSON で `tools/list` を返す。起動時の auth/network は不要。`scripts/generate-tool-contracts.mjs` で再生成し、`scripts/check-schema-drift.mjs` は全4 tool の実 protocol と nested input/output schema、bounds、defaults、annotations の一致を CI で検査する。名前/enum のみだった旧 guard を拡張する（#259）。
 
 #### プロトコル版 2026-07-28、単レーン
 
@@ -117,7 +108,7 @@ README 注意書きで吸収する。
 - かつて MCP を提供していた Durable Object（`RagMcpAgent` / `RagMcpAgentV2`）は
   経路から外れた。過去の migration が名指しするクラスはスクリプト内に存在せねば
   ならないという Cloudflare の制約のため、退役スタブとして export だけ残す。撤去には
-  `deleted_classes` migration が要る。実データを保持する `IssueStore` は無変更。
+  `deleted_classes` migration が要る。`IssueStore` は実データを保持し、#259 では独立 memory table を追加する。
 
 この版は本 repository の 2 成果物のあいだの私的な契約である。Worker へ到達する経路は
 npx ブリッジ（`mcp-server/`）だけ——`server.json` は stdio トランスポートしか宣言
@@ -668,3 +659,11 @@ embedding が失敗した record は incomplete と分かる形で残し、次
 - ranking と filtering の改善
 - multi-agent handoff retrieval の改善
 - cross-repository state recovery の改善
+
+## 検索 feedback memory（Issue #259）
+
+検索履歴、selected/validated/used、半減期3600秒の retrieved/usage activation、confirmed-only の実 path 強化と receipt 指定取消しを同じ PR で実装する。認証済み GitHub principal ごとに共有・分離する。成功検索は trace を原子的に保存し、保存失敗や部分取得は trace を発行せず feedback 不可とする。検索は既定で履歴を書き、keyword の順位は維持する。use_memory は graph の同 hop 内だけに影響し、2 hop の実 edge を保存する。
+
+新 API は `memory_history`、`record_source_use`、`record_outcome`。設定値、上限、ID/version、batch/idempotency、ledger、error、0008先行移行、既存行 backfill と artifact の契約は [2-feedback-memory.ja.md](2-feedback-memory.ja.md) に定義する。会話/本文/credential の複製は行わず、品質向上の主張は別評価を必要とする。
+
+#259 の版契約: live inline doc/wiki は返した本文の SHA-256 を version とし、index snapshot と provenance を分ける。同じ索引 timestamp でも live 本文更新は別 source_id にする。本文を memory に複製しない。
diff --git a/docs/0-requirements.md b/docs/0-requirements.md
@@ -83,17 +83,7 @@ Responsibilities:
 - expose semantic and structured retrieval tools
 - return state in a format that downstream agents can consume directly
 
-Schema source of truth: the Worker tool definitions are authoritative. The client
-proxy (`mcp-server/server/tools.js`) answers `tools/list` from a static mirror of
-the `search` params — it does not forward `tools/list` to the Worker, keeping
-startup auth-free and network-free. Because that mirror is hand-maintained, a param
-added to the Worker but forgotten in the proxy is silently dropped by MCP clients
-(`additionalProperties: false`) and never reaches the Worker (gh#157).
-`scripts/check-schema-drift.mjs` runs in CI and fails the build when the proxy
-`search` schema drifts from the Worker, so the two cannot ship out of sync.
-The check compares two axes: param names and, for enum params, their values —
-a name-only comparison let the proxy `type` enum omit `wiki_doc` while the Worker
-accepted it, so clients rejected the value before any request was sent (gh#181).
+Worker Zod contracts are the source of truth. The bridge answers `tools/list` from generated static JSON without startup auth/network. `scripts/generate-tool-contracts.mjs` regenerates those artifacts; `scripts/check-schema-drift.mjs` compares all four tools against their actual served nested input/output schemas, bounds, defaults and annotations in CI. This extends the previous name/enum-only guard (#259).
 
 #### Protocol revision: 2026-07-28, single lane
 
@@ -120,7 +110,7 @@ Consequences of statelessness:
   out of the serving path. Their classes remain exported as retired stubs
   because Cloudflare requires every class named in a past migration to exist in
   the script; removing them needs a `deleted_classes` migration. `IssueStore`,
-  which holds real data, is untouched.
+  which holds real data, gains independent memory tables in #259.
 
 The revision is a private contract between this repository's two artifacts. The
 npx bridge (`mcp-server/`) is the only way to reach the Worker — `server.json`
@@ -674,3 +664,11 @@ If an embedding attempt fails, the state must remain detectable as incomplete so
 - stronger ranking and filtering behavior
 - better multi-agent handoff retrieval
 - better cross-repository state recovery
+
+## Retrieval feedback memory (Issue #259)
+
+Implement retrieval history, selected/validated/used records, retrieved/usage activation with a 3600-second half-life, and confirmed-only real-path reinforcement with receipt-based reversal atomically in one PR. Share and isolate by authenticated GitHub principal. Successful retrieval commits its trace atomically; memory/partial retrieval failures emit no trace and cannot accept feedback. History writes are enabled by default, keyword ranking is preserved, and use_memory changes only same-hop graph ordering. Save actual two-hop edges.
+
+The APIs are `memory_history`, `record_source_use`, and `record_outcome`. [2-feedback-memory.md](2-feedback-memory.md) owns constants, bounds, source version identity, batch/idempotency, ledger, errors, migration 0008-before-deployment, historical backfill and bridge artifacts. Do not duplicate conversations, bodies or credentials. Claims of retrieval quality improvement require separate evaluation.
+
+Issue #259 version contract: live inline doc/wiki uses the returned-text SHA-256 version and provenance separate from the index snapshot. Changed live text gets a different source ID even at the same index timestamp. Do not duplicate the body in memory.
diff --git a/docs/1-memory-philosophy.ja.md b/docs/1-memory-philosophy.ja.md
@@ -76,3 +76,7 @@ session boundary は普通に起こる。
 - source-of-truth GitHub artifact の代替
 
 これはそれらの artifact から正しい state を引き戻すための retrieval layer である。
+
+## 非公開 retrieval feedback
+
+[検索 feedback memory](2-feedback-memory.ja.md) は query、返却資料の provenance、明示的 usage/outcome を保存する。会話全体や本文を複製せず、GitHub artifact から recoverable state を取り出す立場を保つ。
diff --git a/docs/1-memory-philosophy.md b/docs/1-memory-philosophy.md
@@ -76,3 +76,7 @@ It is not:
 - a substitute for source-of-truth GitHub artifacts
 
 It is a retrieval layer that helps agents recover the right state from those artifacts.
+
+## Private retrieval feedback
+
+[Retrieval feedback memory](2-feedback-memory.md) records queries, returned source provenance and explicit usage/outcomes. It preserves the recoverable-state stance over GitHub artifacts without duplicating conversations or bodies.