docs(memory): add taxonomy and retrieval guide

AGENTS.md

@@ -38,6 +38,23 @@ You wake up fresh each session. These files are your continuity:
 
 Capture what matters. Decisions, context, things to remember. Skip the secrets unless asked to keep them.
 
+### Memory taxonomy
+
+Use the memory system like this:
+
+- `MEMORY.md` → durable truths: preferences, standing decisions, important plans/dates, recurring lessons
+- `memory/YYYY-MM-DD.md` → daily inbox / chronological notes
+- `memory/ops/` → operational history, workflow decisions, setup notes, tooling behavior
+- `memory/incidents/` → bugs, outages, debugging trails, postmortem-ish notes
+- `memory/plans/` → active plans that may evolve over multiple sessions
+- `memory/references/` → stable reference material worth keeping around
+- `memory/archive/` → retained but low-value or superseded material
+
+Retrieval rule of thumb:
+- write first for humans
+- use embeddings for lookup
+- verify against the source file before answering or acting
+
 ### 🧠 MEMORY.md - Your Long-Term Memory
 
 - **ONLY load in main session** (direct chats with your human)

memory/2026-03-11.md

@@ -34,6 +34,10 @@
   - `memory/incidents/` for debugging, outages, and issue investigation notes
 - Result: top-level `memory/` now contains mostly daily notes, which makes the default inbox much clearer.
 
+## Memory taxonomy/docs
+- Added a compact memory taxonomy section to `AGENTS.md` so future sessions know where different kinds of notes belong.
+- Added `memory/README.md` to explain the folder layout, writing rules, and how embeddings should be used: lookup first, source verification second.
+
 ## Follow-up intent
 - Be more disciplined about using the daily note as the default inbox and promoting only durable truths into `MEMORY.md`.
 - Avoid adding new one-off memory files unless the topic is truly long-lived.

memory/README.md

@@ -0,0 +1,56 @@
+# 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