Memory Flush

${var} - Topic to focus on. If empty, flushes all recent activity.

If ${var} is set, only promote entries related to that topic. Pruning (step 3), the index upkeep (step 6), and the deterministic watermark + rotation (steps 0 and 8) still run globally - a focused flush must never leave the rest of the store stale.

Read memory/MEMORY.md for current memory state. The scan window and log rotation are computed for you in step 0 - you no longer parse the watermark or rotate logs by hand.

Steps

0. Prepare (deterministic bookkeeping - run this first)

Run python3 scripts/memory_prep.py window and read its stdout. It:

• computes your scan window from the structured watermark memory/memory-flush-state.json (fallback for a first-run migration: the MEMORY.md *Last consolidated:* line; then the last 3 days; a gap over 14 days is clamped to 14 and flagged), and prints the exact in-window log files to read;
• has already rotated whole old months out of memory/logs/ into memory/logs/archive/YYYY-MM.md (content-preserving) once the directory passed ~45 files.

Read exactly the files it lists. Do not recompute the window or rotate logs yourself - that work is now deterministic and unit-tested (scripts/memory_prep.py), so it never silently falls back to 3 days or gets skipped. This closed two old holes: entries older than 3 days were lost whenever the agent skipped runs, and a daily schedule re-scanned the same 3 days every time.

1. Scan the in-window logs for entries worth promoting to long-term memory

• New lessons learned (errors encountered, workarounds found)
• Topics covered (articles, digests) - add to the recent output/articles/digests tables
• Features built or tools created
• Important findings from monitors (on-chain, GitHub, papers)
• Ideas captured that are still relevant
• Goals completed or progress milestones

2. Check each candidate against existing MEMORY.md content - dedup precisely

Skip if already recorded. Dedup by the fact's subject, not by string match:

• Identify what each candidate is about (a skill, a token, a repo, a lesson, a priority).
• If MEMORY.md already carries that subject, edit the existing line in place (merge the new detail, bump any date). Never append a second bullet that paraphrases an existing one - that near-duplicate drift is what a memory flush exists to prevent.
• Only add a new bullet when the subject is genuinely absent.

3. Remove stale entries - this is as important as adding new ones

a. Open Improvement PRs section: Run gh pr list --state open --search "improve:" --json number,title,url and compare against any "Open Improvement PRs" section in MEMORY.md.

• If all listed PRs are now merged/closed, remove the section entirely.
• If some PRs are merged, update the list to reflect only current open ones. b. Next Priorities section: Cross-check each listed priority against recent logs and current repo state. Remove priorities that are already done (e.g., "Merge open PRs" if 0 open PRs exist). Add any newly urgent priorities surfaced by recent logs. c. Lessons Learned: Remove lessons that are now outdated or resolved (e.g., a workaround for a bug that was later fixed). d. Overflow any section that outgrows its budget (keeps MEMORY.md an index, not a ledger): if a section has grown past the last ~10-15 rows - the Skills Built table is the usual first offender, but the rule is general - archive the oldest rows to memory/topics/<section>-history.md (e.g. skills-history.md) and leave a one-line pointer to that file. Trim newest-kept, oldest-archived.

4. Update memory

• Add brief entries to MEMORY.md (keep it under ~50 lines as an index).
• If a topic needs more detail, write to memory/topics/<topic>.md instead (see step 6 - register it in the index).
• Update tables (recent articles, recent digests) with new rows.
• Before adding a section, check whether its ## Heading already exists anywhere in MEMORY.md - if it does, update that section in place. Never prepend a duplicate heading.
• Do not hand-edit the consolidation date. It is stamped by step 8 (memory_prep.py stamp), which writes the structured watermark memory/memory-flush-state.json (the source of truth) and mirrors it into the MEMORY.md *Last consolidated:* line. Skipping step 8 after a real flush is a bug - other skills (e.g. action-converter) read that line to tell a live, consolidated store from an untouched template.