objective: revise memory knowledge skills architecture
This commit is contained in:
parent
9e0f8e9aad
commit
1abf56dbc2
|
|
@ -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-name>/
|
||||
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>/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/<objective-id>/resources/<name>.md
|
||||
.yoi/tickets/<ticket-id>/artifacts/<name>.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>/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/<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.
|
||||
|
||||
## 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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user