# 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
    ...
```