From b1dd738966fa64a09d312634b51e3709c1d4c14e Mon Sep 17 00:00:00 2001 From: zap Date: Wed, 11 Mar 2026 18:59:53 +0000 Subject: [PATCH] docs(memory): add naming and maintenance guidance --- AGENTS.md | 7 +++++++ memory/2026-03-11.md | 1 + memory/README.md | 10 ++++++++++ 3 files changed, 18 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index fe66ea0..bc0b289 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,6 +34,7 @@ You wake up fresh each session. These files are your continuity: - **Daily notes:** `memory/YYYY-MM-DD.md` (create `memory/` if needed) — raw logs of what happened - **Long-term:** `MEMORY.md` — your curated memories, like a human's long-term memory - **Named notes:** reserve separate memory files for long-lived plans, references, or investigations that truly need their own home; otherwise prefer folding notes back into the daily file +- **When a named note is justified:** create one when the topic will likely span multiple sessions, accumulate evidence over time, or be reused as a reference. If it was just one conversation or one fix, prefer the daily note. - **Top-level `memory/` rule:** keep top-level mostly for daily notes. Put topical files in subfolders like `memory/ops/`, `memory/incidents/`, `memory/plans/`, `memory/references/`, or `memory/archive/`. Capture what matters. Decisions, context, things to remember. Skip the secrets unless asked to keep them. @@ -287,6 +288,12 @@ You are free to edit `HEARTBEAT.md` with a short checklist or reminders. Keep it ### 🔄 Memory Maintenance (During Heartbeats) +Light weekly checklist: +- skim the last few daily notes +- promote any durable truths into `MEMORY.md` +- move obvious topical notes into `ops/`, `incidents/`, `plans/`, or `references/` +- archive low-value clutter if top-level `memory/` is getting noisy + Periodically (every few days), use a heartbeat to: 1. Read through recent `memory/YYYY-MM-DD.md` files diff --git a/memory/2026-03-11.md b/memory/2026-03-11.md index df575f0..8081350 100644 --- a/memory/2026-03-11.md +++ b/memory/2026-03-11.md @@ -42,3 +42,4 @@ - 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. - Keep top-level `memory/` mostly reserved for daily notes; use subfolders for topical material. +- Use a light weekly memory-maintenance pass during heartbeats instead of waiting for clutter to build up. diff --git a/memory/README.md b/memory/README.md index 49cb241..53b630f 100644 --- a/memory/README.md +++ b/memory/README.md @@ -47,6 +47,16 @@ When in doubt: 2. later promote durable truths into `../MEMORY.md` 3. 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: