yoi/.yoi/objectives/00001KVJSMQXZ/memory-architecture-overview.md

created_at	updated_at	objective	status	notes
2026-07-15T21:33:00Z	2026-07-15T21:52:00Z	00001KVJSMQXZ	architecture-draft	Draft architecture for redesigning Memory / Knowledge / Skills as distinct workspace resources. This is an Objective resource, not implementation authority.

Memory / Knowledge / Skills architecture overview

Position

Yoi should treat Memory, Knowledge, and Skills as three distinct resource classes instead of trying to make one generic record store do everything.

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.

Target split:

• Memory: short-term facts, preferences, current focus, and in-progress context. It is written with change in mind.
• Knowledge: long-term notes meant to be cultivated by humans/agents, cross-linked into a mesh, and readable as durable project understanding.
• Skill: portable, established procedural guidance in Agent Skills format, used to perform a class of work.

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.

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

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 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.

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.

Knowledge notes should:

• 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.

Knowledge is where long-term architecture notes, conceptual models, subsystem explanations, decision context, recurring constraints, and domain understanding should mature.

Knowledge examples

• workspace-authority-model
  • Explains why Workspace backend is authority for Tickets/Skills/Runtime views.
  • Links to Ticket backend API design, Skill support ticket, Workspace control plane Objective.
• 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.

Skill

Skill is an established, portable workflow/procedure for a class of tasks. It should follow Agent Skills format:

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

A Skill is not a state machine and does not own external authority. It is prompt/resource guidance that tells the agent how to perform a task using available tools.

Skills should contain:

• when to use the Skill;
• step-by-step procedure;
• expected inputs;
• expected outputs/report shape;
• examples;
• edge cases;
• optional references/scripts/assets.

Skills are portable when they can be moved to another workspace with minimal project-specific assumptions.

Skill examples

• 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.

Boundaries

Memory vs Knowledge

Memory is provisional and change-oriented. Knowledge is maintained and growth-oriented.

Use Memory when:

• 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.

Use Knowledge when:

• 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.

Promotion path:

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

Promotion should be explicit. Not every Memory item becomes Knowledge.

Knowledge vs Docs

Docs are maintained public/project-facing exposition. Knowledge is internal, linked, evolving understanding.

A Knowledge note may later become a doc, but the threshold is different:

• Knowledge can contain uncertainty, partial models, and links to evidence.
• Docs should present settled explanations or user/developer guidance.

Knowledge vs Ticket decisions

Ticket decisions are authority for work item history and state. Knowledge notes synthesize across Tickets.

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.

Skill vs Knowledge

Knowledge explains what is true or how the project is understood. Skill explains how to do a recurring task.

Use Skill when the artifact should instruct an agent to perform work:

• review process;
• implementation process;
• release checklist;
• architecture evaluation method.

Use Knowledge when the artifact should explain a concept:

• Workspace authority model;
• Memory architecture;
• Ticket lifecycle rationale.

Skill vs Feature/Plugin

Skill is prompt/resource guidance. Feature/Plugin is executable authority and tool surface.

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;
• Memory candidate proposal from sessions or artifacts;
• provenance and audit events;
• preference/current-focus surfaces.

Local .yoi/memory can remain compatibility/offline storage during transition.

Knowledge API

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:

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

The architecture should make these promotions explicit and reviewable.

Sensemaking as a usage pattern

Sensemaking remains useful, but should be treated as a pattern layered on the resource model.

Pirolli & Card's flow can map to Yoi resources as:

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

But we should not make "shoebox" or "hypothesis matrix" mandatory first-class concepts until actual workflows prove they are needed.

Initial sensemaking support can be lightweight:

• task-bound collected references as Ticket/Objective artifacts;
• evidence summaries with provenance;
• explicit contradictory evidence sections in review Skills;
• Knowledge notes that synthesize recurring patterns.

Implementation posture

The current implementation can be redesigned. Do not preserve old Memory/Knowledge shapes just because they exist.

However, avoid a large-bang rewrite. Split after this architecture is accepted.

Recommended implementation sequence:

1. Clarify current Memory after Knowledge removal

   • Keep short-term/resident Memory working.
   • Remove assumptions that Memory must replace Knowledge.

2. Design target Knowledge note model

   • Markdown note format.
   • link/backlink model.
   • provenance/staleness metadata.
   • Workspace API surface.

3. Implement minimal Knowledge catalog/read/write

   • Start with Markdown files and Workspace API.
   • Add lint and backlinks.

4. Implement Skill support separately

   • Follow Agent Skills standard and Workspace authority.
   • Do not mix Skill with Knowledge note schema.

5. Add promotion workflows/tools

   • Memory -> Knowledge candidate.
   • Knowledge -> docs/Ticket decision candidate.
   • repeated procedure -> Skill candidate.

6. Add sensemaking helpers only after resource classes stabilize

   • collected refs;
   • evidence extraction;
   • contradiction/staleness views;
   • product-impact metrics.

Non-goals

• Treating Memory as the only long-term knowledge store.
• Treating Knowledge as generated memory with a different name.
• Treating Skill as a Workflow tracker or state machine.
• Hiding context injection outside Worker history/tool results.
• Making Knowledge notes authoritative over Tickets/docs/git history.
• Automatically rewriting Knowledge/Skills/docs without review.
• Designing a vector database before the human-readable artifact model is stable.

Open decisions

• Whether target Knowledge uses .yoi/knowledge/<slug>.md, nested directories, or an index plus notes.
• Exact frontmatter for Knowledge notes.
• Link syntax and backlink extraction rules.
• How Knowledge note IDs/slugs relate to titles.
• Whether Memory remains local-first or becomes Workspace API-first in the same phase as Knowledge.
• Whether Memory/Knowledge APIs share a crate or are separate domain crates.
• What promotion UI/tool should exist for Memory -> Knowledge.
• How to distinguish personal Memory from workspace Memory.
• How much auto-generation is allowed for Knowledge drafts.

Exit criteria for architecture phase

This architecture is ready to split into Tickets when:

• 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.