diff --git a/AGENTS.md b/AGENTS.md index 6ea5d73..fe66ea0 100644 --- a/AGENTS.md +++ b/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) diff --git a/memory/2026-03-11.md b/memory/2026-03-11.md index db46193..df575f0 100644 --- a/memory/2026-03-11.md +++ b/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. diff --git a/memory/README.md b/memory/README.md new file mode 100644 index 0000000..49cb241 --- /dev/null +++ b/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