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

objective: revise memory knowledge skills architecture

Browse Source
This commit is contained in:
Keisuke Hirata 2026-07-16 08:38:33 +09:00
parent 9e0f8e9aad
commit 1abf56dbc2
No known key found for this signature in database
1 changed files with 284 additions and 240 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,335 +1,379 @@
--- ---
created_at: "2026-07-15T21:33:00Z" created_at: "2026-07-15T21:33:00Z"
updated_at: "2026-07-15T21:52:00Z"
objective: "00001KVJSMQXZ" objective: "00001KVJSMQXZ"
status: "architecture-draft" 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 ## 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. - **Memory**: short-term facts, preferences, current focus, and in-progress context. It is written with change in mind.
- Tickets, docs, git history, session logs, explicit user instructions, Workspace records, and typed feature/tool results remain authority. - **Knowledge**: long-term notes meant to be cultivated by humans/agents, cross-linked into a mesh, and readable as durable project understanding.
- Memory provides evidence indexes, working sets, synthesis, reminders, and candidate updates. - **Skill**: portable, established procedural guidance in Agent Skills format, used to perform a class of work.
- 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.
## 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 ```text
External data sources User preference: prefers direct commits only when explicitly requested.
-> task-bound shoebox Scope: this repository / current dogfooding workflow.
-> evidence file Source: repeated user corrections in sessions around git operations.
-> schemas / representations Staleness: revisit if user changes repo workflow.
-> hypotheses
-> product
-> product feedback / memory maintenance
``` ```
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. - be Markdown-first and human-readable;
- Objective item/resources. - have stable IDs/slugs;
- Git commits, diffs, branches, worktrees. - support bidirectional links/backlinks;
- Session logs and Worker transcripts. - support tags or typed relations where useful;
- Docs and reports. - preserve provenance for important claims;
- Code references. - link to Tickets, Objectives, docs, commits, reports, Skills, and other Knowledge notes;
- Runtime/Workspace API records. - support review/staleness/supersession;
- Explicit user messages. - be maintained intentionally, not only generated automatically.
- Existing Memory records.
- Skill metadata and `SKILL.md` content when procedural context matters.
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. Skill is an established, portable workflow/procedure for a class of tasks. It should follow Agent Skills format:
- 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.
Example uses: ```text
.yoi/skills/<skill-name>/
SKILL.md
scripts/
references/
assets/
```
- Orchestrator asks for context before routing a queued Ticket. 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.
- 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 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; - `coder-review-cycle`
- quoted or summarized snippet; - How a Coder should implement, validate, request review, handle feedback, and produce a dossier.
- source location/anchor if available; - `ticket-intake`
- why it matters; - How to turn ambiguous user requests into accepted Ticket requirements.
- supports / refutes / contextualizes relation; - `architecture-review`
- applicability scope; - How to evaluate design proposals, alternatives, and authority boundaries.
- confidence;
- staleness or supersession markers;
- extractor identity/time.
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; - the information is short-lived;
- subsystem map; - the information is a preference or working assumption;
- authority boundary map; - the information is useful resident context;
- invariant list; - the right long-term destination is not clear yet.
- risk list;
- decision table;
- hypothesis table;
- alternative/rejected alternative table;
- contradiction/staleness report;
- review checklist;
- dependency graph.
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; Promotion should be explicit. Not every Memory item becomes Knowledge.
- supporting evidence;
- contradicting evidence;
- open questions;
- rejected alternatives;
- decision threshold;
- current status: proposed / accepted / rejected / stale / superseded.
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; - Knowledge can contain uncertainty, partial models, and links to evidence.
- Objective resource; - Docs should present settled explanations or user/developer guidance.
- design doc/report;
- Skill update;
- code implementation or validation evidence;
- explicit Memory decision/request update;
- stale/superseded marker on old memory.
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; Knowledge explains what is true or how the project is understood. Skill explains how to do a recurring task.
- decision;
- request;
- audit/extraction logs as implementation artifacts.
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; ### Skill vs Feature/Plugin
- task shoebox creation/list/show;
- evidence file creation/list/show; Skill is prompt/resource guidance. Feature/Plugin is executable authority and tool surface.
- artifact/source refs;
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; - staleness/supersession markers;
- product-impact metrics; - Memory candidate proposal from sessions or artifacts;
- memory maintenance diagnostics. - 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>/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 ```text
.yoi/objectives/<objective-id>/resources/<name>.md Session observation
.yoi/tickets/<ticket-id>/artifacts/<name>.json|md -> 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>/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. Sensemaking remains useful, but should be treated as a pattern layered on the resource model.
- `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.
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. Initial sensemaking support can be lightweight:
- 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.
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. The current implementation can be redesigned. Do not preserve old Memory/Knowledge shapes just because they exist.
- 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.
## 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; 2. **Design target Knowledge note model**
- explicit query; - Markdown note format.
- shoebox created; - link/backlink model.
- evidence extracted; - provenance/staleness metadata.
- representation created; - Workspace API surface.
- source opened/read;
- stale marker created.
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; 4. **Implement Skill support separately**
- changed implementation plan; - Follow Agent Skills standard and Workspace authority.
- changed review outcome; - Do not mix Skill with Knowledge note schema.
- changed acceptance criteria or requirement;
- caused docs/Skill update;
- invalidated stale assumption;
- avoided duplicate work;
- reduced time-to-evidence.
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: - Treating Memory as the only long-term knowledge store.
- Treating Knowledge as generated memory with a different name.
- Reviewer Skill says: request contradicting evidence before approving. - Treating Skill as a Workflow tracker or state machine.
- Orchestrator Skill says: create a Ticket shoebox before routing a risky Ticket. - Hiding context injection outside Worker history/tool results.
- Coder Skill says: cite relevant prior decisions in the final dossier. - Making Knowledge notes authoritative over Tickets/docs/git history.
- Automatically rewriting Knowledge/Skills/docs without review.
The Memory service provides the data and artifacts those Skills ask for. - Designing a vector database before the human-readable artifact model is stable.
## 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.
## Open decisions ## Open decisions
- Whether shoebox/evidence should start as Ticket artifacts, Objective resources, or a new Workspace Memory record type. - Whether target Knowledge uses `.yoi/knowledge/<slug>.md`, nested directories, or an index plus notes.
- How much session-log search belongs in the first slice. - Exact frontmatter for Knowledge notes.
- Whether source refs need a shared URI scheme across Ticket/Objectives/docs/git/session/code. - Link syntax and backlink extraction rules.
- Whether Memory tools live in `worker` feature space first or are exposed only via Workspace backend APIs. - How Knowledge note IDs/slugs relate to titles.
- How to represent confidence/staleness without encouraging false precision. - Whether Memory remains local-first or becomes Workspace API-first in the same phase as Knowledge.
- What exact product-impact events are worth recording in the first implementation. - 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: This architecture is ready to split into Tickets when:
- the core flow `source -> shoebox -> evidence -> representation/hypothesis -> product` is accepted; - the Memory / Knowledge / Skill boundary is accepted;
- storage boundaries between Memory, Ticket, Objective, docs, and Skills are accepted; - target Knowledge as long-term linked notes is accepted;
- the first prototype slice is chosen; - Workspace backend authority for Memory/Knowledge/Skills is accepted;
- non-goals are accepted so implementation does not re-create Knowledge or Workflow tracking. - the first implementation slice is chosen;
- non-goals are accepted so implementation does not recreate old Workflow tracking or old unused Knowledge unchanged.