# 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

- `projects.md`
  - Human-readable registry of active bigger-picture efforts
  - Good for quick orientation across sessions

- `tasks.json`
  - Structured task state for follow-up and reminders

- `tasks.md`
  - Human-readable guide for how task tracking should work

- `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. if it's a durable fact, promote it into `../MEMORY.md`
3. if it's a bigger ongoing effort, add/update `projects.md`
4. if it needs follow-up or status tracking, add/update `tasks.json`
5. only create a named note when the topic genuinely needs a long-lived home

Create a named note when:
- the topic will span multiple sessions
- it needs to collect evidence, commands, or findings over time
- it is likely to be reused as a reference later

Prefer the daily note when:
- it was a one-off conversation
- it was a tiny fix or validation
- the note would otherwise become a small orphan file

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