# 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:

```text
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:

```text
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:

```text
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:

```text
vault/03-context/<domain>/*.md
```

### `people`

Use for repeated collaborators, role mappings, manager/stakeholder context, and communication preferences.

Default path pattern:

```text
vault/04-people/*.md
```

### `decisions`

Use for confirmed decisions with ongoing impact.

Default path pattern:

```text
vault/05-decisions/*.md
```

### `tooling-behavior`

Use when a user correction changes how the workspace should behave in the future.

Default path patterns:

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

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
- 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 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.md` and 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.