AGENTS.ctx: Archive Flow Detail

Level 3 (Detail) — Archive script, flat archive structure, and regeneration.

Concept

The memory archive is a two-phase process. Phase A and Phase B steps 1-3 are handled by scripts/archive-memory.sh. Phase B step 4 (past-summary regeneration) is LM responsibility.

Archive Structure

Archives are stored flat in past/ — each directory named by date and event:

past/2026-06-05_description-slug/
├── chronicle.md    — full cycle chronology up to archive point
├── system-state.md — state doctrine at archive point
├── debts.md        — full debt register (closed preserved for history)
└── past-summary.md — compressed summary of the archived cycle

No recursive nesting. Each archive sits side-by-side.

Script Interface

File: scripts/archive-memory.sh

scripts/archive-memory.sh                          # threshold gate (default)
scripts/archive-memory.sh --force                  # skip threshold
scripts/archive-memory.sh --force "cluster-test"   # with LM-provided slug

The description slug is kebab-case, alphanumeric + hyphens only. If omitted, the script extracts a slug from the first ### event in chronicle.md.

Phase A: Archive (Script)

  1. Extracts slug from chronicle event (or uses LM-provided description)
  2. Creates past/YYYY-MM-DD_slug/
  3. Moves root chronicle.md, system-state.md, debts.md, past-summary.md into it

Phase B Steps 1-3: Regeneration (Script, Deterministic)

  1. Copies system-state.md from the just-created archive back to root
  2. Filters debts.md — keeps rows where Status is not Closed. Unrecognized statuses are kept and logged with [WARN].
  3. Creates a minimal chronicle.md header with cycle timestamp

Phase B Step 4: LM Responsibility

  • Write past-summary.md summarizing the archived cycle
  • Append meaningful chronicle entries for the current session

Logging

Every execution writes a structured log to archive-logs/archive-<timestamp>.log:

  • Section markers for scannability
  • [INFO], [OK], [WARN], [ERROR] levels
  • Debt filter warnings for unrecognized statuses (LM should review)
  • Ends with PHASE B STEP 4 PENDING reminder
  • Max 20 log files retained

Validation Checklist

After archive:

  • New archive directory: past/YYYY-MM-DD_description/ with all 4 files
  • Root: chronicle.md (minimal header), system-state.md, debts.md (no closed debts)
  • past-summary.md exists after LM step 4
  • No closed debts remain in root debts.md
  • Archive log contains ARCHIVE COMPLETE with no unexpected [WARN] or [ERROR]

See Also