agent-builder/scripts/templates/memory

3-Tier Memory System

Inspired by OpenClaw's proactive agent memory pattern. Three tiers serve different purposes with different update frequencies.

Architecture

Tier 1: SESSION-STATE.md (hot)
  - Updated every turn
  - Read FIRST on session start and compaction recovery
  - Contains: current task, decisions, pending actions, working buffer

Tier 2: memory/YYYY-MM-DD.md (warm)
  - One file per day, auto-rotated
  - Updated at end of each pipeline run
  - Contains: daily summary, decisions, files modified, issues, carry-forward

Tier 3: memory/MEMORY.md (cold)
  - Updated manually or after significant learnings
  - Read LAST during compaction recovery
  - Contains: identity, curated learnings, patterns, known issues

WAL Protocol (Write-Ahead Logging)

Before responding to the user with important information, write it to SESSION-STATE.md first. This prevents data loss if:

• The session crashes mid-response
• Context compaction removes the exchange
• The user's connection drops

Working Buffer Protocol

When context usage exceeds ~60% (the "danger zone"):

1. Activate the Working Buffer section in SESSION-STATE.md
2. Copy critical recent exchanges into the buffer
3. Extract and list key facts that would be lost on compaction
4. Continue working normally — the buffer is your safety net

Compaction Recovery

When Claude resumes after context compaction, it reads in this order:

1. SESSION-STATE.md (current task, decisions, working buffer)
2. Today's daily log (what happened today)
3. MEMORY.md (long-term context, known issues)
4. Search older daily logs if needed for specific context

Integration with Agent Factory

During /agent-factory:build Phase 2.5 (Memory Setup):

1. Copy these templates to the user's memory/ directory
2. Replace {{PLACEHOLDER}} variables with project-specific values
3. Create the initial SESSION-STATE.md and MEMORY.md
4. Configure the pipeline skill to update daily logs after each run

File locations after scaffolding

project/
  memory/
    SESSION-STATE.md    (from Tier 1 template)
    MEMORY.md           (from Tier 3 template)
    2026-04-11.md       (generated daily, from Tier 2 template)
    2026-04-12.md
    ...