diff --git a/.yoi/objectives/00001KVJSMQXZ/item.md b/.yoi/objectives/00001KVJSMQXZ/item.md index 770c198e..3607dd94 100644 --- a/.yoi/objectives/00001KVJSMQXZ/item.md +++ b/.yoi/objectives/00001KVJSMQXZ/item.md @@ -2,13 +2,13 @@ title: "効果的な Memory システム設計・検証" state: "active" created_at: "2026-06-20T15:16:00Z" -updated_at: "2026-07-15T21:18:00Z" -linked_tickets: ["00001KSKBPHRG", "00001KT02TCCG", "00001KTGCAFXG", "00001KSKBPTHR"] +updated_at: "2026-07-16T04:38:00Z" +linked_tickets: ["00001KSKBPHRG", "00001KT02TCCG", "00001KTGCAFXG", "00001KSKBPTHR", "00001KXMEZNYC", "00001KXMK7YMC", "00001KXMK846H"] --- ## Goal -Yoi の Memory / generated memory / resident context / retrieval / usage metrics を、実際の開発・設計・レビュー・オーケストレーションに効く sensemaking substrate として再設計・検証する。Knowledge は separate record kind として削除する方針であり、この Objective では Memory と authority record / Skill / docs の境界を再整理する。 +Yoi の Memory / Knowledge / Skills / generated context / resident context / retrieval / usage metrics を、実際の開発・設計・レビュー・オーケストレーションに効く sensemaking substrate として再設計・検証する。Memory は短期・変化前提の context、Knowledge は育てる long-term note、Skill は移植可能な workflow として分け、この Objective ではそれらと authority record / docs / typed tools の境界を再整理する。 この Objective でいう「効果的な Memory システム」は、単に多く保存する仕組みではなく、作業中の問いに対して relevant material を集め、根拠を検証可能にし、再表現・仮説形成・反証探索・意思決定・成果物への反映を低コストにする仕組みである。 @@ -41,7 +41,7 @@ Yoi の現行 Memory は、この流れのうち「保存」と「一部の検 - Ticket / task / question ごとの shoebox がない。 - shoebox から evidence snippets を切り出し、source / provenance / applicability / confidence と共に扱う evidence file がない。 -- `summary`, `decision`, `request` は durable memory storage taxonomy であり、sensemaking 用 schema としては粗い。Knowledge record kind は削除方針なので、再利用可能な手順は Skill、保守された設計資料は docs / Ticket decisions に寄せる。 +- `summary`, `decision`, `request` は durable memory storage taxonomy であり、sensemaking 用 schema としては粗い。Knowledge は古い record kind をそのまま残すのではなく、育てる long-term note subsystem として再設計する。再利用可能な手順は Skill、保守された設計資料は Knowledge / docs / Ticket decisions に寄せる。 - decision は残るが、hypothesis space、alternative、rejected reason、disconfirming evidence が残りにくい。 - reviewer / orchestrator が confirmation bias を避けるための反証探索導線が弱い。関連する手順誘導は旧 Workflow ではなく Skill と role prompt / typed tools へ寄せる。 - resident exposure と explicit retrieval は観測できても、Memory が product に効いたかは測りにくい。 @@ -67,7 +67,16 @@ Memory 墓場化の最初の原因は、保存情報が現在の問いに集ま この段階では大きな永続 schema 追加に飛びつかず、report / Ticket artifact / bounded generated context として検証してよい。 -### 3. Memory を authority にしない +### 3. Session Overview を extract の足場にする + +現在の extract は、tool call / tool result summary を含む flat slice から意味を復元しようとして断片化しやすい。改善方針は、main Worker が通常 Assistant Message として Progress message を残し、user messages + Assistant messages を Session Overview として先に読む形にする。 + +- Progress message は専用 Tool ではなく通常 Message とし、ユーザーへの進捗報告と extract 用 semantic summary を兼ねる。 +- extract worker には専用の read-only evidence tools を渡し、Overview で重要そうに見えた箇所だけ session range / tool summaries / source anchors を探索させる。 +- extract worker は Memory / Knowledge / Skill を直接更新しない。output は必ず staging を挟み、source / provenance を host 側で機械的に保持する。 +- trigger は LLM call 単位ではなく、Overview accumulation、evidence growth、Worker run cycle、task boundary を組み合わせる。mid-run 発火を入れる場合も staging/checkpoint extraction に限定する。 + +### 4. Memory を authority にしない Memory は Ticket、docs、git history、session logs、user instruction の代替ではない。Memory は authority record への evidence index / schema / reasoning aid として扱う。 @@ -78,7 +87,7 @@ Memory は Ticket、docs、git history、session logs、user instruction の代 - Memory の断定をそのまま authority として使わない。 - Ticket body/thread/artifacts を読まずに Objective や Memory だけで実装判断できる状態を作らない。 -### 4. 反証探索を first-class にする +### 5. 反証探索を first-class にする より効果的な Memory は、過去方針を思い出すだけでなく、現在案を疑うために使える必要がある。 @@ -92,7 +101,7 @@ Reviewer / Orchestrator / Intake の導線では、次を探せるようにす - authority boundary risks - prior failures / reports -### 5. Metrics は exposure から product impact へ寄せる +### 6. Metrics は exposure から product impact へ寄せる Memory が prompt に入った、または query されたことは成功ではない。評価は次を区別する。 @@ -105,7 +114,7 @@ Memory が prompt に入った、または query されたことは成功では - contradicted / invalidated - led to docs or decision update -### 6. 後続 Ticket は concrete slice に分割する +### 7. 後続 Ticket は concrete slice に分割する この Objective は中期的な設計・検証の一元化 record であり、umbrella Ticket ではない。実装や調査は、単独で実装・レビュー・close できる concrete Ticket に分割する。 @@ -118,6 +127,10 @@ Memory が prompt に入った、または query されたことは成功では - Reviewer Skill / review process に反証探索を入れる。 - Memory usage metrics を product impact oriented に拡張する。 - stale / contradiction / renewal の検出・表示を設計する。 +- turn 中の Progress message を通常 Assistant Message として残す prompt/guidance を追加する (`00001KXMEZNYC`)。 +- Session Overview + Evidence index を使う extract input を設計・実装する。 +- extract worker 専用の read-only evidence search/read/source-anchor tools を設計する。 +- extract output を staging に限定し、source range と output entry を結びつける schema を設計する。 ## Success criteria / exit conditions @@ -126,6 +139,9 @@ Memory が prompt に入った、または query されたことは成功では - Ticket / Objective / docs / session logs / Memory / Skills の authority boundary が明確で、Memory が authority を僭称せず、Skill は手順資源として外部状態 authority を持たない。 - 少なくとも一つの実作業 routing / review / design analysis で、task-bound shoebox または evidence file が生成・利用され、作業品質にどう効いたかが確認されている。 - Memory records または関連 artifacts が source / provenance / applicability / staleness / supports-or-refutes のいずれかを扱えるようになっている。 +- extract が User / Assistant messages 由来の Session Overview を primary input とし、tool logs を evidence として探索できる設計になっている。 +- extract worker 専用の read-only evidence tools が設計され、main Worker の tool surface を増やさない方針になっている。 +- extract output は direct Memory / Knowledge / Skill write ではなく staging を挟む方針になっている。 - Reviewer / Orchestrator が supporting evidence だけでなく、contradicting evidence / stale assumptions / rejected alternatives を探す導線を持っている。 - Memory usage metrics が resident exposure と product impact を区別している。 - 古い Memory が放置されるのではなく、stale / superseded / contradicted / needs-review として扱える方針がある。 @@ -141,13 +157,14 @@ Memory が prompt に入った、または query されたことは成功では - Memory は durable project authority ではない。Ticket、docs、git history、session logs、明示 user instruction の代替として使わない。 - Objective context は判断背景であり、個別実装の authority は各 Ticket body/thread/artifacts と明示的な Ticket relations / OrchestrationPlan records にある。 - `history` に残らない context-only injection を改善案にしない。新しい context input は history に commit する原則を守る。 -- Knowledge record kind は削除方針。再利用可能な手順・作法は Agent Skills (`.yoi/skills//SKILL.md`) へ、durable policy/rationale は Memory decisions / maintained docs / Ticket decisions へ、外部状態 authority は typed feature/tool surface へ分ける。 +- Knowledge は古い unused record kind をそのまま残すのではなく、育てる long-term Markdown note subsystem として再設計する。再利用可能な手順・作法は Agent Skills (`.yoi/skills//SKILL.md`) へ、durable policy/rationale は Knowledge / maintained docs / Ticket decisions へ、外部状態 authority は typed feature/tool surface へ分ける。 - Generated memory / Ticket / docs / report / Skill の境界を再定義する場合は、authority boundary と migration/staleness を明示する。 - 関連する既存 Ticket: - `00001KSKBPHRG` — Prompt / Workflow 評価メトリクスと改善 Offer - `00001KT02TCCG` — Memory prompt: conditional guidance and proactive lookup - `00001KTGCAFXG` — Use .yoi/memory marker for repo-local memory root - `00001KSKBPTHR` — ワークスペースのメモリーをLintするヘッドレスCLI + - `00001KXMEZNYC` — ターン中のProgress messageを残す指示を追加する ## Historical references / prior design sources @@ -224,7 +241,10 @@ HermesAgent で特に重要だった点: この Objective での再解釈: -- HermesAgent の `MEMORY.md` / `USER.md` / `skills` の分離は、Yoi の Memory / Skills / prompt resources / docs / Ticket decision / generated memory の責務再整理に使える。 +- HermesAgent の `MEMORY.md` / `USER.md` / `skills` の分離は、Yoi の Memory / Knowledge / Skills / prompt resources / docs / Ticket decision / generated memory の責務再整理に使える。 +- Yoi は foreground isolation 自体をすでに持つため、取り入れるべきなのは isolation そのものではなく、Overview を足場にした maintenance / extraction の質改善である。 +- main Worker が通常 Assistant Message として残す Progress message は、人間向け進捗報告と machine-readable session overview を兼ねられる。 +- extract worker は専用 read-only evidence tools で必要箇所だけ探索し、direct write ではなく staging に出力する。 - reusable procedure, reviewer focus, orchestration tactic, project preference, user preference, design invariant を同じ Memory bucket に入れると墓場化しやすい。 - `Nothing to save.` / empty extraction allowed は重要だが、保存抑制だけでは効果的な Memory にはならない。保存されたものが task-bound shoebox / evidence / schema / hypothesis / product に接続される必要がある。 - frozen snapshot / prompt cache 配慮は Yoi の history/context 加工原則と整合するが、それだけでは retrieval / resurfacing / disconfirmation は解決しない。 @@ -242,6 +262,7 @@ Codex と HermesAgent の調査から、Yoi が継承すべきものと、継承 - stale / noisy / unused entries の cleanup。 - procedural memory と declarative memory の分離。 - session search / usage metrics / linter feedback を consolidation に入れる設計。 +- user / Assistant messages から作る Session Overview を semantic guide にし、tool logs を evidence として探索する設計。 足りないもの: diff --git a/.yoi/objectives/00001KVJSMQXZ/memory-architecture-overview.md b/.yoi/objectives/00001KVJSMQXZ/memory-architecture-overview.md index 9ce5f5fd..57c0372e 100644 --- a/.yoi/objectives/00001KVJSMQXZ/memory-architecture-overview.md +++ b/.yoi/objectives/00001KVJSMQXZ/memory-architecture-overview.md @@ -1,73 +1,73 @@ --- created_at: "2026-07-15T21:33:00Z" -updated_at: "2026-07-15T21:52:00Z" +updated_at: "2026-07-16T03:45:00Z" objective: "00001KVJSMQXZ" status: "architecture-draft" -notes: "Draft architecture for redesigning Memory / Knowledge / Skills as distinct workspace resources. This is an Objective resource, not implementation authority." +notes: "Memory / Knowledge / Skills を別々の workspace resource として再設計するための draft architecture。この文書は Objective resource であり、実装 authority ではない。" --- # Memory / Knowledge / Skills architecture overview -## Position +## 立場 -Yoi should treat **Memory**, **Knowledge**, and **Skills** as three distinct resource classes instead of trying to make one generic record store do everything. +Yoi は **Memory**、**Knowledge**、**Skills** を 1 つの汎用 record store に押し込めるのではなく、別々の resource class として扱う。 -The practical architecture is more important than the sensemaking model. Pirolli & Card's sensemaking process remains useful background, but it should not force Yoi into shoebox/evidence/hypothesis infrastructure before the product shape is clear. The first goal is a clear workspace resource model whose outputs are human-readable and can grow over time. +sensemaking model よりも、実際に運用できる architecture の方が重要。Pirolli & Card の sensemaking process は背景知識としては有用だが、product shape が固まる前に shoebox / evidence / hypothesis infrastructure を第一級概念にする必要はない。まず目指すべきなのは、成果物が人間に読める形で成長できる clear な workspace resource model である。 -Target split: +目標の分割: -- **Memory**: short-term facts, preferences, current focus, and in-progress context. It is written with change in mind. -- **Knowledge**: long-term notes meant to be cultivated by humans/agents, cross-linked into a mesh, and readable as durable project understanding. -- **Skill**: portable, established procedural guidance in Agent Skills format, used to perform a class of work. +- **Memory**: 短期 fact、嗜好、現在の focus、進行中の context。変化する前提で書く。 +- **Knowledge**: 長期的に育てる note。人間と agent が改訂し、相互リンクで mesh を形成し、durable project understanding として読めるもの。 +- **Skill**: Agent Skills format に従う、移植可能で確立された手順・workflow。 -This replaces the earlier draft's stronger emphasis on sensemaking artifacts as first-class architecture. Sensemaking remains a usage pattern that can be supported by Memory/Knowledge/Skills, not the central storage taxonomy. +これは、以前の draft にあった sensemaking artifact 中心の見方を置き換える。sensemaking は Memory / Knowledge / Skills の上に乗る usage pattern であり、中心の storage taxonomy ではない。 ## Design goals -- Produce human-readable artifacts that can mature. - - Temporary model summaries are not enough. - - A useful result should be able to grow into a Knowledge note, Skill, Ticket decision, doc, or report. -- Keep volatile and durable material separate. - - Short-term context should not pollute long-term notes. - - Long-term notes should not be overwritten by every session extraction. -- Keep procedures separate from notes. - - A repeated way of doing work should become a Skill, not a Knowledge note. -- Keep authority boundaries explicit. - - Tickets define work authority. - - Docs and Objective resources hold maintained design context. - - Knowledge notes hold cultivated long-term understanding. - - Skills guide execution. - - Memory tracks changing working context and preferences. - - Typed feature/tool surfaces own external state changes. -- Use Workspace backend as the shared authority for resource APIs where possible. - - Workers should not develop divergent local views when `WorkspaceClient::Http` is available. +- 人間が読め、成長できる artifact を作る。 + - 一時的な model summary だけでは足りない。 + - 有用な成果は Knowledge note、Skill、Ticket decision、doc、report に育てられるべき。 +- 揮発的なものと durable なものを分ける。 + - 短期 context が長期 note を汚染しないようにする。 + - 長期 note が session extraction のたびに上書きされないようにする。 +- 手順と note を分ける。 + - 繰り返し使える作業方法は Knowledge note ではなく Skill にする。 +- authority boundary を明示する。 + - Ticket は work authority を定義する。 + - docs と Objective resources は maintained design context を持つ。 + - Knowledge notes は育てる project understanding を持つ。 + - Skills は execution を guide する。 + - Memory は変化する working context と preferences を追跡する。 + - typed feature/tool surfaces が external state changes を所有する。 +- 可能な限り Workspace backend を resource API の共有 authority にする。 + - `WorkspaceClient::Http` が使えるときに、Worker ごとに local view が分岐してはいけない。 ## Resource classes ### Memory -Memory is for volatile, short-to-medium-term material that helps the agent continue work without pretending to be long-term project truth. +Memory は、agent が作業を継続する助けになる volatile / short-to-medium-term な情報を扱う。長期的な project truth のふりはしない。 -Memory records may include: +Memory record に入るもの: -- current focus; -- user preferences; -- working assumptions; -- recent decisions whose authority exists elsewhere; -- in-progress constraints; -- reminders to inspect a Ticket/doc/session again; -- session-derived observations; -- personal/workspace context that is expected to change. +- 現在の focus。 +- user preferences。 +- working assumptions。 +- authority が別にある recent decisions。 +- 進行中の constraints。 +- あとで Ticket / doc / session を再確認するための reminder。 +- session から得た observations。 +- 変化することが前提の personal / workspace context。 -Memory should be written as provisional: +Memory は provisional に書く: -- include when/why it was learned; -- include scope and applicability; -- allow staleness/supersession; -- avoid copying authoritative records verbatim; -- prefer pointers to Tickets/docs/Knowledge notes when possible. +- いつ / なぜ learned したかを書く。 +- scope と applicability を書く。 +- staleness / supersession を許す。 +- authoritative records を verbatim にコピーしない。 +- 可能なら Tickets / docs / Knowledge notes への pointer を優先する。 -Memory is useful for resident context and lightweight lookup, but it should not be optimized as a permanent note system. +Memory は resident context と lightweight lookup には有用だが、permanent note system として最適化しない。 #### Memory examples @@ -86,38 +86,38 @@ Expected to change after current milestone. ### Knowledge -Knowledge is a long-term note system. It is meant to be grown, revised, linked, split, merged, and read by humans. It should form a mesh of project understanding rather than a pile of extracted snippets. +Knowledge は long-term note system。人間と agent が育て、改訂し、link し、split / merge しながら読むもの。抽出 snippet の山ではなく、project understanding の mesh を形成する。 -Target Knowledge is not the old unused Knowledge feature preserved as-is. The legacy implementation can be removed first; the replacement should be designed as a proper workspace note subsystem. +Target Knowledge は、古い未使用の Knowledge feature をそのまま残すものではない。legacy implementation は先に削除してよい。置き換えは proper workspace note subsystem として設計する。 -Knowledge notes should: +Knowledge notes の要件: -- be Markdown-first and human-readable; -- have stable IDs/slugs; -- support bidirectional links/backlinks; -- support tags or typed relations where useful; -- preserve provenance for important claims; -- link to Tickets, Objectives, docs, commits, reports, Skills, and other Knowledge notes; -- support review/staleness/supersession; -- be maintained intentionally, not only generated automatically. +- Markdown-first で人間が読める。 +- stable ID / slug を持つ。 +- bidirectional links / backlinks を support する。 +- 必要なら tags や typed relations を support する。 +- 重要な claim には provenance を残す。 +- Tickets、Objectives、docs、commits、reports、Skills、他 Knowledge notes に link できる。 +- review / staleness / supersession を support する。 +- 自動生成だけに頼らず、意図的に maintain される。 -Knowledge is where long-term architecture notes, conceptual models, subsystem explanations, decision context, recurring constraints, and domain understanding should mature. +Knowledge は、長期 architecture note、conceptual model、subsystem explanation、decision context、recurring constraints、domain understanding を育てる場所である。 #### Knowledge examples - `workspace-authority-model` - - Explains why Workspace backend is authority for Tickets/Skills/Runtime views. - - Links to Ticket backend API design, Skill support ticket, Workspace control plane Objective. + - Workspace backend が Tickets / Skills / Runtime views の authority である理由を説明する。 + - Ticket backend API design、Skill support ticket、Workspace control plane Objective に link する。 - `memory-knowledge-skill-boundary` - - Defines boundaries among Memory, Knowledge, and Skills. - - Links to this architecture resource and future implementation Tickets. + - Memory / Knowledge / Skills の boundary を定義する。 + - この architecture resource と将来の implementation Tickets に link する。 - `ticket-lifecycle-authority` - - Explains Ticket state authority and transition graph rationale. - - Links to relevant decisions and code locations. + - Ticket state authority と transition graph の rationale を説明する。 + - 関連 decisions と code locations に link する。 ### Skill -Skill is an established, portable workflow/procedure for a class of tasks. It should follow Agent Skills format: +Skill は、ある種類の task に対して確立された、portable な workflow / procedure。Agent Skills format に従う。 ```text .yoi/skills// @@ -127,49 +127,49 @@ Skill is an established, portable workflow/procedure for a class of tasks. It sh assets/ ``` -A Skill is not a state machine and does not own external authority. It is prompt/resource guidance that tells the agent how to perform a task using available tools. +Skill は state machine ではなく、external authority も所有しない。agent が available tools を使って task をどう実行するかを示す prompt/resource guidance である。 -Skills should contain: +Skill に含めるもの: -- when to use the Skill; -- step-by-step procedure; -- expected inputs; -- expected outputs/report shape; -- examples; -- edge cases; -- optional references/scripts/assets. +- いつその Skill を使うか。 +- step-by-step procedure。 +- expected inputs。 +- expected outputs / report shape。 +- examples。 +- edge cases。 +- optional references / scripts / assets。 -Skills are portable when they can be moved to another workspace with minimal project-specific assumptions. +Skill は、project-specific assumptions が少なく、別 workspace に移しても使えるとき portable と言える。 #### Skill examples - `coder-review-cycle` - - How a Coder should implement, validate, request review, handle feedback, and produce a dossier. + - Coder が実装、検証、review request、feedback 対応、dossier 作成をどう行うか。 - `ticket-intake` - - How to turn ambiguous user requests into accepted Ticket requirements. + - 曖昧な user request を accepted Ticket requirements に変換する方法。 - `architecture-review` - - How to evaluate design proposals, alternatives, and authority boundaries. + - design proposals、alternatives、authority boundaries を評価する方法。 ## Boundaries ### Memory vs Knowledge -Memory is provisional and change-oriented. Knowledge is maintained and growth-oriented. +Memory は provisional / change-oriented。Knowledge は maintained / growth-oriented。 -Use Memory when: +Memory を使うべきとき: -- the information is short-lived; -- the information is a preference or working assumption; -- the information is useful resident context; -- the right long-term destination is not clear yet. +- 情報が短命。 +- preference や working assumption である。 +- resident context として有用。 +- 長期的な置き場所がまだ明確でない。 -Use Knowledge when: +Knowledge を使うべきとき: -- the information should be read and revised over time; -- the information explains a durable project concept; -- multiple future tasks should link to it; -- the note benefits from backlinks and mesh structure; -- humans should be able to browse it as project understanding. +- 時間をかけて読み直し、改訂するべき情報。 +- durable project concept を説明する情報。 +- 複数の future tasks から link されるべき情報。 +- backlinks / mesh structure が有用な note。 +- 人間が project understanding として browse できるべきもの。 Promotion path: @@ -177,92 +177,94 @@ Promotion path: Memory observation -> candidate note/update -> Knowledge note / docs / Ticket decision ``` -Promotion should be explicit. Not every Memory item becomes Knowledge. +Promotion は明示的に行う。すべての Memory item が Knowledge になるわけではない。 ### Knowledge vs Docs -Docs are maintained public/project-facing exposition. Knowledge is internal, linked, evolving understanding. +Docs は public / project-facing な maintained exposition。Knowledge は internal で、link され、発展する understanding。 -A Knowledge note may later become a doc, but the threshold is different: +Knowledge note は後で doc になり得るが、threshold は違う: -- Knowledge can contain uncertainty, partial models, and links to evidence. -- Docs should present settled explanations or user/developer guidance. +- Knowledge は uncertainty、partial models、evidence links を含められる。 +- Docs は settled explanations または user/developer guidance を提示するべき。 ### Knowledge vs Ticket decisions -Ticket decisions are authority for work item history and state. Knowledge notes synthesize across Tickets. +Ticket decisions は work item history と state の authority。Knowledge notes は複数 Ticket をまたいだ synthesis。 -If a decision changes a Ticket's requirement, state, or acceptance criteria, it must be in the Ticket. Knowledge can link to it and explain the broader pattern. +ある decision が Ticket の requirement、state、acceptance criteria を変えるなら、それは Ticket に記録する。Knowledge はそこに link し、より広い pattern を説明できる。 ### Skill vs Knowledge -Knowledge explains what is true or how the project is understood. Skill explains how to do a recurring task. +Knowledge は「何が true か」「project をどう理解するか」を説明する。Skill は「 recurring task をどう実行するか」を説明する。 -Use Skill when the artifact should instruct an agent to perform work: +Skill を使うべきとき: -- review process; -- implementation process; -- release checklist; -- architecture evaluation method. +- review process。 +- implementation process。 +- release checklist。 +- architecture evaluation method。 -Use Knowledge when the artifact should explain a concept: +Knowledge を使うべきとき: -- Workspace authority model; -- Memory architecture; -- Ticket lifecycle rationale. +- Workspace authority model。 +- Memory architecture。 +- Ticket lifecycle rationale。 ### Skill vs Feature/Plugin -Skill is prompt/resource guidance. Feature/Plugin is executable authority and tool surface. +Skill は prompt/resource guidance。Feature/Plugin は executable authority と tool surface。 -A Skill can say "create a Ticket shoebox before review." The Workspace/Memory feature provides the typed tool/API that actually creates it. +Skill は「何をどう進めるか」を書けるが、Ticket、Workspace、Memory、外部状態を変更する権限そのものは持たない。その権限は Feature/Plugin や typed tool/API が持つ。 + +例: Skill は「review 前に Ticket shoebox を作る」と指示できる。実際に作成する authority は Workspace / Memory feature の typed tool/API が提供する。 ## Workspace authority -The target architecture should be Workspace-backed. +Target architecture は Workspace-backed にする。 ### Memory API -Workspace backend should eventually provide: +Workspace backend が最終的に提供するもの: -- Memory list/search/read/write/edit/delete; -- resident memory summary generation or retrieval; -- staleness/supersession markers; -- Memory candidate proposal from sessions or artifacts; -- provenance and audit events; -- preference/current-focus surfaces. +- Memory list / search / read / write / edit / delete。 +- resident memory summary の生成または取得。 +- staleness / supersession markers。 +- sessions や artifacts からの Memory candidate proposal。 +- provenance と audit events。 +- preference / current-focus surfaces。 -Local `.yoi/memory` can remain compatibility/offline storage during transition. +移行期間中は local `.yoi/memory` を compatibility / offline storage として残してよい。 ### Knowledge API -Workspace backend should provide a proper note API rather than exposing raw filesystem layout as the only interface: +Workspace backend は、raw filesystem layout を唯一の interface にするのではなく、proper note API を提供する。 -- Knowledge catalog/list/search; -- note read/write/edit/delete; -- link/backlink extraction; -- relation/tag metadata; -- staleness/supersession markers; -- note diagnostics/lint; -- source/provenance refs; -- import/export from Markdown files. +- Knowledge catalog / list / search。 +- note read / write / edit / delete。 +- link / backlink extraction。 +- relation / tag metadata。 +- staleness / supersession markers。 +- note diagnostics / lint。 +- source / provenance refs。 +- Markdown files からの import / export。 -A filesystem representation may still exist, likely under `.yoi/knowledge/`, but Worker/Runtime/Web/CLI should converge on the Workspace API view when available. +Filesystem representation は残してよい。おそらく `.yoi/knowledge/` 配下になる。ただし Worker / Runtime / Web / CLI は、利用可能なら Workspace API view に収束する。 ### Skill API -Skill support should follow the separate Skill Ticket direction: +Skill support は separate Skill Ticket の方針に従う。 -- Workspace backend owns discovery/lint/catalog/activation. -- `.yoi/skills//SKILL.md` is the workspace storage convention. -- Workers use Workspace API for Skill metadata/body when `WorkspaceClient::Http` is available. -- Skill references/assets are accessed through backend-resolved authority or Skill resource APIs. +- Workspace backend が discovery / lint / catalog / activation を所有する。 +- `.yoi/skills//SKILL.md` は workspace storage convention。 +- `WorkspaceClient::Http` が使えるとき、Workers は Workspace API から Skill metadata / body を使う。 +- Skill references / assets は backend-resolved authority または Skill resource APIs 経由で access する。 ## Human-readable growth path -A core requirement is that useful material can mature into human-readable form. +中核要件は、有用な material が人間に読める形へ成長できること。 -Typical paths: +典型的な path: ```text Session observation @@ -288,92 +290,268 @@ Design discussion -> docs after stabilization ``` -The architecture should make these promotions explicit and reviewable. +Architecture は、これらの promotion を explicit and reviewable にする。 ## Sensemaking as a usage pattern -Sensemaking remains useful, but should be treated as a pattern layered on the resource model. +Sensemaking は有用だが、resource model の上に重なる pattern として扱う。 -Pirolli & Card's flow can map to Yoi resources as: +Pirolli & Card の flow は Yoi resource にこう mapping できる: ```text External sources -> Memory/search/shoebox artifact -> Knowledge notes / Objective resources -> Tickets/docs/Skills/products ``` -But we should not make "shoebox" or "hypothesis matrix" mandatory first-class concepts until actual workflows prove they are needed. +ただし、実際の workflows が必要性を示すまでは、`shoebox` や `hypothesis matrix` を mandatory first-class concepts にしない。 -Initial sensemaking support can be lightweight: +初期の sensemaking support は lightweight でよい: -- task-bound collected references as Ticket/Objective artifacts; -- evidence summaries with provenance; -- explicit contradictory evidence sections in review Skills; -- Knowledge notes that synthesize recurring patterns. +- Ticket / Objective artifacts としての task-bound collected references。 +- provenance 付き evidence summaries。 +- review Skills における explicit contradictory evidence sections。 +- recurring patterns を synthesize する Knowledge notes。 + +## Extract / review mechanism comparison + +Yoi は foreground 応答生成からの隔離をすでに持っている。次に改善すべきなのは isolation そのものではなく、extract worker が意味のない flat slice から文脈を復元しようとしている点である。 + +Target は、通常 Assistant Message を session overview の backbone とし、extract worker が専用の read-only evidence tools で必要箇所だけ探索し、出力は必ず staging を挟む形にする。 + +```text +Main Worker + -> user-facing Progress / final Assistant messages を history に残す + -> tool calls / tool results は evidence log として残る + -> overview が一定量溜まる、または run/task boundary に到達する + -> extract worker が Overview を読む + -> extract worker が専用 evidence tools で必要範囲だけ探索する + -> write_extracted で structured staging payload を出す + -> consolidation / review が Memory / Knowledge / Skill candidate を扱う +``` + +### Current Yoi pipeline + +現在の Yoi extraction は activity-log pipeline: + +- `build_extract_input` が conversation slice を flat Markdown として render する。 + - user / assistant text は保持する。 + - tool-call names を含める。 + - raw tool-result content ではなく tool-result summaries のみを含める。 + - reasoning は落とす。 +- extract worker の tool は `write_extracted` 1 つだけ。 +- `write_extracted` は `decisions`、`discussions`、`attempts`、`requests` を持つ structured `ExtractedPayload` を 1 件受け取る。 +- LLM は provenance を作らない。Worker が `StagingRecord` を書くときに `source` を機械的に付与する。 +- empty payload は valid で、no-op として扱える。 +- consolidation は後で staging entries、full current Memory records、usage evidence、tidy hints を consume する。 +- consolidation は Memory tools 経由で write し、linter feedback に対応し、record を merge / replace し、outdated / superseded / unused / noisy records を clean up する。 + +この価値は、provenance と audit boundary が clear なこと。特に Knowledge notes、design records、Tickets、docs、その他 durable project understanding に影響し得る material に向いている。 + +弱点は、flat slice だけでは「なぜその tool を使ったのか」「何のための探索だったのか」「どの時点の結論なのか」が抜けやすいこと。extract worker が local な tool summary から意味を推測すると、断片的な attempts や無用な discussions が増えやすい。 + +### HermesAgent / Codex からの再解釈 + +HermesAgent は background review により、conversation snapshot から Memory / Skill update を直接判断する。参考になるのは、maintenance を foreground interaction から隔離し、保存すべきものがなければ NOP にする点である。一方で、direct write-only review は Yoi には強すぎる。staged evidence layer がないと、auditability を失いやすく、one session への overfit や過剰 rewrite が起きやすい。 + +Codex は session / rollout を durable source として扱い、background pipeline が後から claim / extract / consolidate する。参考になるのは、turn-local sidecar そのものではなく、durable source、phase separation、claim/lease/retry/global lock、workspace diff/baseline guard の発想である。 + +Yoi では両者を単純コピーせず、次のように分ける: + +- foreground isolation は既存設計の前提として扱う。 +- main Worker は、人間にも有用な Progress message を通常 Assistant Message として残す。 +- extract worker は、Overview を semantic guide として読み、必要な evidence だけを read-only tool で探索する。 +- extract worker は durable Memory / Knowledge / Skill を直接書かず、必ず staging に structured output を出す。 +- consolidation / review が、staging を Memory update、Knowledge candidate、Skill candidate、Ticket/doc update candidate に整理する。 + +### Overview-first extract + +Overview は、committed history にある user messages と normal Assistant messages から作る。Assistant messages には、最終応答だけでなく、長い作業中の Progress message も含める。 + +Progress message は専用 Tool ではなく通常 Assistant Message とする。Tool surface を増やさず、ユーザーへの進捗報告と extract 用 semantic summary を兼ねるためである。内容は public に見せられる短い作業状態に限る。 + +Overview に含めるもの: + +- user requests / corrections / approvals; +- Assistant progress messages; +- Assistant final responses; +- parent delegation や Ticket context のように、history に commit された task context; +- tool evidence への bounded index。 + +Overview に含めないもの: + +- raw reasoning / chain-of-thought; +- raw tool-result content 全文; +- secret-like data; +- history に commit されていない hidden context injection。 + +### Extract worker evidence tools + +extract worker には専用の constrained evidence tools を渡す。これは main Worker の tool 数を増やすものではなく、extract 専用 worker の read-only surface である。 + +必要な tool category: + +- **Evidence search**: session slice / tool summaries / message index から query で候補 range を探す。 +- **Evidence read**: bounded な session entry range、tool call/result summary、必要なら host が許す bounded content excerpt を読む。 +- **Source anchor resolver**: `session_id`, entry range, tool call id, file path, Ticket/Objective artifact ref などを staging source に結びつける。 +- **write_extracted**: structured payload を 1 回提出する既存 output tool。 + +制約: + +- read-only。file write、Ticket mutation、Memory/Knowledge/Skill direct write は持たせない。 +- bounded output。large tool result は summary / excerpt / pointer に留める。 +- provenance first。extract worker が根拠を推測せず、読んだ evidence range を output と結びつけられるようにする。 +- NOP allowed。Overview を読んで保存価値がなければ empty payload で終わる。 + +### Staging remains mandatory + +extract output は必ず staging を挟む。 + +理由: + +- Progress message は semantic guide であり、authority ではない。 +- extract worker の判断は候補であり、direct Memory / Knowledge / Skill update にしない。 +- staging があることで source range、review、consolidation、stale cleanup、later synthesis を維持できる。 +- Knowledge / Skill / docs のような long-term artifacts は、staging と review / consolidation を経て育てるべき。 + +### Trigger policy + +発火単位は LLM call 単位にしない。LLM call 単位では文脈が薄く、断片的な extraction になりやすい。 + +初期方針: + +- overview token count または Assistant Progress/final message count が一定量を超えたら extract を予約する。 +- tool evidence growth が大きい場合も extract を予約できる。 +- Worker run cycle / task boundary / Ticket phase boundary では extract を試す。 +- long-running 中に mid-run 発火する場合も、direct update ではなく staging/checkpoint extraction に限定する。 + +この trigger は「意味のある overview が溜まったか」と「evidence が失われる前に staging したいか」の両方で判断する。 + +### Target Yoi lanes + +Yoi は 1 つの generic extractor ではなく、maintenance lanes に分ける。 + +1. **Overview-guided extract lane** + - user / Assistant messages から Overview を作る。 + - extract worker が dedicated evidence tools で必要箇所だけ探索する。 + - output は必ず staging。 + - decisions / discussions / attempts / requests に加え、将来の Memory / Knowledge / Skill candidate の材料になる source anchors を残す。 + +2. **Consolidation / tidy lane** + - staging entries、existing Memory、usage evidence、linter feedback、stale/noisy hints を統合する。 + - legacy Knowledge as generated memory 前提を外し、Knowledge は redesigned note subsystem への candidate として扱う。 + +3. **Memory update lane** + - short-term facts、preferences、current focus、stale Memory cleanup を扱う。 + - direct write/edit/delete を許す場合でも、extract worker ではなく別 lane の bounded Memory API と audit event で扱う。 + +4. **Skill / Knowledge candidate lane** + - Skill は recurrence / portability rules で gate する。 + - Knowledge は linked Markdown notes への proposal / candidate とし、自動 direct rewrite を避ける。 + +この lane split により、session は人間にも機械にも追いやすくなり、extract は断片的な tool log ではなく Overview を足場にして evidence を確認できる。Yoi の auditability は staging によって維持する。 ## Implementation posture -The current implementation can be redesigned. Do not preserve old Memory/Knowledge shapes just because they exist. +現在の実装は redesign してよい。既存の Memory / Knowledge shape があるからという理由で残さない。 -However, avoid a large-bang rewrite. Split after this architecture is accepted. +ただし big-bang rewrite は避ける。この architecture が accepted されてから分割する。 Recommended implementation sequence: -1. **Clarify current Memory after Knowledge removal** - - Keep short-term/resident Memory working. - - Remove assumptions that Memory must replace Knowledge. +1. **Knowledge removal 後の current Memory を clarify する** + - short-term / resident Memory を維持する。 + - Memory が Knowledge を代替しなければならない、という前提を外す。 + - legacy `knowledge/*` を generated memory として扱う stale consolidation prompt language を削除する。 -2. **Design target Knowledge note model** - - Markdown note format. - - link/backlink model. - - provenance/staleness metadata. - - Workspace API surface. +2. **Progress message guidance を追加する** + - 長い作業や tool loop の節目で、main Worker が通常 Assistant Message として短い Progress message を残す。 + - 専用 Tool は追加しない。 + - Progress message は public に見せられる作業状態、確認済み事実、判断、未解決点、次の作業に限定する。 -3. **Implement minimal Knowledge catalog/read/write** - - Start with Markdown files and Workspace API. - - Add lint and backlinks. +3. **Overview-first extract input を設計する** + - user messages + Assistant messages を semantic Overview として優先する。 + - tool calls / tool results は Evidence index として分離する。 + - committed history だけから Overview を作り、hidden context injection を避ける。 -4. **Implement Skill support separately** - - Follow Agent Skills standard and Workspace authority. - - Do not mix Skill with Knowledge note schema. +4. **Extract worker 専用 evidence tools を設計する** + - extract worker に read-only Evidence search / Evidence read / Source anchor resolver を渡す。 + - main Worker の tool surface は増やさない。 + - output tool は `write_extracted` を維持し、structured payload を 1 回提出させる。 + - source range と output entry を結びつけられる schema / staging format を設計する。 -5. **Add promotion workflows/tools** - - Memory -> Knowledge candidate. - - Knowledge -> docs/Ticket decision candidate. - - repeated procedure -> Skill candidate. +5. **Staging-first extract を実装する** + - extract worker は direct Memory / Knowledge / Skill write をしない。 + - overview accumulation / evidence growth / run or task boundary で extract を予約する。 + - mid-run 発火を入れる場合も staging/checkpoint extraction に限定する。 -6. **Add sensemaking helpers only after resource classes stabilize** - - collected refs; - - evidence extraction; - - contradiction/staleness views; - - product-impact metrics. +6. **Target Knowledge note model を設計する** + - Markdown note format。 + - link / backlink model。 + - provenance / staleness metadata。 + - Workspace API surface。 + - reviewable Knowledge updates の candidate / staging format。 + +7. **Consolidation / tidy lane を更新する** + - staging entries、existing Memory、usage evidence、linter feedback、stale/noisy hints を統合する。 + - legacy Knowledge as generated memory 前提を外す。 + - Memory update、Knowledge candidate、Skill candidate を分けて扱う。 + +8. **Minimal Knowledge catalog/read/write を実装する** + - Markdown files と Workspace API から始める。 + - lint と backlinks を追加する。 + +9. **Skill support を別に実装する** + - Agent Skills standard と Workspace authority に従う。 + - Skill と Knowledge note schema を混ぜない。 + - automatic Skill modification は recurrence と portability で gate する。 + +10. **Promotion workflows/tools を追加する** + - Memory -> Knowledge candidate。 + - Knowledge -> docs / Ticket decision candidate。 + - repeated procedure -> Skill candidate。 + +11. **Resource classes が安定してから sensemaking helpers を追加する** + - collected refs。 + - evidence extraction。 + - contradiction / staleness views。 + - product-impact metrics。 ## Non-goals -- Treating Memory as the only long-term knowledge store. -- Treating Knowledge as generated memory with a different name. -- Treating Skill as a Workflow tracker or state machine. -- Hiding context injection outside Worker history/tool results. -- Making Knowledge notes authoritative over Tickets/docs/git history. -- Automatically rewriting Knowledge/Skills/docs without review. -- Designing a vector database before the human-readable artifact model is stable. +- Memory を唯一の long-term knowledge store として扱うこと。 +- Knowledge を名前だけ変えた generated memory として扱うこと。 +- Skill を Workflow tracker や state machine として扱うこと。 +- Worker history / tool results の外で context injection を隠すこと。 +- Knowledge notes を Tickets / docs / git history より authoritative にすること。 +- review なしに Knowledge / Skills / docs を自動 rewrite すること。 +- human-readable artifact model が安定する前に vector database を設計すること。 ## Open decisions -- Whether target Knowledge uses `.yoi/knowledge/.md`, nested directories, or an index plus notes. -- Exact frontmatter for Knowledge notes. -- Link syntax and backlink extraction rules. -- How Knowledge note IDs/slugs relate to titles. -- Whether Memory remains local-first or becomes Workspace API-first in the same phase as Knowledge. -- Whether Memory/Knowledge APIs share a crate or are separate domain crates. -- What promotion UI/tool should exist for Memory -> Knowledge. -- How to distinguish personal Memory from workspace Memory. -- How much auto-generation is allowed for Knowledge drafts. +- Target Knowledge は `.yoi/knowledge/.md`、nested directories、index + notes のどれを使うか。 +- Knowledge notes の exact frontmatter。 +- Link syntax と backlink extraction rules。 +- Knowledge note IDs / slugs と titles の関係。 +- Memory は local-first のままにするか、Knowledge と同じ phase で Workspace API-first にするか。 +- Memory / Knowledge APIs は同じ crate にするか、別 domain crates にするか。 +- Memory -> Knowledge の promotion UI/tool をどうするか。 +- personal Memory と workspace Memory をどう区別するか。 +- Knowledge drafts の auto-generation をどこまで許すか。 +- extract worker 専用 evidence tools の exact API: search/read/resolver の引数、上限、source anchor format。 +- Overview trigger を overview token count、Assistant message count、evidence growth、run/task boundary のどれで制御するか。 +- mid-run extract をどこまで許すか。初期は staging/checkpoint extraction に限定する方針。 +- source range と `ExtractedPayload` entries をどう結びつけるか。 +- どの Memory sidecar writes を direct に許し、どれを staged proposals にするか。extract worker 自体は direct write しない。 +- Skill sidecar output は patches/proposals だけから始めるか、low-risk Skill edits を auto-apply してよいか。 +- Memory / Knowledge / Skill Workspace APIs をまたぐ sidecar audit events をどう表現するか。 +- prompt-cache-aware sidecar input で full replay と digest-plus-tail をどう選ぶか。 ## Exit criteria for architecture phase -This architecture is ready to split into Tickets when: +この architecture は、次が満たされたら Tickets に分割できる。 -- the Memory / Knowledge / Skill boundary is accepted; -- target Knowledge as long-term linked notes is accepted; -- Workspace backend authority for Memory/Knowledge/Skills is accepted; -- the first implementation slice is chosen; -- non-goals are accepted so implementation does not recreate old Workflow tracking or old unused Knowledge unchanged. +- Memory / Knowledge / Skill boundary が accepted される。 +- long-term linked notes としての target Knowledge が accepted される。 +- Memory / Knowledge / Skills の Workspace backend authority が accepted される。 +- Overview-first extract、extract worker 専用 evidence tools、staging-first output の方針が accepted される。 +- 最初の implementation slice が選ばれる。 +- non-goals が accepted され、old Workflow tracking や old unused Knowledge をそのまま再作成しないことが確認される。 diff --git a/.yoi/tickets/00001KXMEZNYC/artifacts/.gitkeep b/.yoi/tickets/00001KXMEZNYC/artifacts/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.yoi/tickets/00001KXMEZNYC/item.md b/.yoi/tickets/00001KXMEZNYC/item.md new file mode 100644 index 00000000..eb35f246 --- /dev/null +++ b/.yoi/tickets/00001KXMEZNYC/item.md @@ -0,0 +1,30 @@ +--- +title: 'ターン中のProgress messageを残す指示を追加する' +state: 'ready' +created_at: '2026-07-16T03:19:36Z' +updated_at: '2026-07-16T03:22:00Z' +assignee: null +--- + +## 背景 + +Memory extract が raw tool/result slice から意味を復元しようとすると、目的・判断・現在地が抜けて断片的な抽出になりやすい。専用 Tool を増やすと tool surface が増え、注意分散と token 重複も増える。 + +長い作業の節目で、main Worker がユーザーに見える通常 Assistant Message として短い Progress message を残せれば、人間への進捗報告と後段 extract 用 Overview の semantic backbone を兼ねられる。 + +## 要件 + +- 長い作業、tool loop、調査/実装 phase の節目で、main Worker が短い Progress message を通常 Assistant Message として出すように prompt / guidance を追加または変更する。 +- Progress message は user-facing transcript の一部として成立する内容に限定する。 +- raw reasoning や迷いの垂れ流しではなく、目的、確認済み事実、判断、未解決点、次の作業を簡潔に書く。 +- 専用 Tool は追加しない。 +- tool call ごとではなく、意味のある phase boundary / long-running interval / 重要な確認結果の節目で出す。 +- Memory extract 側は将来的に user messages + assistant messages を Overview として優先し、tool logs は evidence として参照できる設計に接続する。 + +## 受け入れ条件 + +- relevant prompt/resource の指示に、turn 中の Progress message を残す方針が明記されている。 +- Progress message の内容制約が明記されている: public に見せられる短い作業状態、確認済み事実、判断、未解決点、次の作業。chain-of-thought や冗長な tool detail は含めない。 +- 専用 Tool を増やさず、通常 Assistant Message として記録する方針になっている。 +- 既存の最終応答と過剰に重複しない頻度・粒度の guidance がある。 +- prompt/resource 変更として `nix build .#yoi` で packaging を検証する。 diff --git a/.yoi/tickets/00001KXMEZNYC/thread.md b/.yoi/tickets/00001KXMEZNYC/thread.md new file mode 100644 index 00000000..82003977 --- /dev/null +++ b/.yoi/tickets/00001KXMEZNYC/thread.md @@ -0,0 +1,48 @@ + + +## 作成 + +LocalTicketBackend によって作成されました。 + +--- + + + +## Plan + +背景: +Memory extract が raw tool/result slice から意味を復元しようとすると、目的・判断・現在地が抜けて断片的な抽出になりやすい。専用 Tool を増やすと tool surface が増え、注意分散と token 重複が増えるため、ユーザーに見える通常 Assistant Message を progress / checkpoint として活用し、人間にも機械にも追いやすい transcript を作る。 + +要件: +- 長い作業・tool loop・調査/実装 phase の節目で、main Worker が短い Progress message を通常 Assistant Message として出すように prompt / guidance を追加または変更する。 +- Progress message は user-facing transcript の一部として成立する内容に限定する。raw reasoning や迷いの垂れ流しではなく、目的、確認済み事実、判断、未解決点、次の作業を簡潔に書く。 +- 専用 Tool は追加しない。Progress message はユーザーへの進捗報告と、後段 extract 用 Overview の semantic backbone を兼ねる。 +- tool call ごとではなく、意味のある phase boundary / long-running interval / 重要な確認結果の節目で出す。 +- Memory extract 側は将来的に user messages + assistant messages を Overview として優先し、tool logs は evidence として参照できる設計に接続する。 + +受け入れ条件: +- relevant prompt/resource の指示に、turn 中の Progress message を残す方針が明記されている。 +- Progress message の内容制約が明記されている: public に見せられる短い作業状態、確認済み事実、判断、未解決点、次の作業。chain-of-thought や冗長な tool detail は含めない。 +- 専用 Tool を増やさず、通常 Assistant Message として記録する方針になっている。 +- 既存の最終応答と過剰に重複しない頻度・粒度の guidance がある。 +- prompt/resource 変更として `nix build .#yoi` で packaging を検証する。 + + +--- + + + +## Intake summary + +Marked ready by `yoi ticket state`. + +--- + + + +## State changed + +Marked ready by `yoi ticket state`. + + +--- diff --git a/.yoi/tickets/00001KXMK7YMC/artifacts/.gitkeep b/.yoi/tickets/00001KXMK7YMC/artifacts/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.yoi/tickets/00001KXMK7YMC/item.md b/.yoi/tickets/00001KXMK7YMC/item.md new file mode 100644 index 00000000..713e259d --- /dev/null +++ b/.yoi/tickets/00001KXMK7YMC/item.md @@ -0,0 +1,191 @@ +--- +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` が通る。 diff --git a/.yoi/tickets/00001KXMK7YMC/thread.md b/.yoi/tickets/00001KXMK7YMC/thread.md new file mode 100644 index 00000000..8373038a --- /dev/null +++ b/.yoi/tickets/00001KXMK7YMC/thread.md @@ -0,0 +1,42 @@ + + +## 作成 + +LocalTicketBackend によって作成されました。 + +--- + + + +## Intake summary + +Marked ready by `yoi ticket state`. + +--- + + + +## State changed + +Marked ready by `yoi ticket state`. + + +--- + + + +## Decision + +ユーザー指示により、設計で止める Ticket ではなく実装 Ticket として再スコープした。Overview-first extract / evidence tools は実装要件に変更し、staging 審査・剪定も resolution/disposition の実装まで含める。 + + +--- + + + +## Decision + +実装者が対象領域と意図を追いやすいように、実装意図、対象 module、実装方針、想定順序を item.md に追記した。特に `extract/input.rs`、`extract/tool.rs`、`extract/payload.rs`、`extract/staging.rs`、`worker.rs`、`memory_extract_system.md` を主な対象として明示し、初期 evidence tools は extract slice 内の bounded read-only search/read/anchor 解決に閉じる方針を示した。 + + +--- diff --git a/.yoi/tickets/00001KXMK846H/artifacts/.gitkeep b/.yoi/tickets/00001KXMK846H/artifacts/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.yoi/tickets/00001KXMK846H/item.md b/.yoi/tickets/00001KXMK846H/item.md new file mode 100644 index 00000000..7c1a1151 --- /dev/null +++ b/.yoi/tickets/00001KXMK846H/item.md @@ -0,0 +1,73 @@ +--- +title: 'StagingからMemory化する審査・剪定フローを実装する' +state: 'ready' +created_at: '2026-07-16T04:34:07Z' +updated_at: '2026-07-16T04:38:21Z' +assignee: null +--- + +## 背景 + +現状の staging は extract output の一時保存としては機能しているが、Memory 化前の審査キューとしての情報が弱い。consolidation が成功すると consumed staging は削除されるため、どの staging entry を Memory 化したか、何を捨てたか、なぜ捨てたか、何を Knowledge / Skill candidate に送るべきだったかが machine-readable に残りにくい。 + +この Ticket では設計だけで止めず、staging entry の resolution / disposition を実装し、consolidation が staging から Memory 化する際の審査・剪定結果を残せるようにする。Memory は短期・変化前提の context であり、staging から無制限に append しない。 + +関連: + +- Objective `00001KVJSMQXZ` +- `.yoi/objectives/00001KVJSMQXZ/memory-architecture-overview.md` +- `.yoi/objectives/00001KVJSMQXZ/resources/pirolli-card-2005-sensemaking.md` + +## 実装要件 + +- staging entry ごとの resolution / disposition 記録を実装する。 + - 初期実装は append-only JSONL などの軽量な形式でよい。 + - consumed staging を削除する場合も、削除前に resolution を残す。 + - invalid staging / failed consolidation は既存挙動を壊さず、可能なら diagnostic resolution を残す。 +- disposition action を machine-readable にする。 + - 最低限: `discard` / `merge_memory` / `replace_memory` / `mark_memory_stale` / `delete_memory` / `defer` / `promote_to_knowledge_candidate` / `promote_to_skill_candidate` / `link_to_authority` / `create_ticket_or_doc_candidate`。 + - 初期実装で全 action を実際に mutate できない場合も、resolution として記録できるようにする。 +- consolidation prompt / input / output flow を更新し、staging entry ごとの disposition を要求する。 + - discard reason / defer reason / target record / consolidation run id / consumed_by を記録する。 + - record mutation がない場合でも、なぜ Memory 化しなかったかを resolution に残せるようにする。 +- Memory 化条件を prompt と実装上の記録に反映する。 + - future usefulness reason。 + - scope / applicability。 + - source anchors。 + - staleness condition / invalidation condition。 + - なぜ Knowledge / Skill / Ticket / docs ではなく Memory なのか。 + - authoritative records の単なる mirror ではないこと。 +- staging からの destination routing を resolution に記録する。 + - Memory。 + - Knowledge candidate。 + - Skill candidate。 + - Ticket/doc candidate。 + - authority link only。 + - discard / defer。 +- consolidation / tidy を garden operation として強める。 + - append より merge / replace / mark stale / delete を優先する guidance を prompt に入れる。 + - stale / duplicate / no-scope / no-product-use / authority-duplicate / contradictory records を検出する tidy hints を追加できる範囲で実装する。 +- Pirolli & Card の sensemaking flow を implementation note / prompt に反映する。 + - shoebox: Overview + Evidence index + selected candidate ranges。 + - evidence file: source anchors 付き staging entries。 + - schemas/hypotheses: Memory 化すべきか、Knowledge/Skill に送るべきか、stale かの判断。 + - product: Memory update / Knowledge candidate / Skill candidate / Ticket/doc update / discard resolution。 + +## 非目標 + +- staging を長期 Knowledge store にしない。 +- staging entry を全て Memory 化しない。 +- Memory を Ticket / docs / git / session log の mirror にしない。 +- 初期 slice で完全な vector DB や大規模 search infrastructure を実装しない。 + +## 受け入れ条件 + +- consolidation 実行後、staging entry ごとの disposition / resolution が durable に残る。 +- consumed staging を削除する前に resolution が記録される。 +- `discard` / `merge_memory` / `replace_memory` / `mark_memory_stale` / `delete_memory` / `defer` / `promote_to_knowledge_candidate` / `promote_to_skill_candidate` / `link_to_authority` / `create_ticket_or_doc_candidate` の少なくとも記録表現がある。 +- Memory 化には usefulness / scope / source / staleness / destination reason が求められる。 +- Knowledge / Skill / Ticket / docs への routing と、Memory に入れない重要 material の扱いが resolution として表現できる。 +- resolution log / archive は staging cleanup と競合せず、consolidation lock / consumed snapshot の既存安全性を壊さない。 +- resolution write、consumed cleanup、discard/defer path、no-record-change path の tests が追加または更新されている。 +- `cargo test -p memory` または該当 crate の同等テストが通る。 +- code/prompt/resource 変更として `nix build .#yoi` が通る。 diff --git a/.yoi/tickets/00001KXMK846H/thread.md b/.yoi/tickets/00001KXMK846H/thread.md new file mode 100644 index 00000000..be4fe414 --- /dev/null +++ b/.yoi/tickets/00001KXMK846H/thread.md @@ -0,0 +1,33 @@ + + +## 作成 + +LocalTicketBackend によって作成されました。 + +--- + + + +## Intake summary + +Marked ready by `yoi ticket state`. + +--- + + + +## State changed + +Marked ready by `yoi ticket state`. + + +--- + + + +## Decision + +ユーザー指示により、設計で止める Ticket ではなく実装 Ticket として再スコープした。Overview-first extract / evidence tools は実装要件に変更し、staging 審査・剪定も resolution/disposition の実装まで含める。 + + +---