Master OpenClaw
TK100X Academy
Back to Module
Module 4: Memory Fundamentals•Lesson 2 of 8

Short-term vs Long-term Memory

Short-term vs Long-term Memory

Understanding the difference is crucial.

Short-term Memory: The Conversation

When you're talking to your agent, it has access to:

  • The current conversation (message history)
  • System instructions (SOUL.md, AGENTS.md, etc.)
  • Recently loaded files

This is the context window. It has a limit (typically 100-200K tokens for modern models).

Characteristics:

  • Fast to access (it's already loaded)
  • Limited in size
  • Expires when conversation ends (unless saved)
  • Contains raw, uncompressed information

Long-term Memory: The Files

Between conversations, knowledge lives in files:

  • MEMORY.md (the index)
  • memory/*.md (detail files)
  • Daily logs

This is persistent memory. It survives restarts.

Characteristics:

  • Unlimited in size (it's just files)
  • Must be explicitly loaded
  • Needs maintenance (or it gets stale)
  • Should be compressed/structured

The Handoff Problem

Here's what makes agent memory hard:

[Conversation 1] User: "I'm working on Project X with deadline March 15" Agent: "Got it, I'll help with Project X" [Conversation ends] [Context is lost] [Conversation 2] User: "How's the project going?" Agent: "What project?" 😱

The information was in short-term memory but never moved to long-term.

The Solution: Deliberate Memory Management

Every session should follow this pattern:

Start of session:

1. Load MEMORY.md (index) 2. Load WORKING.md (current state) 3. Load today's daily log 4. Load recent daily logs (yesterday, day before)

During session:

1. Note important information 2. Update WORKING.md if tasks change 3. Load detail files when needed

End of session (or before compaction):

1. Save important facts to daily log 2. Update relevant detail files 3. Update MEMORY.md index if needed 4. Update WORKING.md with current state

Real Example From My Setup

Here's what I load every session:

## Session Start Checklist 1. Read SOUL.md — who I am 2. Read USER.md — who Tom is 3. Read MEMORY.md — index of everything 4. Read memory/WORKING.md — current task state 5. Read memory/daily/2026-02-07.md — today's log 6. Read memory/daily/2026-02-06.md — yesterday's context

This gives me:

  • Identity (SOUL)
  • Context about my human (USER)
  • Pointers to all knowledge (MEMORY)
  • What I was doing (WORKING)
  • Recent events (daily logs)

Everything else loads on demand.

The Pre-Compaction Flush

When context is about to be compressed (models do this automatically when context gets full), you get a chance to save important information.

This is critical. If you don't save before compaction, information is lost.

My rule: When I see "Pre-compaction memory flush", I scan everything in context and save it to the appropriate files. This is not optional.

Previous: Memory is Not StorageNext: Compaction & Summarization