From 1abf56dbc27b0187f330a27909c84ecba377c8ca Mon Sep 17 00:00:00 2001 From: Hare Date: Thu, 16 Jul 2026 08:38:33 +0900 Subject: [PATCH] objective: revise memory knowledge skills architecture --- .../memory-architecture-overview.md | 524 ++++++++++-------- 1 file changed, 284 insertions(+), 240 deletions(-) diff --git a/.yoi/objectives/00001KVJSMQXZ/memory-architecture-overview.md b/.yoi/objectives/00001KVJSMQXZ/memory-architecture-overview.md index 366f9c92..9ce5f5fd 100644 --- a/.yoi/objectives/00001KVJSMQXZ/memory-architecture-overview.md +++ b/.yoi/objectives/00001KVJSMQXZ/memory-architecture-overview.md @@ -1,335 +1,379 @@ --- created_at: "2026-07-15T21:33:00Z" +updated_at: "2026-07-15T21:52:00Z" objective: "00001KVJSMQXZ" status: "architecture-draft" -notes: "Draft architecture for redesigning Yoi Memory as a sensemaking substrate. This is an Objective resource, not implementation authority." +notes: "Draft architecture for redesigning Memory / Knowledge / Skills as distinct workspace resources. This is an Objective resource, not implementation authority." --- -# Memory architecture overview +# Memory / Knowledge / Skills architecture overview ## Position -Yoi Memory should be redesigned as a **sensemaking substrate** rather than a larger persistent note store. The core architecture should help an agent gather task-relevant material, preserve evidence and provenance, build intermediate representations, test hypotheses, and feed outcomes back into Tickets, reviews, docs, Skills, and implementation decisions. +Yoi should treat **Memory**, **Knowledge**, and **Skills** as three distinct resource classes instead of trying to make one generic record store do everything. -This document intentionally assumes the current Memory/Knowledge implementation can be redesigned. Existing `summary` / `decision` / `request` records, extraction, consolidation, resident context, and memory tools are useful historical inputs, but they should not constrain the target model when they conflict with the sensemaking architecture. +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. -## Design constraints +Target split: -- Memory is not project authority. - - Tickets, docs, git history, session logs, explicit user instructions, Workspace records, and typed feature/tool results remain authority. - - Memory provides evidence indexes, working sets, synthesis, reminders, and candidate updates. -- Knowledge is not a separate target record kind. - - Reusable procedures belong in Skills. - - Maintained policies and design rationale belong in docs, Ticket decisions, Objective resources, or explicit Memory decisions depending on authority. -- Workflow tracking is not part of Memory. - - Procedure guidance belongs in Skills / role prompts. - - External state transitions belong in typed feature/tool surfaces. -- Context-only injection is forbidden. - - Any new model-visible memory/shoebox/evidence context must be appended to Worker history or represented through explicit tool results/artifacts. -- Workspace backend should become the shared authority for Memory-related control-plane APIs. - - Local `.yoi/memory` can remain compatibility/offline storage while the architecture is proven. +- **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. -## Reference model +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. -The target architecture follows Pirolli & Card's sensemaking process: +## 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. + +## 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 records may include: + +- 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. + +Memory should be written as 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. + +Memory is useful for resident context and lightweight lookup, but it should not be optimized as a permanent note system. + +#### Memory examples ```text -External data sources - -> task-bound shoebox - -> evidence file - -> schemas / representations - -> hypotheses - -> product - -> product feedback / memory maintenance +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. ``` -Yoi should optimize the loop, not just the final durable storage. +```text +Current focus: web Workspace console and Workspace-backed Ticket/Skill authority. +Source: recent Tickets and Objective updates. +Expected to change after current milestone. +``` -## Core concepts +### Knowledge -### 1. External sources +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. -External sources are authoritative or semi-authoritative material that Memory can point to but should not replace. +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. -Examples: +Knowledge notes should: -- Ticket item/thread/resolution/artifacts. -- Objective item/resources. -- Git commits, diffs, branches, worktrees. -- Session logs and Worker transcripts. -- Docs and reports. -- Code references. -- Runtime/Workspace API records. -- Explicit user messages. -- Existing Memory records. -- Skill metadata and `SKILL.md` content when procedural context matters. +- 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. -External sources should be addressed through source refs, not copied wholesale into Memory. +Knowledge is where long-term architecture notes, conceptual models, subsystem explanations, decision context, recurring constraints, and domain understanding should mature. -### 2. Task-bound shoebox +#### Knowledge examples -A shoebox is a bounded working set of potentially relevant material for a concrete question, Ticket, Objective, review, or design task. +- `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. +- `memory-knowledge-skill-boundary` + - Defines boundaries among Memory, Knowledge, and Skills. + - Links to this architecture resource and future implementation Tickets. +- `ticket-lifecycle-authority` + - Explains Ticket state authority and transition graph rationale. + - Links to relevant decisions and code locations. -Properties: +### Skill -- Scoped to a task/question. -- Contains source refs plus short rationale for inclusion. -- Can include both likely supporting and likely contradicting material. -- Does not assert conclusions. -- Is disposable or artifact-like; it is not necessarily durable memory. +Skill is an established, portable workflow/procedure for a class of tasks. It should follow Agent Skills format: -Example uses: +```text +.yoi/skills// + SKILL.md + scripts/ + references/ + assets/ +``` -- Orchestrator asks for context before routing a queued Ticket. -- Reviewer asks for prior decisions and contradictory evidence for a change. -- Designer asks for relevant reports, tickets, commits, and old memory before writing architecture. +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. -A shoebox is the first concrete slice to prototype because it directly addresses Memory graveyard behavior: information must gather around the current question. +Skills should contain: -### 3. Evidence file +- when to use the Skill; +- step-by-step procedure; +- expected inputs; +- expected outputs/report shape; +- examples; +- edge cases; +- optional references/scripts/assets. -An evidence file extracts snippets or observations from a shoebox. +Skills are portable when they can be moved to another workspace with minimal project-specific assumptions. -Each evidence item should carry: +#### Skill examples -- source ref; -- quoted or summarized snippet; -- source location/anchor if available; -- why it matters; -- supports / refutes / contextualizes relation; -- applicability scope; -- confidence; -- staleness or supersession markers; -- extractor identity/time. +- `coder-review-cycle` + - How a Coder should implement, validate, request review, handle feedback, and produce a dossier. +- `ticket-intake` + - How to turn ambiguous user requests into accepted Ticket requirements. +- `architecture-review` + - How to evaluate design proposals, alternatives, and authority boundaries. -Evidence files are not final decisions. They are structured working material for reasoning. +## Boundaries -### 4. Representation / schema layer +### Memory vs Knowledge -The representation layer reorganizes evidence into forms that reduce reasoning cost. +Memory is provisional and change-oriented. Knowledge is maintained and growth-oriented. -Possible representations: +Use Memory when: -- timeline; -- subsystem map; -- authority boundary map; -- invariant list; -- risk list; -- decision table; -- hypothesis table; -- alternative/rejected alternative table; -- contradiction/staleness report; -- review checklist; -- dependency graph. +- 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. -Representations should be attached to a task or Objective as artifacts/resources before becoming durable Memory records. +Use Knowledge when: -### 5. Hypotheses and alternatives +- 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. -Memory should help track not only final conclusions but also competing interpretations. +Promotion path: -A hypothesis record or artifact should be able to express: +```text +Memory observation -> candidate note/update -> Knowledge note / docs / Ticket decision +``` -- claim; -- supporting evidence; -- contradicting evidence; -- open questions; -- rejected alternatives; -- decision threshold; -- current status: proposed / accepted / rejected / stale / superseded. +Promotion should be explicit. Not every Memory item becomes Knowledge. -This is the main anti-confirmation-bias layer. Reviewer and Orchestrator Skills should explicitly ask agents to seek disconfirming evidence, but the data structure should make that evidence easy to preserve. +### Knowledge vs Docs -### 6. Product feedback +Docs are maintained public/project-facing exposition. Knowledge is internal, linked, evolving understanding. -The loop must end in a product. A memory-driven activity should normally produce or update one of: +A Knowledge note may later become a doc, but the threshold is different: -- Ticket decision/comment/implementation report/review; -- Objective resource; -- design doc/report; -- Skill update; -- code implementation or validation evidence; -- explicit Memory decision/request update; -- stale/superseded marker on old memory. +- Knowledge can contain uncertainty, partial models, and links to evidence. +- Docs should present settled explanations or user/developer guidance. -Memory that is collected but never changes a product should be considered low-value unless it is intentionally kept as a temporary shoebox/evidence artifact. +### Knowledge vs Ticket decisions -## Storage layers +Ticket decisions are authority for work item history and state. Knowledge notes synthesize across Tickets. -### Compatibility layer: current `.yoi/memory` +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. -Keep only the minimum durable Memory record kinds needed during transition: +### Skill vs Knowledge -- summary; -- decision; -- request; -- audit/extraction logs as implementation artifacts. +Knowledge explains what is true or how the project is understood. Skill explains how to do a recurring task. -Do not reintroduce Knowledge as a separate kind. +Use Skill when the artifact should instruct an agent to perform work: -Existing generated Memory can continue to serve as background context, but new architecture should not optimize around resident memory injection first. +- review process; +- implementation process; +- release checklist; +- architecture evaluation method. -### Workspace control-plane layer +Use Knowledge when the artifact should explain a concept: -Target authority should move toward Workspace backend APIs for: +- Workspace authority model; +- Memory architecture; +- Ticket lifecycle rationale. -- memory catalog/search; -- task shoebox creation/list/show; -- evidence file creation/list/show; -- artifact/source refs; +### Skill vs Feature/Plugin + +Skill is prompt/resource guidance. Feature/Plugin is executable authority and 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. + +## Workspace authority + +The target architecture should be Workspace-backed. + +### Memory API + +Workspace backend should eventually provide: + +- Memory list/search/read/write/edit/delete; +- resident memory summary generation or retrieval; - staleness/supersession markers; -- product-impact metrics; -- memory maintenance diagnostics. +- Memory candidate proposal from sessions or artifacts; +- provenance and audit events; +- preference/current-focus surfaces. -This mirrors the direction already chosen for Tickets and Skills: Workers should not maintain divergent local interpretations when `WorkspaceClient::Http` is available. +Local `.yoi/memory` can remain compatibility/offline storage during transition. -### Artifact/resource layer +### Knowledge API -Before inventing new durable schemas, prefer Objective/Ticket resources or artifacts for prototypes: +Workspace backend should provide a proper note API rather than exposing raw filesystem layout as the only interface: + +- 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. + +A filesystem representation may still exist, likely under `.yoi/knowledge/`, but Worker/Runtime/Web/CLI should converge on the Workspace API view when available. + +### Skill API + +Skill support should follow the separate Skill Ticket direction: + +- Workspace backend owns discovery/lint/catalog/activation. +- `.yoi/skills//SKILL.md` is the workspace storage convention. +- Workers use Workspace API for Skill metadata/body when `WorkspaceClient::Http` is available. +- Skill references/assets are accessed through backend-resolved authority or Skill resource APIs. + +## Human-readable growth path + +A core requirement is that useful material can mature into human-readable form. + +Typical paths: ```text -.yoi/objectives//resources/.md -.yoi/tickets//artifacts/.json|md +Session observation + -> Memory record + -> Knowledge note candidate + -> Knowledge note with links/backlinks + -> maintained doc or Ticket decision if it becomes authority ``` -This keeps early experiments inspectable and avoids overfitting storage before the architecture is proven. +```text +Repeated successful procedure + -> Memory observation / Ticket comment + -> draft Skill + -> `.yoi/skills//SKILL.md` + -> builtin or shared Skill if portable +``` -## Runtime/API architecture +```text +Design discussion + -> Objective resource + -> Knowledge note synthesis + -> implementation Tickets + -> docs after stabilization +``` -### Memory service responsibilities +The architecture should make these promotions explicit and reviewable. -A future Workspace Memory service should provide typed operations for: +## Sensemaking as a usage pattern -- `MemorySourceSearch`: find candidate source refs across Tickets, Objectives, docs, sessions, code, reports, and existing Memory. -- `ShoeboxCreate`: create a task-bound working set from query/task/source refs. -- `ShoeboxShow`: render a bounded shoebox for an agent. -- `EvidenceExtract`: extract evidence items from a shoebox or selected source refs. -- `EvidenceShow`: render evidence with provenance and support/refute relations. -- `RepresentationCreate`: create tables/maps/timelines/hypothesis matrices from evidence. -- `MemoryCandidatePropose`: propose durable Memory/doc/Ticket/Skill updates based on artifacts. -- `MemoryImpactRecord`: record when memory/evidence influenced a product. -- `MemoryStalenessMark`: mark records as stale/superseded/contradicted/needs-review. +Sensemaking remains useful, but should be treated as a pattern layered on the resource model. -These should be typed feature/tool surfaces, not hidden prompt injection. +Pirolli & Card's flow can map to Yoi resources as: -### Worker interaction +```text +External sources -> Memory/search/shoebox artifact -> Knowledge notes / Objective resources -> Tickets/docs/Skills/products +``` -Workers should interact with Memory through explicit tools/API results: +But we should not make "shoebox" or "hypothesis matrix" mandatory first-class concepts until actual workflows prove they are needed. -- A Worker asks for a shoebox or evidence file. -- The result is committed as a tool result or artifact reference. -- If the Worker needs additional source material, it explicitly reads/fetches it. -- If a result should influence future work, the Worker writes a Ticket comment, Objective resource, doc update, Skill update, or Memory candidate. +Initial sensemaking support can be lightweight: -Resident context may still include high-signal summary, but it should not be the primary product of the Memory system. +- 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. -### Prompt/context behavior +## Implementation posture -- Shoebox and evidence outputs should be bounded. -- Large source material should remain referenced, not inlined. -- If a generated summary or evidence bundle is used for reasoning, it must be visible in history/tool output/artifact. -- Context should distinguish source quote, extractor summary, and model inference. +The current implementation can be redesigned. Do not preserve old Memory/Knowledge shapes just because they exist. -## Metrics +However, avoid a large-bang rewrite. Split after this architecture is accepted. -Memory metrics should distinguish exposure from impact. +Recommended implementation sequence: -Low-level events: +1. **Clarify current Memory after Knowledge removal** + - Keep short-term/resident Memory working. + - Remove assumptions that Memory must replace Knowledge. -- resident exposure; -- explicit query; -- shoebox created; -- evidence extracted; -- representation created; -- source opened/read; -- stale marker created. +2. **Design target Knowledge note model** + - Markdown note format. + - link/backlink model. + - provenance/staleness metadata. + - Workspace API surface. -Product-impact events: +3. **Implement minimal Knowledge catalog/read/write** + - Start with Markdown files and Workspace API. + - Add lint and backlinks. -- cited in Ticket comment/review/resolution; -- changed implementation plan; -- changed review outcome; -- changed acceptance criteria or requirement; -- caused docs/Skill update; -- invalidated stale assumption; -- avoided duplicate work; -- reduced time-to-evidence. +4. **Implement Skill support separately** + - Follow Agent Skills standard and Workspace authority. + - Do not mix Skill with Knowledge note schema. -The architecture should not treat retrieval count alone as success. +5. **Add promotion workflows/tools** + - Memory -> Knowledge candidate. + - Knowledge -> docs/Ticket decision candidate. + - repeated procedure -> Skill candidate. -## Relationship to Skills +6. **Add sensemaking helpers only after resource classes stabilize** + - collected refs; + - evidence extraction; + - contradiction/staleness views; + - product-impact metrics. -Skills are procedural guidance. They can instruct agents to use Memory tools, ask for disconfirming evidence, or produce a dossier, but they do not own external state. +## Non-goals -Examples: - -- Reviewer Skill says: request contradicting evidence before approving. -- Orchestrator Skill says: create a Ticket shoebox before routing a risky Ticket. -- Coder Skill says: cite relevant prior decisions in the final dossier. - -The Memory service provides the data and artifacts those Skills ask for. - -## Relationship to Tickets/Objectives - -Tickets and Objectives remain the primary durable work-management records. - -- Ticket body/thread/artifacts define work authority and evidence for implementation. -- Objective item/resources define long-running design context. -- Memory can point to them, synthesize across them, and propose updates, but does not replace them. - -A practical rule: if a statement changes what should be built or reviewed, it should appear in Ticket/Objective/docs, not only in Memory. - -## Initial implementation slices - -Do not start by redesigning every Memory record. Split into small Tickets after this architecture is accepted. - -Recommended order: - -1. **Task-bound shoebox artifact prototype** - - Given a Ticket or Objective and a question, collect source refs and short rationales. - - Store as Ticket artifact or Objective resource. - -2. **Evidence file schema prototype** - - Extract snippets from shoebox refs with source/provenance/support-refute metadata. - - Keep as artifact/resource first. - -3. **Contradiction/staleness markers** - - Mark existing Memory decisions or source refs as stale/superseded/contradicted. - - Avoid deleting first; make staleness visible. - -4. **Reviewer/Orchestrator Skill integration** - - Update Skills to ask for shoebox/evidence before risky review/routing. - - This tests whether the architecture changes product quality. - -5. **Workspace Memory API sketch** - - Add read-only catalog/search and shoebox/evidence endpoints once artifact prototypes stabilize. - -6. **Product-impact metrics** - - Record when evidence is cited in Ticket/review/docs and when it changes outcomes. - -## Non-goals for the first redesign - -- Recreating Knowledge under another name. -- Making Memory the canonical source for Ticket requirements or design decisions. -- Automatically rewriting docs/Skills/Tickets from extracted memory without explicit review. -- Building a general vector database before task-bound evidence flows are proven. -- Optimizing resident prompt stuffing before explicit shoebox/evidence usefulness is validated. -- Creating a hidden context channel that bypasses Worker history. +- 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. ## Open decisions -- Whether shoebox/evidence should start as Ticket artifacts, Objective resources, or a new Workspace Memory record type. -- How much session-log search belongs in the first slice. -- Whether source refs need a shared URI scheme across Ticket/Objectives/docs/git/session/code. -- Whether Memory tools live in `worker` feature space first or are exposed only via Workspace backend APIs. -- How to represent confidence/staleness without encouraging false precision. -- What exact product-impact events are worth recording in the first implementation. +- Whether target Knowledge uses `.yoi/knowledge/.md`, nested directories, or an index plus notes. +- Exact frontmatter for Knowledge notes. +- Link syntax and backlink extraction rules. +- How Knowledge note IDs/slugs relate to titles. +- Whether Memory remains local-first or becomes Workspace API-first in the same phase as Knowledge. +- Whether Memory/Knowledge APIs share a crate or are separate domain crates. +- What promotion UI/tool should exist for Memory -> Knowledge. +- How to distinguish personal Memory from workspace Memory. +- How much auto-generation is allowed for Knowledge drafts. -## Exit criteria for this architecture phase +## Exit criteria for architecture phase This architecture is ready to split into Tickets when: -- the core flow `source -> shoebox -> evidence -> representation/hypothesis -> product` is accepted; -- storage boundaries between Memory, Ticket, Objective, docs, and Skills are accepted; -- the first prototype slice is chosen; -- non-goals are accepted so implementation does not re-create Knowledge or Workflow tracking. +- 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.