192 lines
11 KiB
Markdown
192 lines
11 KiB
Markdown
---
|
|
title: 'Overview-first extract と evidence 探索を実装する'
|
|
state: 'ready'
|
|
created_at: '2026-07-16T04:34:01Z'
|
|
updated_at: '2026-07-16T14:06:41Z'
|
|
assignee: null
|
|
---
|
|
|
|
## 背景
|
|
|
|
現状の Memory extract は conversation slice を flat Markdown として渡し、extract worker が `decisions` / `discussions` / `attempts` / `requests` を `write_extracted` で返す。tool call 名と tool result summary は含まれるが、User / Assistant の semantic flow と tool evidence が同列に並ぶため、目的・判断・現在地が抜けた断片的な抽出になりやすい。
|
|
|
|
この Ticket では設計だけで止めず、実装として extract 入力を Overview-first に変更し、extract worker が bounded read-only evidence tools で必要箇所を探索できるようにする。extract output は引き続き staging に限定し、Memory / Knowledge / Skill を直接更新しない。
|
|
|
|
関連:
|
|
|
|
- Objective `00001KVJSMQXZ`
|
|
- `.yoi/objectives/00001KVJSMQXZ/memory-architecture-overview.md`
|
|
- Ticket `00001KXMEZNYC` — ターン中のProgress messageを残す指示を追加する
|
|
|
|
## 実装意図
|
|
|
|
この Ticket の目的は、extract worker に「何が起きたか」を flat log から推測させるのではなく、main Worker が残した user-facing transcript を作業の地図として渡し、必要な evidence だけを確認させることである。
|
|
|
|
方針:
|
|
|
|
```text
|
|
User / Assistant messages
|
|
-> Overview: 目的・現在地・判断・未解決点を追う semantic backbone
|
|
|
|
Tool calls / tool results
|
|
-> Evidence index: Overview の claim を確認する根拠への bounded pointer
|
|
|
|
extract worker
|
|
-> Overview を読んで重要そうな候補を見つける
|
|
-> read-only evidence tools で必要範囲だけ確認する
|
|
-> write_extracted で staging payload を出す
|
|
```
|
|
|
|
Progress message は専用 Tool ではなく通常 Assistant Message として残す方針なので、この Ticket では Progress message を新しい item kind として導入しない。extract 側は、committed history 上の User / Assistant messages を信頼できる overview source として扱い、tool evidence はそれを検証・補足するために使う。
|
|
|
|
この変更で目指す改善は recall をむやみに増やすことではない。むしろ、断片的な `attempts` や無用な `discussions` を減らし、source に辿れる候補だけを staging に出す precision 改善を優先する。
|
|
|
|
## 対象領域
|
|
|
|
主な対象は memory extract の入力構築、extract worker の tool surface、staging source 付与である。
|
|
|
|
想定される主な参照先:
|
|
|
|
- `crates/memory/src/extract/input.rs`
|
|
- 現在の flat renderer。
|
|
- Overview-first / Evidence-index-second rendering の中心候補。
|
|
- `crates/memory/src/extract/tool.rs`
|
|
- `write_extracted` 実装。
|
|
- evidence tools を追加する場合は、この module を分割するか、隣接 module に追加する。
|
|
- `crates/memory/src/extract/payload.rs`
|
|
- `ExtractedPayload` / `StagingRecord`。
|
|
- entry-level source anchors が必要なら、互換性を壊さない拡張をここで検討する。
|
|
- `crates/memory/src/extract/staging.rs`
|
|
- staging 書き込み。
|
|
- source anchor の保存形式と関係する。
|
|
- `crates/worker/src/worker.rs`
|
|
- `run_extract_once` / extract worker 起動 / source range 付与 / post-run trigger。
|
|
- extract 専用 ToolRegistry に evidence tools を登録する場所の候補。
|
|
- `resources/prompts/internal/memory_extract_system.md`
|
|
- Overview を first-class input とし、evidence tools を使って根拠確認してから `write_extracted` する指示へ更新する。
|
|
|
|
必要なら周辺 crate / module に小さい helper を追加してよいが、main Worker の通常 tool registry に evidence tools を露出しないこと。
|
|
|
|
## 実装方針
|
|
|
|
### 1. まず Overview / Evidence index を host 側で作る
|
|
|
|
最初の実装では、extract worker に巨大な自由探索をさせない。Worker が渡す conversation range から、host 側で次を組み立てる。
|
|
|
|
- Overview
|
|
- User messages。
|
|
- Assistant messages。
|
|
- Progress message と final response は同じ Assistant message として扱う。
|
|
- System messages は原則 Overview の本文には混ぜない。必要な task context は committed history 由来に限定する。
|
|
- Evidence index
|
|
- tool call id / tool name / entry index。
|
|
- tool result summary / entry index。
|
|
- raw content がある場合も全文は入れず、bounded excerpt または `read_evidence` で読める pointer にする。
|
|
- reasoning は入れない。
|
|
|
|
extract input の top-level は、flat log ではなく次のような形にする。
|
|
|
|
```text
|
|
## Overview
|
|
...User / Assistant messages...
|
|
|
|
## Evidence index
|
|
- E001: ToolCall Read at entry 42
|
|
- E002: ToolResult summary at entry 43
|
|
...
|
|
|
|
## Instructions
|
|
Use Overview as the semantic guide. Use evidence tools only when needed. Call write_extracted once.
|
|
```
|
|
|
|
### 2. Evidence tools は extract slice の中だけを読む
|
|
|
|
初期実装の evidence tools は、まず extract 対象 slice 内に閉じてよい。repository filesystem や Ticket backend を直接探索する必要はない。
|
|
|
|
最低限の tool shape:
|
|
|
|
- `search_evidence`
|
|
- input: query / optional kind / optional limit。
|
|
- output: matching evidence IDs、entry ranges、short summaries。
|
|
- `read_evidence`
|
|
- input: evidence ID または entry range。
|
|
- output: bounded message/tool summary/excerpt。
|
|
- `resolve_source_anchor`
|
|
- input: evidence ID / entry range / tool call id。
|
|
- output: staging に保存できる normalized source anchor。
|
|
|
|
実装上 `resolve_source_anchor` が過剰なら、`search_evidence` / `read_evidence` の output に normalized anchor を含める形でもよい。重要なのは、extract worker が「根拠を読んだふり」をせず、host が解決した anchor を payload / staging に残せること。
|
|
|
|
### 3. Source anchor は段階的に拡張する
|
|
|
|
現状は `StagingRecord` 全体に `source` が付く。これを一気に壊さない。
|
|
|
|
推奨順:
|
|
|
|
1. 既存 `source` は維持する。
|
|
2. `ExtractedPayload` entry に optional な evidence refs / source anchors を追加できるか検討する。
|
|
3. 互換性が難しければ、staging record に `anchors` / `evidence_refs` の sibling field を追加する。
|
|
4. consolidation が未対応でも壊れないよう、unknown/optional field として扱える形にする。
|
|
|
|
entry-level provenance が最終目標だが、この Ticket では少なくとも evidence ID と source range を staging から辿れる状態にする。
|
|
|
|
### 4. Trigger は広げすぎない
|
|
|
|
初期実装では既存 post-run trigger を維持してよい。LLM call ごとの extract はしない。
|
|
|
|
この Ticket の中心は trigger scheduler ではなく、extract の入力品質と evidence 確認である。mid-run trigger や Overview accumulation trigger は、既存 threshold と矛盾しない小さな変更に留める。大きな scheduler 変更が必要なら別 Ticket に分ける。
|
|
|
|
## 実装要件
|
|
|
|
- `build_extract_input` 相当の入力を Overview-first / Evidence-index-second の形に変更する。
|
|
- User messages と通常 Assistant messages を primary Overview として先に提示する。
|
|
- Progress message / final response / user correction / approval を semantic guide として扱う。
|
|
- tool calls / tool results は primary narrative ではなく Evidence index として提示する。
|
|
- reasoning と raw tool result content 全文は引き続き入れない。
|
|
- extract worker 専用の constrained read-only evidence tools を実装する。
|
|
- Evidence search: session slice / message index / tool summaries から候補 range を探す。
|
|
- Evidence read: bounded session entry range、tool call/result summary、許可された bounded excerpt を読む。
|
|
- Source anchor resolver: session id、entry range、tool call id、file path、Ticket/Objective artifact ref などを staging source に結びつける。
|
|
- `write_extracted` は output tool として維持する。
|
|
- evidence tools は extract 専用 worker にだけ登録し、main Worker の model-visible tool surface は増やさない。
|
|
- extract worker は Memory / Knowledge / Skill / Ticket / docs を直接変更しない。
|
|
- extract output は staging に限定する。
|
|
- `ExtractedPayload` の entry と source anchors の結びつけを実装する。
|
|
- 既存の staging record 全体 source だけで足りない場合、互換性を壊さない拡張にする。
|
|
- trigger は LLM call 単位にしない。
|
|
- 初期実装では既存 post-run trigger を維持してよい。
|
|
- Overview accumulation / Evidence growth / Worker run cycle / task boundary に基づく予約が必要なら、既存 threshold と矛盾しない形で導入する。
|
|
- mid-run 発火を入れる場合も staging/checkpoint extraction に限定する。
|
|
- empty / NOP は正常結果として扱う。
|
|
|
|
## 非目標
|
|
|
|
- 専用 Progress Tool を main Worker に追加しない。
|
|
- extract worker に write 権限や durable resource mutation 権限を渡さない。
|
|
- Knowledge / Skill / docs を extract worker が直接 rewrite しない。
|
|
- raw tool result 全文を無制限に extract prompt へ流さない。
|
|
- この Ticket で staging -> Memory disposition / resolution flow まで実装しない。それは Ticket `00001KXMK846H` の対象。
|
|
- この Ticket で大規模な scheduler / mid-run extraction framework を作らない。
|
|
|
|
## 実装順序の目安
|
|
|
|
1. `extract/input.rs` に Overview / Evidence index の renderer を追加し、既存 tests を更新する。
|
|
2. extract 対象 slice から evidence index を作る host-side data structure を追加する。
|
|
3. read-only evidence tools を extract worker context に実装する。
|
|
4. `worker.rs` の extract worker 起動箇所で、`write_extracted` と evidence tools を extract 専用 registry に登録する。
|
|
5. `memory_extract_system.md` を Overview-first / evidence-confirmation 前提に更新する。
|
|
6. source anchor / evidence refs を staging output から辿れる形にする。
|
|
7. tests を追加し、raw tool content が無制限に入らないこと、main Worker tool surface が増えないこと、empty payload が維持されることを確認する。
|
|
|
|
## 受け入れ条件
|
|
|
|
- extract input が Overview-first / Evidence-index-second の形で生成される。
|
|
- extract worker が bounded read-only evidence tools を使って必要箇所を探索できる。
|
|
- main Worker の model-visible tool surface が増えていない。
|
|
- extract output は staging にだけ書かれ、Memory / Knowledge / Skill への direct write がない。
|
|
- source / provenance が機械的に保持され、extract worker が根拠を推測しない実装になっている。
|
|
- 既存の empty payload / no-op path が維持されている。
|
|
- Overview-first rendering、Evidence index、evidence tool bounds、source anchor について unit tests が追加または更新されている。
|
|
- `cargo test -p memory` または該当 crate の同等テストが通る。
|
|
- prompt/resource/code 変更として `nix build .#yoi` が通る。
|