Hare/yoi
1
1
Fork 0
Code Actions Packages Releases Activity

ticket: plan memory extract improvements

Browse Source
This commit is contained in:
Keisuke Hirata 2026-07-17 00:50:43 +09:00
parent 1abf56dbc2
commit 8163c54a44
No known key found for this signature in database
11 changed files with 815 additions and 199 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
.yoi/objectives/00001KVJSMQXZ/item.md
View File

@ -2,13 +2,13 @@
title: "効果的な Memory システム設計・検証" title: "効果的な Memory システム設計・検証"
state: "active" state: "active"
created_at: "2026-06-20T15:16:00Z" created_at: "2026-06-20T15:16:00Z"
updated_at: "2026-07-15T21:18:00Z" updated_at: "2026-07-16T04:38:00Z"
linked_tickets: ["00001KSKBPHRG", "00001KT02TCCG", "00001KTGCAFXG", "00001KSKBPTHR"] linked_tickets: ["00001KSKBPHRG", "00001KT02TCCG", "00001KTGCAFXG", "00001KSKBPTHR", "00001KXMEZNYC", "00001KXMK7YMC", "00001KXMK846H"]
--- ---
## Goal ## 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 を集め、根拠を検証可能にし、再表現・仮説形成・反証探索・意思決定・成果物への反映を低コストにする仕組みである。 この Objective でいう「効果的な Memory システム」は、単に多く保存する仕組みではなく、作業中の問いに対して relevant material を集め、根拠を検証可能にし、再表現・仮説形成・反証探索・意思決定・成果物への反映を低コストにする仕組みである。
@ -41,7 +41,7 @@ Yoi の現行 Memory は、この流れのうち「保存」と「一部の検
- Ticket / task / question ごとの shoebox がない。 - Ticket / task / question ごとの shoebox がない。
- shoebox から evidence snippets を切り出し、source / provenance / applicability / confidence と共に扱う evidence file がない。 - 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 が残りにくい。 - decision は残るが、hypothesis space、alternative、rejected reason、disconfirming evidence が残りにくい。
- reviewer / orchestrator が confirmation bias を避けるための反証探索導線が弱い。関連する手順誘導は旧 Workflow ではなく Skill と role prompt / typed tools へ寄せる。 - reviewer / orchestrator が confirmation bias を避けるための反証探索導線が弱い。関連する手順誘導は旧 Workflow ではなく Skill と role prompt / typed tools へ寄せる。
- resident exposure と explicit retrieval は観測できても、Memory が product に効いたかは測りにくい。 - resident exposure と explicit retrieval は観測できても、Memory が product に効いたかは測りにくい。
@ -67,7 +67,16 @@ Memory 墓場化の最初の原因は、保存情報が現在の問いに集ま
この段階では大きな永続 schema 追加に飛びつかず、report / Ticket artifact / bounded generated context として検証してよい。 この段階では大きな永続 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 として扱う。 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 として使わない。 - Memory の断定をそのまま authority として使わない。
- Ticket body/thread/artifacts を読まずに Objective や Memory だけで実装判断できる状態を作らない。 - Ticket body/thread/artifacts を読まずに Objective や Memory だけで実装判断できる状態を作らない。
### 4. 反証探索を first-class にする ### 5. 反証探索を first-class にする
より効果的な Memory は、過去方針を思い出すだけでなく、現在案を疑うために使える必要がある。 より効果的な Memory は、過去方針を思い出すだけでなく、現在案を疑うために使える必要がある。
@ -92,7 +101,7 @@ Reviewer / Orchestrator / Intake の導線では、次を探せるようにす
- authority boundary risks - authority boundary risks
- prior failures / reports - prior failures / reports
### 5. Metrics は exposure から product impact へ寄せる ### 6. Metrics は exposure から product impact へ寄せる
Memory が prompt に入った、または query されたことは成功ではない。評価は次を区別する。 Memory が prompt に入った、または query されたことは成功ではない。評価は次を区別する。
@ -105,7 +114,7 @@ Memory が prompt に入った、または query されたことは成功では
- contradicted / invalidated - contradicted / invalidated
- led to docs or decision update - led to docs or decision update
### 6. 後続 Ticket は concrete slice に分割する ### 7. 後続 Ticket は concrete slice に分割する
この Objective は中期的な設計・検証の一元化 record であり、umbrella Ticket ではない。実装や調査は、単独で実装・レビュー・close できる concrete Ticket に分割する。 この Objective は中期的な設計・検証の一元化 record であり、umbrella Ticket ではない。実装や調査は、単独で実装・レビュー・close できる concrete Ticket に分割する。
@ -118,6 +127,10 @@ Memory が prompt に入った、または query されたことは成功では
- Reviewer Skill / review process に反証探索を入れる。 - Reviewer Skill / review process に反証探索を入れる。
- Memory usage metrics を product impact oriented に拡張する。 - Memory usage metrics を product impact oriented に拡張する。
- stale / contradiction / renewal の検出・表示を設計する。 - 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 ## Success criteria / exit conditions
@ -126,6 +139,9 @@ Memory が prompt に入った、または query されたことは成功では
- Ticket / Objective / docs / session logs / Memory / Skills の authority boundary が明確で、Memory が authority を僭称せず、Skill は手順資源として外部状態 authority を持たない。 - Ticket / Objective / docs / session logs / Memory / Skills の authority boundary が明確で、Memory が authority を僭称せず、Skill は手順資源として外部状態 authority を持たない。
- 少なくとも一つの実作業 routing / review / design analysis で、task-bound shoebox または evidence file が生成・利用され、作業品質にどう効いたかが確認されている。 - 少なくとも一つの実作業 routing / review / design analysis で、task-bound shoebox または evidence file が生成・利用され、作業品質にどう効いたかが確認されている。
- Memory records または関連 artifacts が source / provenance / applicability / staleness / supports-or-refutes のいずれかを扱えるようになっている。 - 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 を探す導線を持っている。 - Reviewer / Orchestrator が supporting evidence だけでなく、contradicting evidence / stale assumptions / rejected alternatives を探す導線を持っている。
- Memory usage metrics が resident exposure と product impact を区別している。 - Memory usage metrics が resident exposure と product impact を区別している。
- 古い Memory が放置されるのではなく、stale / superseded / contradicted / needs-review として扱える方針がある。 - 古い 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 の代替として使わない。 - Memory は durable project authority ではない。Ticket、docs、git history、session logs、明示 user instruction の代替として使わない。
- Objective context は判断背景であり、個別実装の authority は各 Ticket body/thread/artifacts と明示的な Ticket relations / OrchestrationPlan records にある。 - Objective context は判断背景であり、個別実装の authority は各 Ticket body/thread/artifacts と明示的な Ticket relations / OrchestrationPlan records にある。
- `history` に残らない context-only injection を改善案にしない。新しい context input は history に commit する原則を守る。 - `history` に残らない context-only injection を改善案にしない。新しい context input は history に commit する原則を守る。
- Knowledge record kind は削除方針。再利用可能な手順・作法は Agent Skills (`.yoi/skills/<skill>/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>/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 を明示する。 - Generated memory / Ticket / docs / report / Skill の境界を再定義する場合は、authority boundary と migration/staleness を明示する。
- 関連する既存 Ticket: - 関連する既存 Ticket:
- `00001KSKBPHRG` — Prompt / Workflow 評価メトリクスと改善 Offer - `00001KSKBPHRG` — Prompt / Workflow 評価メトリクスと改善 Offer
- `00001KT02TCCG` — Memory prompt: conditional guidance and proactive lookup - `00001KT02TCCG` — Memory prompt: conditional guidance and proactive lookup
- `00001KTGCAFXG` — Use .yoi/memory marker for repo-local memory root - `00001KTGCAFXG` — Use .yoi/memory marker for repo-local memory root
- `00001KSKBPTHR` — ワークスペースのメモリーをLintするヘッドレスCLI - `00001KSKBPTHR` — ワークスペースのメモリーをLintするヘッドレスCLI
- `00001KXMEZNYC` — ターン中のProgress messageを残す指示を追加する
## Historical references / prior design sources ## Historical references / prior design sources
@ -224,7 +241,10 @@ HermesAgent で特に重要だった点:
この Objective での再解釈: この 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 に入れると墓場化しやすい。 - 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 に接続される必要がある。 - `Nothing to save.` / empty extraction allowed は重要だが、保存抑制だけでは効果的な Memory にはならない。保存されたものが task-bound shoebox / evidence / schema / hypothesis / product に接続される必要がある。
- frozen snapshot / prompt cache 配慮は Yoi の history/context 加工原則と整合するが、それだけでは retrieval / resurfacing / disconfirmation は解決しない。 - frozen snapshot / prompt cache 配慮は Yoi の history/context 加工原則と整合するが、それだけでは retrieval / resurfacing / disconfirmation は解決しない。
@ -242,6 +262,7 @@ Codex と HermesAgent の調査から、Yoi が継承すべきものと、継承
- stale / noisy / unused entries の cleanup。 - stale / noisy / unused entries の cleanup。
- procedural memory と declarative memory の分離。 - procedural memory と declarative memory の分離。
- session search / usage metrics / linter feedback を consolidation に入れる設計。 - session search / usage metrics / linter feedback を consolidation に入れる設計。
- user / Assistant messages から作る Session Overview を semantic guide にし、tool logs を evidence として探索する設計。
足りないもの: 足りないもの:

556
.yoi/objectives/00001KVJSMQXZ/memory-architecture-overview.md
View File

@ -1,73 +1,73 @@
--- ---
created_at: "2026-07-15T21:33:00Z" created_at: "2026-07-15T21:33:00Z"
updated_at: "2026-07-15T21:52:00Z" updated_at: "2026-07-16T03:45:00Z"
objective: "00001KVJSMQXZ" objective: "00001KVJSMQXZ"
status: "architecture-draft" 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 # 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. - **Memory**: 短期 fact、嗜好、現在の focus、進行中の context。変化する前提で書く。
- **Knowledge**: long-term notes meant to be cultivated by humans/agents, cross-linked into a mesh, and readable as durable project understanding. - **Knowledge**: 長期的に育てる note。人間と agent が改訂し、相互リンクで mesh を形成し、durable project understanding として読めるもの。
- **Skill**: portable, established procedural guidance in Agent Skills format, used to perform a class of work. - **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 ## Design goals
- Produce human-readable artifacts that can mature. - 人間が読め、成長できる artifact を作る。
- Temporary model summaries are not enough. - 一時的な model summary だけでは足りない。
- A useful result should be able to grow into a Knowledge note, Skill, Ticket decision, doc, or report. - 有用な成果は Knowledge note、Skill、Ticket decision、doc、report に育てられるべき。
- Keep volatile and durable material separate. - 揮発的なものと durable なものを分ける。
- Short-term context should not pollute long-term notes. - 短期 context が長期 note を汚染しないようにする。
- Long-term notes should not be overwritten by every session extraction. - 長期 note が session extraction のたびに上書きされないようにする。
- Keep procedures separate from notes. - 手順と note を分ける。
- A repeated way of doing work should become a Skill, not a Knowledge note. - 繰り返し使える作業方法は Knowledge note ではなく Skill にする。
- Keep authority boundaries explicit. - authority boundary を明示する。
- Tickets define work authority. - Ticket は work authority を定義する。
- Docs and Objective resources hold maintained design context. - docs と Objective resources は maintained design context を持つ。
- Knowledge notes hold cultivated long-term understanding. - Knowledge notes は育てる project understanding を持つ。
- Skills guide execution. - Skills は execution を guide する。
- Memory tracks changing working context and preferences. - Memory は変化する working context と preferences を追跡する。
- Typed feature/tool surfaces own external state changes. - typed feature/tool surfaces が external state changes を所有する。
- Use Workspace backend as the shared authority for resource APIs where possible. - 可能な限り Workspace backend を resource API の共有 authority にする。
- Workers should not develop divergent local views when `WorkspaceClient::Http` is available. - `WorkspaceClient::Http` が使えるときに、Worker ごとに local view が分岐してはいけない。
## Resource classes ## Resource classes
### Memory ### 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; - 現在の focus。
- user preferences; - user preferences。
- working assumptions; - working assumptions。
- recent decisions whose authority exists elsewhere; - authority が別にある recent decisions。
- in-progress constraints; - 進行中の constraints。
- reminders to inspect a Ticket/doc/session again; - あとで Ticket / doc / session を再確認するための reminder。
- session-derived observations; - session から得た observations。
- personal/workspace context that is expected to change. - 変化することが前提の personal / workspace context。
Memory should be written as provisional: Memory は provisional に書く:
- include when/why it was learned; - いつ / なぜ learned したかを書く。
- include scope and applicability; - scope と applicability を書く。
- allow staleness/supersession; - staleness / supersession を許す。
- avoid copying authoritative records verbatim; - authoritative records を verbatim にコピーしない。
- prefer pointers to Tickets/docs/Knowledge notes when possible. - 可能なら 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 #### Memory examples
@ -86,38 +86,38 @@ Expected to change after current milestone.
### Knowledge ### 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; - Markdown-first で人間が読める。
- have stable IDs/slugs; - stable ID / slug を持つ。
- support bidirectional links/backlinks; - bidirectional links / backlinks を support する。
- support tags or typed relations where useful; - 必要なら tags や typed relations を support する。
- preserve provenance for important claims; - 重要な claim には provenance を残す。
- link to Tickets, Objectives, docs, commits, reports, Skills, and other Knowledge notes; - Tickets、Objectives、docs、commits、reports、Skills、他 Knowledge notes に link できる。
- support review/staleness/supersession; - review / staleness / supersession を support する。
- be maintained intentionally, not only generated automatically. - 自動生成だけに頼らず、意図的に 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 #### Knowledge examples
- `workspace-authority-model` - `workspace-authority-model`
- Explains why Workspace backend is authority for Tickets/Skills/Runtime views. - Workspace backend が Tickets / Skills / Runtime views の authority である理由を説明する。
- Links to Ticket backend API design, Skill support ticket, Workspace control plane Objective. - Ticket backend API design、Skill support ticket、Workspace control plane Objective に link する。
- `memory-knowledge-skill-boundary` - `memory-knowledge-skill-boundary`
- Defines boundaries among Memory, Knowledge, and Skills. - Memory / Knowledge / Skills の boundary を定義する。
- Links to this architecture resource and future implementation Tickets. - この architecture resource と将来の implementation Tickets に link する。
- `ticket-lifecycle-authority` - `ticket-lifecycle-authority`
- Explains Ticket state authority and transition graph rationale. - Ticket state authority と transition graph の rationale を説明する。
- Links to relevant decisions and code locations. - 関連 decisions と code locations に link する。
### Skill ### 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 ```text
.yoi/skills/<skill-name>/ .yoi/skills/<skill-name>/
@ -127,49 +127,49 @@ Skill is an established, portable workflow/procedure for a class of tasks. It sh
assets/ 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; - いつその Skill を使うか。
- step-by-step procedure; - step-by-step procedure。
- expected inputs; - expected inputs。
- expected outputs/report shape; - expected outputs / report shape。
- examples; - examples。
- edge cases; - edge cases。
- optional references/scripts/assets. - 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 #### Skill examples
- `coder-review-cycle` - `coder-review-cycle`
- How a Coder should implement, validate, request review, handle feedback, and produce a dossier. - Coder が実装、検証、review request、feedback 対応、dossier 作成をどう行うか。
- `ticket-intake` - `ticket-intake`
- How to turn ambiguous user requests into accepted Ticket requirements. - 曖昧な user request を accepted Ticket requirements に変換する方法。
- `architecture-review` - `architecture-review`
- How to evaluate design proposals, alternatives, and authority boundaries. - design proposals、alternatives、authority boundaries を評価する方法。
## Boundaries ## Boundaries
### Memory vs Knowledge ### 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; - preference や working assumption である。
- the information is useful resident context; - resident context として有用。
- the right long-term destination is not clear yet. - 長期的な置き場所がまだ明確でない。
Use Knowledge when: Knowledge を使うべきとき:
- the information should be read and revised over time; - 時間をかけて読み直し、改訂するべき情報。
- the information explains a durable project concept; - durable project concept を説明する情報。
- multiple future tasks should link to it; - 複数の future tasks から link されるべき情報。
- the note benefits from backlinks and mesh structure; - backlinks / mesh structure が有用な note。
- humans should be able to browse it as project understanding. - 人間が project understanding として browse できるべきもの。
Promotion path: Promotion path:
@ -177,92 +177,94 @@ Promotion path:
Memory observation -> candidate note/update -> Knowledge note / docs / Ticket decision 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 ### 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. - Knowledge は uncertainty、partial models、evidence links を含められる。
- Docs should present settled explanations or user/developer guidance. - Docs は settled explanations または user/developer guidance を提示するべき。
### Knowledge vs Ticket decisions ### 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 ### 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; - review process。
- implementation process; - implementation process。
- release checklist; - release checklist。
- architecture evaluation method. - architecture evaluation method。
Use Knowledge when the artifact should explain a concept: Knowledge を使うべきとき:
- Workspace authority model; - Workspace authority model。
- Memory architecture; - Memory architecture。
- Ticket lifecycle rationale. - Ticket lifecycle rationale。
### Skill vs Feature/Plugin ### 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 ## Workspace authority
The target architecture should be Workspace-backed. Target architecture は Workspace-backed にする。
### Memory API ### Memory API
Workspace backend should eventually provide: Workspace backend が最終的に提供するもの:
- Memory list/search/read/write/edit/delete; - Memory list / search / read / write / edit / delete。
- resident memory summary generation or retrieval; - resident memory summary の生成または取得。
- staleness/supersession markers; - staleness / supersession markers。
- Memory candidate proposal from sessions or artifacts; - sessions や artifacts からの Memory candidate proposal。
- provenance and audit events; - provenance と audit events。
- preference/current-focus surfaces. - preference / current-focus surfaces。
Local `.yoi/memory` can remain compatibility/offline storage during transition. 移行期間中は local `.yoi/memory` を compatibility / offline storage として残してよい。
### Knowledge API ### 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; - Knowledge catalog / list / search。
- note read/write/edit/delete; - note read / write / edit / delete。
- link/backlink extraction; - link / backlink extraction。
- relation/tag metadata; - relation / tag metadata。
- staleness/supersession markers; - staleness / supersession markers。
- note diagnostics/lint; - note diagnostics / lint。
- source/provenance refs; - source / provenance refs。
- import/export from Markdown files. - 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 API
Skill support should follow the separate Skill Ticket direction: Skill support は separate Skill Ticket の方針に従う。
- Workspace backend owns discovery/lint/catalog/activation. - Workspace backend が discovery / lint / catalog / activation を所有する。
- `.yoi/skills/<skill>/SKILL.md` is the workspace storage convention. - `.yoi/skills/<skill>/SKILL.md` は workspace storage convention。
- Workers use Workspace API for Skill metadata/body when `WorkspaceClient::Http` is available. - `WorkspaceClient::Http` が使えるとき、Workers は Workspace API から Skill metadata / body を使う。
- Skill references/assets are accessed through backend-resolved authority or Skill resource APIs. - Skill references / assets は backend-resolved authority または Skill resource APIs 経由で access する。
## Human-readable growth path ## Human-readable growth path
A core requirement is that useful material can mature into human-readable form. 中核要件は、有用な material が人間に読める形へ成長できること。
Typical paths: 典型的な path:
```text ```text
Session observation Session observation
@ -288,92 +290,268 @@ Design discussion
-> docs after stabilization -> docs after stabilization
``` ```
The architecture should make these promotions explicit and reviewable. Architecture は、これらの promotion を explicit and reviewable にする。
## Sensemaking as a usage pattern ## 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 ```text
External sources -> Memory/search/shoebox artifact -> Knowledge notes / Objective resources -> Tickets/docs/Skills/products 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; - Ticket / Objective artifacts としての task-bound collected references。
- evidence summaries with provenance; - provenance 付き evidence summaries。
- explicit contradictory evidence sections in review Skills; - review Skills における explicit contradictory evidence sections。
- Knowledge notes that synthesize recurring patterns. - 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 ## 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: Recommended implementation sequence:
1. **Clarify current Memory after Knowledge removal** 1. **Knowledge removal 後の current Memory を clarify する**
- Keep short-term/resident Memory working. - short-term / resident Memory を維持する。
- Remove assumptions that Memory must replace Knowledge. - Memory が Knowledge を代替しなければならない、という前提を外す。
- legacy `knowledge/*` を generated memory として扱う stale consolidation prompt language を削除する。
2. **Design target Knowledge note model** 2. **Progress message guidance を追加する**
- Markdown note format. - 長い作業や tool loop の節目で、main Worker が通常 Assistant Message として短い Progress message を残す。
- link/backlink model. - 専用 Tool は追加しない。
- provenance/staleness metadata. - Progress message は public に見せられる作業状態、確認済み事実、判断、未解決点、次の作業に限定する。
- Workspace API surface.
3. **Implement minimal Knowledge catalog/read/write** 3. **Overview-first extract input を設計する**
- Start with Markdown files and Workspace API. - user messages + Assistant messages を semantic Overview として優先する。
- Add lint and backlinks. - tool calls / tool results は Evidence index として分離する。
- committed history だけから Overview を作り、hidden context injection を避ける。
4. **Implement Skill support separately** 4. **Extract worker 専用 evidence tools を設計する**
- Follow Agent Skills standard and Workspace authority. - extract worker に read-only Evidence search / Evidence read / Source anchor resolver を渡す。
- Do not mix Skill with Knowledge note schema. - main Worker の tool surface は増やさない。
- output tool は `write_extracted` を維持し、structured payload を 1 回提出させる。
- source range と output entry を結びつけられる schema / staging format を設計する。
5. **Add promotion workflows/tools** 5. **Staging-first extract を実装する**
- Memory -> Knowledge candidate. - extract worker は direct Memory / Knowledge / Skill write をしない。
- Knowledge -> docs/Ticket decision candidate. - overview accumulation / evidence growth / run or task boundary で extract を予約する。
- repeated procedure -> Skill candidate. - mid-run 発火を入れる場合も staging/checkpoint extraction に限定する。
6. **Add sensemaking helpers only after resource classes stabilize** 6. **Target Knowledge note model を設計する**
- collected refs; - Markdown note format。
- evidence extraction; - link / backlink model。
- contradiction/staleness views; - provenance / staleness metadata。
- product-impact metrics. - 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 ## Non-goals
- Treating Memory as the only long-term knowledge store. - Memory を唯一の long-term knowledge store として扱うこと。
- Treating Knowledge as generated memory with a different name. - Knowledge を名前だけ変えた generated memory として扱うこと。
- Treating Skill as a Workflow tracker or state machine. - Skill を Workflow tracker や state machine として扱うこと。
- Hiding context injection outside Worker history/tool results. - Worker history / tool results の外で context injection を隠すこと。
- Making Knowledge notes authoritative over Tickets/docs/git history. - Knowledge notes を Tickets / docs / git history より authoritative にすること。
- Automatically rewriting Knowledge/Skills/docs without review. - review なしに Knowledge / Skills / docs を自動 rewrite すること。
- Designing a vector database before the human-readable artifact model is stable. - human-readable artifact model が安定する前に vector database を設計すること。
## Open decisions ## Open decisions
- Whether target Knowledge uses `.yoi/knowledge/<slug>.md`, nested directories, or an index plus notes. - Target Knowledge は `.yoi/knowledge/<slug>.md`、nested directories、index + notes のどれを使うか。
- Exact frontmatter for Knowledge notes. - Knowledge notes の exact frontmatter。
- Link syntax and backlink extraction rules. - Link syntax と backlink extraction rules。
- How Knowledge note IDs/slugs relate to titles. - Knowledge note IDs / slugs と titles の関係。
- Whether Memory remains local-first or becomes Workspace API-first in the same phase as Knowledge. - Memory は local-first のままにするか、Knowledge と同じ phase で Workspace API-first にするか。
- Whether Memory/Knowledge APIs share a crate or are separate domain crates. - Memory / Knowledge APIs は同じ crate にするか、別 domain crates にするか。
- What promotion UI/tool should exist for Memory -> Knowledge. - Memory -> Knowledge の promotion UI/tool をどうするか。
- How to distinguish personal Memory from workspace Memory. - personal Memory と workspace Memory をどう区別するか。
- How much auto-generation is allowed for Knowledge drafts. - 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 ## Exit criteria for architecture phase
This architecture is ready to split into Tickets when: この architecture は、次が満たされたら Tickets に分割できる。
- the Memory / Knowledge / Skill boundary is accepted; - Memory / Knowledge / Skill boundary が accepted される。
- target Knowledge as long-term linked notes is accepted; - long-term linked notes としての target Knowledge が accepted される。
- Workspace backend authority for Memory/Knowledge/Skills is accepted; - Memory / Knowledge / Skills の Workspace backend authority が accepted される。
- the first implementation slice is chosen; - Overview-first extract、extract worker 専用 evidence tools、staging-first output の方針が accepted される。
- non-goals are accepted so implementation does not recreate old Workflow tracking or old unused Knowledge unchanged. - 最初の implementation slice が選ばれる。
- non-goals が accepted され、old Workflow tracking や old unused Knowledge をそのまま再作成しないことが確認される。

0
.yoi/tickets/00001KXMEZNYC/artifacts/.gitkeep Normal file
View File

30
.yoi/tickets/00001KXMEZNYC/item.md Normal file
View File

@ -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 を検証する。

48
.yoi/tickets/00001KXMEZNYC/thread.md Normal file
View File

@ -0,0 +1,48 @@
<!-- event: create author: "yoi ticket" at: 2026-07-16T03:19:36Z -->
## 作成
LocalTicketBackend によって作成されました。
---
<!-- event: plan author: hare at: 2026-07-16T03:19:50Z -->
## 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 を検証する。
---
<!-- event: intake_summary author: hare at: 2026-07-16T03:19:54Z -->
## Intake summary
Marked ready by `yoi ticket state`.
---
<!-- event: state_changed author: "yoi ticket" at: 2026-07-16T03:19:54Z from: planning to: ready reason: cli_state field: state -->
## State changed
Marked ready by `yoi ticket state`.
---

0
.yoi/tickets/00001KXMK7YMC/artifacts/.gitkeep Normal file
View File

191
.yoi/tickets/00001KXMK7YMC/item.md Normal file
View File

@ -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` が通る。

42
.yoi/tickets/00001KXMK7YMC/thread.md Normal file
View File

@ -0,0 +1,42 @@
<!-- event: create author: "yoi ticket" at: 2026-07-16T04:34:01Z -->
## 作成
LocalTicketBackend によって作成されました。
---
<!-- event: intake_summary author: hare at: 2026-07-16T04:35:41Z -->
## Intake summary
Marked ready by `yoi ticket state`.
---
<!-- event: state_changed author: "yoi ticket" at: 2026-07-16T04:35:41Z from: planning to: ready reason: cli_state field: state -->
## State changed
Marked ready by `yoi ticket state`.
---
<!-- event: decision author: hare at: 2026-07-16T04:38:21Z -->
## Decision
ユーザー指示により、設計で止める Ticket ではなく実装 Ticket として再スコープした。Overview-first extract / evidence tools は実装要件に変更し、staging 審査・剪定も resolution/disposition の実装まで含める。
---
<!-- event: decision author: hare at: 2026-07-16T14:06:41Z -->
## 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 解決に閉じる方針を示した。
---

0
.yoi/tickets/00001KXMK846H/artifacts/.gitkeep Normal file
View File

73
.yoi/tickets/00001KXMK846H/item.md Normal file
View File

@ -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` が通る。

33
.yoi/tickets/00001KXMK846H/thread.md Normal file
View File

@ -0,0 +1,33 @@
<!-- event: create author: "yoi ticket" at: 2026-07-16T04:34:07Z -->
## 作成
LocalTicketBackend によって作成されました。
---
<!-- event: intake_summary author: hare at: 2026-07-16T04:35:41Z -->
## Intake summary
Marked ready by `yoi ticket state`.
---
<!-- event: state_changed author: "yoi ticket" at: 2026-07-16T04:35:41Z from: planning to: ready reason: cli_state field: state -->
## State changed
Marked ready by `yoi ticket state`.
---
<!-- event: decision author: hare at: 2026-07-16T04:38:21Z -->
## Decision
ユーザー指示により、設計で止める Ticket ではなく実装 Ticket として再スコープした。Overview-first extract / evidence tools は実装要件に変更し、staging 審査・剪定も resolution/disposition の実装まで含める。
---