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

ticket: plan memory extract improvements

Browse Source
This commit is contained in:
Hare
2026-07-17 00:50:43 +09:00
parent 1abf56dbc2
commit 8163c54a44
11 changed files with 815 additions and 199 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.yoi/objectives/00001KVJSMQXZ/memory-architecture-overview.md
+367 -189
View File
@@ -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/<skill-name>/
@@ -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>/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>/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/<slug>.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/<slug>.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 をそのまま再作成しないことが確認される。