Skip to content

memory.md

Latest commit

 

History

History
113 lines (89 loc) · 3.79 KB

memory.md

File metadata and controls

113 lines (89 loc) · 3.79 KB

Layer I: Memory Persistence — Implementation Guide

The Problem

Context windows are finite. When they fill up:

  1. Compression happens → Details destroyed
  2. "Why did I choose X?" → Forgotten
  3. "What didn't work?" → Forgotten
  4. "What's the variable value?" → Gone
  5. Result: Agent repeats mistakes, loops, wastes time

Three Pillars of External State

1. Task State (Where am I?)

Must always be able to answer:

  • Goal: What am I trying to accomplish?
  • Phase: What stage am I in? (planning/executing/debugging/reviewing)
  • Progress: What's done, what's next?
  • Blockers: What's stopping me?
  • Variables: Key data I need to remember (URLs, IDs, names, values)

2. Decision Log (Why did I do that?) ⭐ MOST VALUABLE

This is the #1 thing lost during compression. Each entry:

### [Date/Time] Decision: [Short Title]
- **Choice**: What was decided
- **Options considered**: A, B, C (with one-line each)
- **Reasoning**: Why this option won (THE KEY PART)
- **Risks**: What could go wrong
- **If wrong**: How to recover/rollback
- **Context**: What task/phase was this in

Why this matters: When context is compressed and you reload state, the decision log tells you not just WHAT was decided but WHY. This prevents re-litigating settled questions.

Examples by agent type:

  • Coding: "Chose Session over JWT — project already has session middleware"
  • Content: "Chose 16:9 over 9:16 — target platform is YouTube not TikTok"
  • Operations: "Chose Wednesday over Friday — data shows 23% higher open rate"

3. Exclusion List (What NOT to do again)

Each entry:

  • What: The approach/option that didn't work
  • When: Date and task context
  • Why: Root cause of failure
  • Symptom: What error/symptom it produced

When to Save/Load

Event Action Priority
New task starts Initialize all 3 files Critical
Major decision made Append to decision log High
Approach fails Append to exclusion list High
Sub-task completed Update task state progress Medium
Context >80% full Full snapshot save Critical
About to be idle/compressed Full snapshot save Critical
New turn starts Load all state files Critical
Task completes/end Archive everything Medium

Storage Options

Option A: File System (OpenClaw / local agents)

workspace/memory/states/
├── .active-task          # Current task ID
├── .task-{id}.json       # Task state
├── .decisions-{id}.md     # Decision log
└── .context-map-{id}.md   # Context map + exclusions
  • ✅ Simple, fast, no dependencies
  • ❌ Only works with file system access

Option B: Feishu/Lark Document

  • Write to a doc or multi-dimensional table
  • ✅ Accessible from anywhere, visual
  • ❌ API latency, rate limits

Option C: Inline (no file access)

  • Prepend structured summary at start of every response: 
    [STATE] Task: X | Phase: Y | Next: Z | Last decision: W
  • ✅ Works everywhere, zero setup
  • ❌ Consumes context tokens, limited detail

Option D: Database (SQLite/Redis)

  • ✅ Queryable, scalable, structured
  • ❌ Setup required, another dependency

Option E: MCP Tools

  • Write via MCP server to external storage
  • ✅ Flexible, can write anywhere
  • ❌ Depends on MCP availability

Recovery Quality Target

After a compression/event reload, you should recover:

Information Target recovery rate
Current goal 100%
Current phase & progress 100%
Last 3 decisions (with reasoning) 100%
Active variables 95%
Exclusions (what didn't work) 90%
Detailed step history 70% (acceptable loss)

If you're recovering less than 80% of critical info, your persistence needs improvement.