AI Agent Memory and Session Loss Guide

Memory loss is the most frustrating failure mode for AI agents and their users. The agent appears to be working, then reveals it forgot a decision made three messages ago, repeats a step that was already done, or loses all context after a restart.

Most memory failures are architectural, not model limitations — the fix is usually in how state is persisted, not the model itself.

Why Agents Forget

Fix 1: File-Based Session Persistence (Most Important)

The most common cause of agent amnesia: state stored only in memory. Gateway restart = everything gone.

# openclaw.config.yaml
memory:
  persist: true
  backend: file
  path: ~/.openclaw/sessions/
  compress: true
  auto_save_interval_ms: 30000  # Save every 30 seconds

After this, sessions survive gateway restarts. The agent picks up exactly where it left off.

Fix 2: Explicit Memory Checkpoints

For critical decisions or completed subtasks, save explicit checkpoints:

# In your agent skill or script
import openclaw

async def handle_step_completion(step_name, result):
    # Save checkpoint after each completed step
    await openclaw.session.checkpoint({
        'step': step_name,
        'result': result,
        'timestamp': datetime.utcnow().isoformat(),
        'next_step': get_next_step(step_name)
    })
    print(f"Checkpoint saved: {step_name}")

On restart, the agent reads the last checkpoint and resumes from there instead of starting over.

Fix 3: Workspace File as External Memory

The most robust memory pattern — write to files, not just conversation context:

Agent instruction pattern:

After completing each subtask:
1. Update ./progress.md with what was done and what remains
2. Write decisions to ./decisions.md with rationale
3. Save all intermediate outputs to ./workspace/

At the start of each session:
1. Read ./progress.md to understand current state
2. Read ./decisions.md to avoid re-deciding already-settled questions
3. Continue from the last incomplete subtask

This pattern makes the agent’s memory inspectable, debuggable, and crash-resistant.

Fix 4: Cross-Session Memory Sharing

For agents that need to maintain context across completely separate sessions (different users, different days):

memory:
  backend: sqlite        # Or: redis, postgres
  connection: ~/.openclaw/shared-memory.db
  namespace: project-alpha  # Separate memory spaces per project
  ttl_days: 30             # Auto-expire old memories

All sessions with the same namespace share memory. Agent can reference “what we decided last week” from a fresh session.

The Session Handoff Problem

Symptom: Agent in session A completes 60% of a task. Session B starts (different terminal, new connection). Session B doesn’t know what A did.

Root cause: Session IDs are generated per-connection. Without explicit binding, sessions are isolated.

Fix:

# Pass session ID explicitly when resuming work
openclaw start --session-id $PREVIOUS_SESSION_ID

# Or list recent sessions and choose
openclaw session list --last 10
openclaw session resume session-2026-04-14-abc123

Add to your workflow: always save the session ID at the end of each work block.

Fix 5: Summarize on Context Warning

When the context window approaches its limit, summarize to preserve key facts:

context:
  on_window_warning:
    threshold: 0.75          # At 75% context usage
    action: summarize
    preserve_facts:
      - decisions
      - completed_steps
      - constraints
      - next_steps

The summary replaces older turns but keeps the essential information the agent needs to continue.

Debugging Memory Issues

Check what the agent actually has in memory

openclaw session inspect $SESSION_ID --show-context | head -100

Look for:

• Are the critical decisions from earlier turns still present?
• Did summarization drop important facts?
• What’s the current token count vs. the limit?

Check if persistence is actually working

# Kill and restart the gateway
openclaw gateway stop
openclaw gateway start

# Resume the session
openclaw session resume $SESSION_ID

# Check if the agent knows what it was doing
openclaw chat --session $SESSION_ID "What was the last thing you completed?"

If the agent answers correctly, persistence is working. If it starts fresh, check the persist config.

Memory Architecture Patterns

Pattern 1: Ephemeral (Default — Don’t Use for Long Tasks)

• State: in-memory only
• Survives: nothing (gateway restart = full loss)
• Good for: throwaway tasks under 10 minutes

Pattern 2: File-Persisted (Recommended)

• State: disk file, auto-saved every 30s
• Survives: gateway restart, system reboot
• Good for: any task longer than 10 minutes

Pattern 3: Checkpointed (Best for Critical Tasks)

• State: file + explicit checkpoints at each step
• Survives: crashes, partial failures, long pauses
• Good for: multi-hour tasks, tasks with external side effects

Pattern 4: Shared Store (For Multi-Agent or Long-Running Projects)

• State: SQLite/Redis/Postgres shared DB
• Survives: everything, accessible from any session
• Good for: ongoing projects, multi-agent coordination

Common Questions

Why does the agent repeat steps it already completed?

The completed step fell out of context (window overflow) or was never persisted. Fix: Use checkpoints + write progress to ./progress.md after each step.

Why does the agent contradict an earlier decision?

Decision was made in a turn that got summarized or truncated. Fix: Write decisions to ./decisions.md and instruct the agent to read it at the start of each session.

Why does memory work in one session but not the next?

Session ID changed between sessions, so they’re isolated. Fix: Use --session-id to explicitly bind sessions, or use shared-store backend.

← View all memory/session solutions