memory-writeback

Memory Writeback

After any meaningful project change, evaluate whether durable project understanding changed. If yes, update the correct memory branch before ending the session. If no, say so explicitly.

---

Evaluation -- ask after every meaningful task

"Did this session change what future sessions should understand about this project?"

Write to memory if the answer is yes for any of:

• An architectural decision was made or reversed
• A new pattern or convention was confirmed
• A critical gotcha was discovered (build, DB, API, environment, path)
• A feature area was substantially completed or its design changed
• A recurring mistake was corrected (record the lesson)
• A dependency or external constraint changed

Skip writeback if:

• The session was read-only exploration with no new conclusions
• The change is already captured in git or inline documentation
• The fact is session-specific and won't matter in a future session
• The fact is speculative and not yet confirmed
• The work changed code but not project understanding

When skipping, state it: Memory writeback: none needed.

---

What to write and where

Fact type	Target
Architectural decision	Memory/decisions/decisions.md (append numbered entry) + optionally Memory/decisions/YYYY-MM-DD-slug.md for a deep-dive
New pattern or convention	relevant branch note -> Current State
Gotcha or constraint	relevant branch note -> Current State
Stack change	relevant branch note -> Current State + Recent Changes
Completed feature area	relevant branch note -> Current State
Lesson from a mistake	relevant branch note -> Current State, with Why: and How to apply:

If no existing branch fits the fact, create a new branch note using the same-name convention. Use the project's own terminology for branch names.

---

How to write

1. Identify the target branch note.
2. Read its current content.
3. Preserve YAML frontmatter and add or update the fact in the correct section.
   • Current State: what is true now (replace stale entries, don't append duplicates)
   • Recent Changes: YYYY-MM-DD -- what changed (prune entries older than ~4 weeks)
   • Decisions: link to decision file
   • Open Questions: add unresolved items only if they remain open after verification
4. Use emojis in section headers to improve scannability. Pick an emoji that matches the section's purpose (e.g. ## 🔄 Recent Changes, ## 🔗 See Also, ## ⚠️ Gotchas, ## 📦 Build, ## 🔍 Detection, ## 🧩 Patterns). Keep existing headers consistent.
5. If the branch now exceeds ~150 lines, follow the memory-compaction skill.
6. If branch summaries changed, update agent-knowledge/Memory/MEMORY.md.