Curating MEMORY.md

+15 Mana ✨
OpenClaw Memory Management(DOCUMENTATION)OpenClaw MEMORY.md Reference(DOCUMENTATION)

Introduction

MEMORY.md is the agent's long-term knowledge store, accumulating facts, decisions, and patterns across conversations. Unlike bootstrap files that you author deliberately, MEMORY.md grows organically as the agent records what it learns. Curating this file effectively is the difference between an agent that gets smarter over time and one that becomes cluttered with irrelevant noise.

Key Concepts

  • Long-Term Memory: Persistent knowledge that survives across sessions, stored in MEMORY.md
  • Daily Logs: Timestamped entries the agent writes during conversations, capturing decisions and observations
  • Memory Curation: The practice of reviewing, organizing, and pruning MEMORY.md to keep it useful
  • Signal vs Noise: Distinguishing valuable knowledge (architectural decisions, user preferences) from ephemeral details (debugging steps, one-off questions)
  • Memory Directives: Rules in AGENTS.md that guide what the agent writes to MEMORY.md

Real World Context

After three months of daily use, an agent's MEMORY.md has grown to 800 lines. It contains valuable architectural decisions alongside dozens of irrelevant entries like "User asked about weather API" and "Helped debug a typo in line 42 of server.ts". The useful knowledge is buried under noise. Regular curation would have kept the file focused and within the token budget.

Deep Dive

MEMORY.md serves as the agent's notebook. During conversations, the agent appends entries based on the memory directives in AGENTS.md. Over time, this file can grow significantly.

Here is what a well-curated MEMORY.md looks like:

markdown
# Project Architecture Decisions

- 2026-01-15: Decided to use event sourcing for the order service
  instead of CRUD. Rationale: audit trail requirement from compliance.
- 2026-01-22: Chose Redis Streams over Kafka for event bus.
  Rationale: simpler ops, sufficient throughput for current scale.
- 2026-02-03: Migrated from REST to gRPC for inter-service communication.
  Rationale: type safety and performance for high-frequency calls.

# User Preferences (Sarah)

- Prefers table-driven tests in Go over individual test functions
- Wants all error messages to include request IDs for tracing
- Dislikes comments that restate what the code does

# Codebase Patterns

- Error handling: always use `apperror.Wrap(err, "context")` pattern
- Database queries: use sqlc, never raw SQL strings
- API responses: always include `request_id` and `timestamp` fields

# Known Issues

- The payment service has a race condition in concurrent refund processing
  (ticket PLAT-2847, assigned to James)
- Memory leak in WebSocket handler when clients disconnect without closing

This MEMORY.md is organized by category, contains dated entries for decisions, and focuses exclusively on information that actively improves the agent's future responses.

Contrast this with a poorly curated MEMORY.md:

markdown
- Helped user fix a typo
- User asked about Go syntax
- Discussed deployment options
- Fixed a bug
- User prefers Go
- Something about Redis
- Reviewed PR #234

These entries are too vague to be useful. "Discussed deployment options" does not capture what was decided. "Fixed a bug" does not say which bug or how.

When to write to MEMORY.md versus daily logs:

markdown
Write to MEMORY.md (permanent knowledge):
- Architectural decisions and their rationale
- Discovered codebase patterns and conventions
- User preferences that affect future responses
- Known issues and their status
- Important project context (tech stack changes, team structure)

Write to daily logs (ephemeral context):
- Step-by-step debugging sessions
- Exploratory conversations without decisions
- Temporary workarounds being tested
- One-off questions unrelated to the project

The distinction is durability. If the information will be valuable next week, it goes in MEMORY.md. If it is only relevant today, it goes in a daily log.

Common Pitfalls

  • Never reviewing MEMORY.md: Letting the file grow unchecked leads to token budget issues and noise drowning out signal.
  • Writing vague entries: Entries like "discussed deployment" are worthless without specifics. Always capture the decision, rationale, and context.
  • Storing sensitive information: MEMORY.md is part of the system prompt. Never store credentials, personal data, or security-sensitive information.

Best Practices

  • Review MEMORY.md monthly: Remove outdated entries, consolidate redundant ones, and reorganize for clarity.
  • Use categories with headers: Group entries under clear headers (Architecture, Preferences, Patterns, Issues) for easy scanning.
  • Date all decision entries: Timestamps help track when decisions were made and whether they are still current.

Summary

  • MEMORY.md is the agent's long-term knowledge store that grows across conversations
  • Well-curated memory uses categories, dates, and specific details rather than vague notes
  • Distinguish between permanent knowledge (MEMORY.md) and ephemeral context (daily logs)
  • Review and prune monthly to prevent noise accumulation and token budget overruns
  • Never store sensitive information in MEMORY.md since it is part of the system prompt
✓ Completed