fidelity-ai-workspace/agent-memory/behavior/agent-behavior.md

type, status, updated, tags

type	status	updated	tags
agent-behavior	active	2026-04-21	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.