memory-system

Agent Memory System

When working with OpenClaw agent memory and context management.

MEMORY.md

Every agent has a MEMORY.md file that persists across sessions. The agent reads it at startup and updates it when it learns something important.

Structure

# {Agent Name} — Memory

## About Me
- **Role:** {role}
- **Created:** {date}

## Key Decisions
- {Important decision and why it was made}

## Preferences
- {User preferences discovered over time}

## Context
- {Project-specific context}

## Notes
- MEMORY.md is loaded at session start.
- Update this file when you learn something important.
- Keep it concise — this is your long-term memory.

Rules

• Max 200 lines. Beyond 200, the context becomes too large and the agent starts ignoring older entries.
• Semantic organization. Group by topic, not chronologically. "User Preferences" not "Feb 23 Notes."
• Update, don't append. When information changes, update the existing entry. Don't add a new line saying "actually, the previous thing was wrong."
• Delete stale info. If a decision was reversed or context is no longer relevant, remove it.

USER.md

Optional file for user-specific context that the agent should always know:

# User Context

## Products
- AI2SQL (ai2sql.io) — Text-to-SQL tool
- CrewClaw (crewclaw.com) — Agent deploy platform

## Preferences
- Never auto-commit or push without asking
- Respond in English only
- Keep responses concise

Context Loading Order

When an agent starts a session, it loads context in this order:

1. SOUL.md (identity and rules)
2. MEMORY.md (persistent memory)
3. USER.md (user context, if exists)
4. TOOLS.md (available commands, if exists)
5. HEARTBEAT.md (scheduled tasks, if exists)

Tips

• If the agent keeps forgetting something, add it to MEMORY.md or USER.md.
• If the agent is too slow to start, MEMORY.md is probably too long. Trim it.
• Use MEMORY.md for things the agent learned. Use USER.md for things you want to tell the agent.