5.2 KiB
Agent Memory Rules
Goal
Make workspace memory maintenance part of the agent's normal job, not a separate optional workflow.
Default Agent Behavior
For any meaningful prompt, the agent should decide whether the interaction changes project memory.
This applies to:
- direct user prompts
- Mattermost sync results
- translated notes
- standup generation
- manager-update drafting
- debugging discussions
- corrections to previous understanding
The agent should not wait for a separate promotion command when the right update is already clear.
What Counts As Memory-Worthy
Capture information automatically when it is:
- project-relevant
- explicit enough to preserve safely
- likely to matter in a future session
- useful for standups, debugging, or supervisor communication
Examples:
- confirmed story creation, points, scope, or priority
- confirmed reproduction constraints
- newly clarified root cause framing
- approved manager guidance that changes work direction
- confirmed version, dependency, or rollout facts tied to current work
- corrections to previously stored project context
- repeated named people with stable roles or communication relevance
- repeated named people with multi-channel, multi-year, or high-signal technical/process involvement even when the exact formal role is still unknown
What The Agent Must Do
When new memory-worthy information appears, the agent should:
- decide whether it is daily, current-state, durable, or decision-level context
- update the smallest correct set of files
- correct stale or conflicting existing statements
- answer the user using the refreshed context
Do not ask the user what to promote unless the ambiguity is real and material.
Tooling Self-Maintenance
User corrections about how the workspace should behave are memory-worthy when they affect future output.
If a correction applies to a command, prompt, skill, agent, or reusable rule, update the linked tool directly instead of only logging the correction.
Examples:
- A standup formatting correction should update
prompts/standup.mdand.opencode/commands/standup.md. - A Mattermost freshness correction should update the Mattermost command/plugin instructions.
- A Copilot prompt-structure correction should update
prompts/copilot-prompt.md,.opencode/commands/copilot-prompt.md, or the Copilot skill. - A Swift answer-quality correction should update the relevant iOS skill or
ai/context/ios/guidance.
Keep the daily log as evidence of what happened, but make the reusable behavior live in the file that controls that behavior.
File Selection
ai/logs/YYYY-MM-DD.md
Default destination for:
- same-day progress
- same-day findings
- scoped reproduction notes
- story and approval movement
- context that is important now but may evolve later
ai/state/current.md
Use when the fact changes the active work window, including:
- current priorities
- currently active story scope
- current blockers or debugging constraints
- manager direction that changes the next few days of work
ai/work-items/*.md and ai/state/work-items.md
Use ai/work-items/*.md as the canonical memory for current Jira-linked work that should remain easy to reference across sessions, especially:
- Jira IDs
- approved or explicit titles
- currently relevant status notes
- current points or scope notes
Use ai/state/work-items.md as the summary view of what is active now.
These files should help standups and manager updates mention work items precisely.
ai/context/project.md
Use for durable project knowledge that should survive beyond the current work window.
ai/context/people/manager.md
Use only when a communication preference or manager expectation becomes stable enough to reuse repeatedly.
ai/context/people/index.md and ai/context/people/*.md
Use these files for:
- mapping roles to actual people
- keeping named stakeholders recognizable across sessions
- storing stable communication or responsibility context per person
When the role is not explicit, store:
- where the person tends to appear
- what kinds of topics they influence
- how they affect approvals, scope, debugging, or communication
ai/context/decisions/*.md
Use for explicit confirmed decisions with ongoing impact.
.opencode/commands/, prompts/, .opencode/agents/, .opencode/skills/, and knowledge/
Use these when the new information changes how the workspace should operate:
- command invocation behavior
- reusable output format
- default agent behavior
- specialized skill workflow
- persistent process or memory rules
Do not create a separate note when an existing command, prompt, agent, or skill is the source of truth.
What Not To Store
Do not store:
- tool failures
- sync attempts
- generic urgency messages
- duplicate paraphrases of the same fact
- weak guesses
- operational chatter that does not change project understanding
Correction Rule
If new information supersedes old memory:
- update the existing canonical file
- do not leave stale and corrected versions side by side
- preserve qualifiers if the fact is only partially confirmed
The agent should behave like a senior engineer maintaining project notes, not like a chat assistant accumulating transcripts.