Hare/yoi

ticket: plan memory extract improvements

2026-07-17 00:50:43 +09:00

28 KiB

Raw Blame History

created_at	updated_at	objective	status	notes
2026-07-15T21:33:00Z	2026-07-16T03:45:00Z	00001KVJSMQXZ	architecture-draft	Memory / Knowledge / Skills を別々の workspace resource として再設計するための draft architecture。この文書は Objective resource であり、実装 authority ではない。

Memory / Knowledge / Skills architecture overview

立場

Yoi は Memory、Knowledge、Skills を 1 つの汎用 record store に押し込めるのではなく、別々の resource class として扱う。

sensemaking model よりも、実際に運用できる architecture の方が重要。Pirolli & Card の sensemaking process は背景知識としては有用だが、product shape が固まる前に shoebox / evidence / hypothesis infrastructure を第一級概念にする必要はない。まず目指すべきなのは、成果物が人間に読める形で成長できる clear な workspace resource model である。

目標の分割:

Memory: 短期 fact、嗜好、現在の focus、進行中の context。変化する前提で書く。
Knowledge: 長期的に育てる note。人間と agent が改訂し、相互リンクで mesh を形成し、durable project understanding として読めるもの。
Skill: Agent Skills format に従う、移植可能で確立された手順・workflow。

これは、以前の draft にあった sensemaking artifact 中心の見方を置き換える。sensemaking は Memory / Knowledge / Skills の上に乗る usage pattern であり、中心の storage taxonomy ではない。

Design goals

人間が読め、成長できる 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 は、agent が作業を継続する助けになる volatile / short-to-medium-term な情報を扱う。長期的な project truth のふりはしない。

Memory record に入るもの:

現在の focus。
user preferences。
working assumptions。
authority が別にある recent decisions。
進行中の constraints。
あとで Ticket / doc / session を再確認するための reminder。
session から得た observations。
変化することが前提の personal / workspace context。

Memory は provisional に書く:

いつ / なぜ learned したかを書く。
scope と applicability を書く。
staleness / supersession を許す。
authoritative records を verbatim にコピーしない。
可能なら Tickets / docs / Knowledge notes への pointer を優先する。

Memory は resident context と lightweight lookup には有用だが、permanent note system として最適化しない。

Memory examples

User preference: prefers direct commits only when explicitly requested.
Scope: this repository / current dogfooding workflow.
Source: repeated user corrections in sessions around git operations.
Staleness: revisit if user changes repo workflow.

Current focus: web Workspace console and Workspace-backed Ticket/Skill authority.
Source: recent Tickets and Objective updates.
Expected to change after current milestone.

Knowledge

Knowledge は long-term note system。人間と agent が育て、改訂し、link し、split / merge しながら読むもの。抽出 snippet の山ではなく、project understanding の mesh を形成する。

Target Knowledge は、古い未使用の Knowledge feature をそのまま残すものではない。legacy implementation は先に削除してよい。置き換えは proper workspace note subsystem として設計する。

Knowledge notes の要件:

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 は、長期 architecture note、conceptual model、subsystem explanation、decision context、recurring constraints、domain understanding を育てる場所である。

Knowledge examples

workspace-authority-model
- Workspace backend が Tickets / Skills / Runtime views の authority である理由を説明する。
- Ticket backend API design、Skill support ticket、Workspace control plane Objective に link する。
memory-knowledge-skill-boundary
- Memory / Knowledge / Skills の boundary を定義する。
- この architecture resource と将来の implementation Tickets に link する。
ticket-lifecycle-authority
- Ticket state authority と transition graph の rationale を説明する。
- 関連 decisions と code locations に link する。

Skill

Skill は、ある種類の task に対して確立された、portable な workflow / procedure。Agent Skills format に従う。

.yoi/skills/<skill-name>/
  SKILL.md
  scripts/
  references/
  assets/

Skill は state machine ではなく、external authority も所有しない。agent が available tools を使って task をどう実行するかを示す prompt/resource guidance である。

Skill に含めるもの:

いつその Skill を使うか。
step-by-step procedure。
expected inputs。
expected outputs / report shape。
examples。
edge cases。
optional references / scripts / assets。

Skill は、project-specific assumptions が少なく、別 workspace に移しても使えるとき portable と言える。

Skill examples

coder-review-cycle
- Coder が実装、検証、review request、feedback 対応、dossier 作成をどう行うか。
ticket-intake
- 曖昧な user request を accepted Ticket requirements に変換する方法。
architecture-review
- design proposals、alternatives、authority boundaries を評価する方法。

Boundaries

Memory vs Knowledge

Memory は provisional / change-oriented。Knowledge は maintained / growth-oriented。

Memory を使うべきとき:

情報が短命。
preference や working assumption である。
resident context として有用。
長期的な置き場所がまだ明確でない。

Knowledge を使うべきとき:

時間をかけて読み直し、改訂するべき情報。
durable project concept を説明する情報。
複数の future tasks から link されるべき情報。
backlinks / mesh structure が有用な note。
人間が project understanding として browse できるべきもの。

Promotion path:

Memory observation -> candidate note/update -> Knowledge note / docs / Ticket decision

Promotion は明示的に行う。すべての Memory item が Knowledge になるわけではない。

Knowledge vs Docs

Docs は public / project-facing な maintained exposition。Knowledge は internal で、link され、発展する understanding。

Knowledge note は後で doc になり得るが、threshold は違う:

Knowledge は uncertainty、partial models、evidence links を含められる。
Docs は settled explanations または user/developer guidance を提示するべき。

Knowledge vs Ticket decisions

Ticket decisions は work item history と state の authority。Knowledge notes は複数 Ticket をまたいだ synthesis。

ある decision が Ticket の requirement、state、acceptance criteria を変えるなら、それは Ticket に記録する。Knowledge はそこに link し、より広い pattern を説明できる。

Skill vs Knowledge

Knowledge は「何が true か」「project をどう理解するか」を説明する。Skill は「 recurring task をどう実行するか」を説明する。

Skill を使うべきとき:

review process。
implementation process。
release checklist。
architecture evaluation method。

Knowledge を使うべきとき:

Workspace authority model。
Memory architecture。
Ticket lifecycle rationale。

Skill vs Feature/Plugin

Skill は prompt/resource guidance。Feature/Plugin は executable authority と tool surface。

Skill は「何をどう進めるか」を書けるが、Ticket、Workspace、Memory、外部状態を変更する権限そのものは持たない。その権限は Feature/Plugin や typed tool/API が持つ。

例: Skill は「review 前に Ticket shoebox を作る」と指示できる。実際に作成する authority は Workspace / Memory feature の typed tool/API が提供する。

Workspace authority

Target architecture は Workspace-backed にする。

Memory API

Workspace backend が最終的に提供するもの:

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 を compatibility / offline storage として残してよい。

Knowledge API

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。
Markdown files からの import / export。

Filesystem representation は残してよい。おそらく .yoi/knowledge/ 配下になる。ただし Worker / Runtime / Web / CLI は、利用可能なら Workspace API view に収束する。

Skill API

Skill support は separate Skill Ticket の方針に従う。

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

中核要件は、有用な material が人間に読める形へ成長できること。

典型的な path:

Session observation
  -> Memory record
  -> Knowledge note candidate
  -> Knowledge note with links/backlinks
  -> maintained doc or Ticket decision if it becomes authority

Repeated successful procedure
  -> Memory observation / Ticket comment
  -> draft Skill
  -> `.yoi/skills/<skill>/SKILL.md`
  -> builtin or shared Skill if portable

Design discussion
  -> Objective resource
  -> Knowledge note synthesis
  -> implementation Tickets
  -> docs after stabilization

Architecture は、これらの promotion を explicit and reviewable にする。

Sensemaking as a usage pattern

Sensemaking は有用だが、resource model の上に重なる pattern として扱う。

Pirolli & Card の flow は Yoi resource にこう mapping できる:

External sources -> Memory/search/shoebox artifact -> Knowledge notes / Objective resources -> Tickets/docs/Skills/products

ただし、実際の workflows が必要性を示すまでは、shoebox や hypothesis matrix を mandatory first-class concepts にしない。

初期の sensemaking support は lightweight でよい:

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 を挟む形にする。

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 に分ける。

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 を残す。
Consolidation / tidy lane
- staging entries、existing Memory、usage evidence、linter feedback、stale/noisy hints を統合する。
- legacy Knowledge as generated memory 前提を外し、Knowledge は redesigned note subsystem への candidate として扱う。
Memory update lane
- short-term facts、preferences、current focus、stale Memory cleanup を扱う。
- direct write/edit/delete を許す場合でも、extract worker ではなく別 lane の bounded Memory API と audit event で扱う。
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

現在の実装は redesign してよい。既存の Memory / Knowledge shape があるからという理由で残さない。

ただし big-bang rewrite は避ける。この architecture が accepted されてから分割する。

Recommended implementation sequence:

Knowledge removal 後の current Memory を clarify する
- short-term / resident Memory を維持する。
- Memory が Knowledge を代替しなければならない、という前提を外す。
- legacy knowledge/* を generated memory として扱う stale consolidation prompt language を削除する。
Progress message guidance を追加する
- 長い作業や tool loop の節目で、main Worker が通常 Assistant Message として短い Progress message を残す。
- 専用 Tool は追加しない。
- Progress message は public に見せられる作業状態、確認済み事実、判断、未解決点、次の作業に限定する。
Overview-first extract input を設計する
- user messages + Assistant messages を semantic Overview として優先する。
- tool calls / tool results は Evidence index として分離する。
- committed history だけから Overview を作り、hidden context injection を避ける。
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 を設計する。
Staging-first extract を実装する
- extract worker は direct Memory / Knowledge / Skill write をしない。
- overview accumulation / evidence growth / run or task boundary で extract を予約する。
- mid-run 発火を入れる場合も staging/checkpoint extraction に限定する。
Target Knowledge note model を設計する
- Markdown note format。
- link / backlink model。
- provenance / staleness metadata。
- Workspace API surface。
- reviewable Knowledge updates の candidate / staging format。
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 を分けて扱う。
Minimal Knowledge catalog/read/write を実装する
- Markdown files と Workspace API から始める。
- lint と backlinks を追加する。
Skill support を別に実装する
- Agent Skills standard と Workspace authority に従う。
- Skill と Knowledge note schema を混ぜない。
- automatic Skill modification は recurrence と portability で gate する。
Promotion workflows/tools を追加する
- Memory -> Knowledge candidate。
- Knowledge -> docs / Ticket decision candidate。
- repeated procedure -> Skill candidate。
Resource classes が安定してから sensemaking helpers を追加する
- collected refs。
- evidence extraction。
- contradiction / staleness views。
- product-impact metrics。

Non-goals

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

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

この architecture は、次が満たされたら Tickets に分割できる。

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 をそのまま再作成しないことが確認される。

28 KiB Raw Blame History