david.delagneau
1ad707373a
- Created daily log entries for May 13, 14, 18, 19, 20, and 21, capturing work done, findings, and next steps. - Established a daily logs index for easy navigation of daily notes. - Developed templates for daily logs, decisions, meeting notes, people, systems, and work items to standardize documentation. - Introduced base files for filtering and displaying various types of project knowledge, including daily notes, decisions, people, systems, work items, and workstreams. - Added maps for current work, fidelity apps, and fidelity domain to enhance project navigation and context.
235 lines
9.4 KiB
Markdown
235 lines
9.4 KiB
Markdown
---
|
|
type: agent-behavior
|
|
status: active
|
|
updated: 2026-04-21
|
|
tags: [process, memory, agent]
|
|
---
|
|
|
|
# Agent Memory Rules
|
|
|
|
## Goal
|
|
|
|
Make workspace memory maintenance part of the agent's normal job, not a separate optional workflow.
|
|
|
|
---
|
|
|
|
## Default Agent Behavior (Real-Time Auto-Documentation)
|
|
|
|
For every meaningful prompt, the agent must evaluate whether a memory update is needed in the same turn. Auto-documentation is part of the job, but it must not dominate the critical path of simple user-facing answers.
|
|
|
|
This applies to:
|
|
|
|
- direct user prompts
|
|
- Mattermost sync results
|
|
- translated notes
|
|
- standup generation
|
|
- manager-update drafting
|
|
- debugging discussions
|
|
- corrections to previous understanding
|
|
|
|
The agent must not wait for a separate promotion command. The agent should proactively update `workspaces/fidelity/project-knowledge/` (including 01-current, 02-work-items, 03-context, 04-people, 06-daily) within the same conversational turn when new information is clear, durable, and the destination is obvious.
|
|
|
|
- When editing `workspaces/fidelity/project-knowledge/`, write as a human engineer maintaining shared project documentation.
|
|
- Keep agent-operating logic out of `workspaces/fidelity/project-knowledge/`; store that logic in prompts, commands, skills, agents, or `agent-memory/`.
|
|
- Answer-first rule: when the user's main goal is analysis, review, translation, or drafting, answer first unless persistence is required to avoid losing a clear durable fact.
|
|
- Do not create a brand-new canonical note during the critical path of the answer unless the user explicitly asked to save the fact or the new note is the smallest correct update.
|
|
- Prefer updating an existing canonical note over creating a new file when both are valid.
|
|
|
|
---
|
|
|
|
## Learning Sessions
|
|
|
|
The agent should support incremental self-learning sessions.
|
|
|
|
When the user asks a question, the agent may answer from existing context, but must not invent missing facts.
|
|
|
|
Learning sessions should improve durable project understanding. They are not the same as standup preparation, daily status refresh, or ticket triage unless the user explicitly asks for that.
|
|
|
|
The agent should:
|
|
|
|
- say what is known from the workspace
|
|
- say what is unclear or not available
|
|
- label assumptions and inferences explicitly
|
|
- ask a concise clarification question when the missing context materially changes the answer
|
|
- focus clarification questions on architecture, process, ownership, debugging patterns, domain concepts, release mechanics, and decision rules
|
|
- avoid asking mostly about transient ticket state unless the answer would clarify a durable project rule
|
|
- learn from user corrections or confirmations by updating the smallest correct canonical file
|
|
- avoid promoting unconfirmed exploration as durable truth
|
|
|
|
Good learning behavior:
|
|
|
|
- If the answer is clear from stored context, answer directly and update nothing unless the interaction adds durable context.
|
|
- If the answer is partly clear, answer the known part, state the gap, and ask for the missing detail.
|
|
- If the user corrects the answer, update the stale memory or behavior rule directly.
|
|
- If the user teaches a reusable workflow preference, update the relevant command, prompt, skill, agent rule, or process note.
|
|
- If the user asks what the agent wants to clarify, propose 3 to 5 high-leverage questions that would help a senior engineer ramp into the project.
|
|
|
|
Do not ask for clarification just to avoid work. Ask only when the missing context is material or when guessing would create misleading memory.
|
|
|
|
Avoid low-value learning-session questions such as:
|
|
|
|
- whether a specific PR was approved today
|
|
- whether a ticket moved columns today
|
|
- what the next standup line should be
|
|
- temporary sequencing questions that belong in `workspaces/fidelity/project-knowledge/01-current/` or `workspaces/fidelity/project-knowledge/06-daily/`
|
|
|
|
Prefer high-value questions such as:
|
|
|
|
- what determines ownership between SDK, adapter, feature module, app, and backend configuration
|
|
- how release propagation works across SDK, adapter, consuming app, and validation environment
|
|
- what invariants define REST vs GraphQL parity
|
|
- how authenticated and non-authenticated flows differ operationally
|
|
- what evidence is required before classifying an external issue as a regression
|
|
|
|
---
|
|
|
|
## 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
|
|
- corrections to the agent's answer quality, uncertainty handling, or learning behavior
|
|
- 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:
|
|
|
|
1. decide whether it is daily, current-state, durable, or decision-level context
|
|
2. update the smallest correct set of files
|
|
3. correct stale or conflicting existing statements
|
|
4. 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.md` and the shared workflow in `.agents/workflows/standup.md`.
|
|
- A Mattermost freshness correction should update the Mattermost command/plugin instructions.
|
|
- A Copilot prompt-structure correction should update `prompts/copilot-prompt.md`, `.agents/workflows/copilot-prompt.md`, or the shared skill/rule source.
|
|
- A Swift answer-quality correction should update the relevant iOS skill or `workspaces/fidelity/project-knowledge/03-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
|
|
|
|
### `workspaces/fidelity/project-knowledge/06-daily/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
|
|
|
|
### `workspaces/fidelity/project-knowledge/01-current/current-work.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
|
|
|
|
### `workspaces/fidelity/project-knowledge/02-work-items/*.md` and `workspaces/fidelity/project-knowledge/01-current/work-items.md`
|
|
|
|
Use `workspaces/fidelity/project-knowledge/02-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 `workspaces/fidelity/project-knowledge/01-current/work-items.md` as the summary view of what is active now.
|
|
|
|
These files should help standups and manager updates mention work items precisely.
|
|
|
|
### `workspaces/fidelity/project-knowledge/03-context/project.md`
|
|
|
|
Use for durable project knowledge that should survive beyond the current work window.
|
|
|
|
### `workspaces/fidelity/project-knowledge/04-people/manager.md`
|
|
|
|
Use only when a communication preference or manager expectation becomes stable enough to reuse repeatedly.
|
|
|
|
### `workspaces/fidelity/project-knowledge/04-people/index.md` and `workspaces/fidelity/project-knowledge/04-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
|
|
|
|
### `workspaces/fidelity/project-knowledge/05-decisions/*.md`
|
|
|
|
Use for explicit confirmed decisions with ongoing impact.
|
|
|
|
### `.agents/workflows/`, `.agents/rules/`, `.agents/skills/`, `.opencode/`, `prompts/`, and `agent-memory/`
|
|
|
|
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.
|