5.2 KiB
Operational Memory
Definition
Operational memory is a versionable file-based system where the agent decides whether each interaction introduces, corrects, or invalidates knowledge, then updates the smallest correct canonical file.
The goal is not transcript storage. The goal is a curated working memory that improves future reasoning, communication, and execution.
Memory Classes
daily
Use for same-day progress, findings, evolving reproduction notes, and work that may change soon.
Default path pattern:
vault/06-daily/YYYY-MM-DD.md
state
Use for current priorities, active blockers, near-term constraints, and communication needs that affect the next few days.
Default paths:
vault/01-current/current-work.md
vault/01-current/work-items.md
work-items
Use for canonical memory about active tickets, tasks, stories, investigations, or other units of work.
Default path pattern:
vault/02-work-items/<id-or-slug>.md
stable-context
Use for durable project knowledge that should survive beyond the current work window.
Default path pattern:
vault/03-context/<domain>/*.md
people
Use for repeated collaborators, role mappings, manager/stakeholder context, and communication preferences.
Default path pattern:
vault/04-people/*.md
decisions
Use for confirmed decisions with ongoing impact.
Default path pattern:
vault/05-decisions/*.md
tooling-behavior
Use when a user correction changes how the workspace should behave in the future.
Default path patterns:
.opencode/commands/*.md
.opencode/agents/*.md
.opencode/skills/*/SKILL.md
prompts/*.md
vault/00-start/*.md
vault/03-context/process/*.md
Raw evidence stays outside vault/; promoted memory is written to vault/.
Promotion Rules
Promote information when it is:
- explicit enough to preserve safely
- relevant to the current project or workflow
- likely to matter in a future session
- useful for standups, status updates, debugging, planning, or decision making
Do not promote:
- tool failures
- sync attempts
- empty inbox states
- generic chat noise
- unverified guesses
- duplicate paraphrases of existing memory
If confidence is mixed, prefer the daily log and preserve uncertainty.
Learning Session Rules
A learning session is any interaction where the user asks the agent to explain, reason about, or improve understanding of a topic and may then correct or extend the answer.
Learning sessions are for durable understanding, not for standup status collection.
The agent should:
- answer from known workspace context and verified sources only
- explicitly separate known facts, reasonable inferences, and unknowns
- avoid inventing missing context, names, tickets, implementation details, or causal explanations
- ask a concise clarification question when the missing information materially affects the answer
- provide a partial answer when useful, clearly labeling assumptions and uncertainty
- prioritize architecture, system boundaries, ownership, release process, debugging strategy, reusable workflows, domain concepts, and decision rules
- avoid defaulting to in-progress ticket status unless the user asks for current work or the status exposes a durable process/architecture gap
- ask questions that would help a senior engineer ramp into the project, not questions that merely refresh the latest daily update
- treat user corrections as high-value learning input
- update the smallest correct canonical file when the correction changes future behavior or project understanding
- avoid turning every answer into memory; promote only reusable or project-relevant learning
When proposing clarification questions, keep them concise and high-leverage:
- prefer 3 to 5 questions
- group by durable learning area
- state why each question matters for future reasoning
- avoid multi-level status checklists
When the user is teaching the agent how to behave, update tooling-behavior.
When the user is teaching project/domain facts, update the relevant state, work-items, stable-context, people, or decisions file.
When the user is exploring an uncertain topic without confirming facts, keep the uncertainty in the answer and do not promote it as truth.
Correction Rules
When new information supersedes old memory:
- update the existing canonical file directly
- do not leave stale and corrected versions side by side
- preserve qualifiers when the fact remains partially confirmed
- update indexes when adding new stable context files
The agent should behave like a senior engineer maintaining project notes, not like a transcript accumulator.
Self-Maintenance Rules
When the user corrects recurring output or behavior, update the operational surface that controls that behavior.
Examples:
- standup format correction -> update
prompts/standup.mdand the standup command - communication freshness correction -> update the communication sync command/plugin
- prompt-engineering correction -> update the AI prompt command or skill
- memory routing correction -> update memory rules and context-maintenance guidance
The daily log may preserve evidence, but reusable behavior must live in the command, prompt, skill, agent, or knowledge file that enforces it.