67 lines
2.2 KiB
Markdown
67 lines
2.2 KiB
Markdown
# 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
|
|
...
|
|
```
|