# Memory Layout

This folder is the assistant's working memory on disk.

## Roles

- `../MEMORY.md`
  - Curated long-term memory
  - Durable truths only
  - Examples: preferences, stable decisions, important future dates, recurring lessons

- `YYYY-MM-DD.md`
  - Daily inbox / timeline
  - Default place for new notes
  - Prefer this over creating a new one-off file

- `ops/`
  - Operational notes
  - Setup history, routing decisions, workflow changes, tool behavior, validation notes

- `incidents/`
  - Debugging and incident history
  - Errors, outages, investigations, mitigations, postmortem-style notes

- `plans/`
  - Multi-session plans or ongoing initiatives

- `references/`
  - Stable supporting material worth keeping around for reuse

- `archive/`
  - Old low-value or superseded material kept only for traceability

## Retrieval model

Files are the source of truth.

Embeddings are the lookup layer:
- use semantic search to find likely relevant notes
- then read the source lines
- answer from the file, not from the vector hit alone

## Writing guidance

When in doubt:
1. write to today's daily note
2. later promote durable truths into `../MEMORY.md`
3. only create a named note when the topic genuinely needs a long-lived home

## Cleanup guidance

If top-level `memory/` starts filling with non-daily files again:
- move operational material to `ops/`
- move debugging material to `incidents/`
- move stale low-value chatter to `archive/`
- keep top-level mostly daily notes