Phase 7 / Ep 36: Memory System —— MEMORY.md and Hierarchical Memory Architecture

🎯 Learning Objective: Master OpenClaw's hierarchical long-term memory mechanism.

1. Why is Memory Needed?

A Session is short-term memory—it's archived after the conversation ends. But your Agent needs to remember things across Sessions: your name, your preferences, the progress of a project discussed last week.

This is the purpose of the Memory system.

2. Three-Layer Memory Model

graph TB
    subgraph Always["🔵 Always Loaded (Per Session)"]
        SOUL["SOUL.md\nPersonality Definition"]
        USER["USER.md\nUser Profile"]
        IDENTITY["IDENTITY.md\nSelf-Introduction"]
        BOOTSTRAP["BOOTSTRAP.md\nBootstrap Instructions"]
    end

    subgraph OnDemand["🟡 On-Demand Retrieval (memory_search)"]
        MemoryMD["MEMORY.md\nMemory Index"]
        Daily["memory/2026-04-06.md\nToday's Diary"]
        People["memory/people/eric.md\nPeople Profile"]
        Projects["memory/projects/app.md\nProject Profile"]
        Decisions["memory/decisions/db.md\nDecision Records"]
    end

    subgraph Session["🟢 Session Level"]
        Context["Current Context Window\nLast N Rounds of Conversation"]
        Compact["Compressed History Summary"]
    end

    Always -->|"Automatically Loaded Each Time"| Agent["🤖 Agent"]
    Agent -->|"Actively Retrieves"| OnDemand
    Agent -->|"Maintained in Real-time"| Session

3. MEMORY.md — The Memory Directory

# Long-Term Memory Index

## Important People
- Eric: My owner, an independent developer, see people/eric.md for details
- Alice: Eric's colleague, a backend engineer, see people/alice.md for details

## Active Projects
- OpenClaw Tutorial: Currently writing 40 episodes of tutorials, see projects/openclaw-tutorial.md for details
- T-Block App: A time management application, already launched, see projects/t-block.md for details

## Important Decisions
- Database Selection: Chose PostgreSQL, see decisions/db-choice.md for details
- Deployment Plan: Chose Hetzner + Docker, see decisions/deployment.md for details

## Common Q&A
- Eric prefers concise replies
- Eric's working hours are 9:00-23:00; do not actively disturb outside this period

4. Diary System memory/

The Agent automatically creates diary files daily:

# 2026-04-06 Diary

## Morning
- 08:30 Eric asked about new features in OpenClaw v3
- 09:15 Helped Eric search for MCP protocol documentation
- 10:00 Completed the outline review for Tutorial Ep 17

## Afternoon
- 14:00 Eric requested to deploy a new version
- 14:15 Collaborated with code-agent to complete testing
- 14:30 ops-agent completed deployment

## Learned Today
- Eric prefers to receive reports in Markdown format

5. Retrieval Tools

The Agent can actively retrieve memories during a conversation:

memory_search("Project Eric discussed last week")
→ Returns: Relevant content from projects/openclaw-tutorial.md

memory_get("decisions/db-choice.md")
→ Returns: The complete database selection decision record

Next Episode Preview: Ep 37, MemSkill in Practice—Installing and configuring Memory management related Skills, teaching the Agent to "remember" and "forget".