OpenClaw Memory.md: How the Memory File System Works [2026]

How Memory Works in OpenClaw

Memory is what separates a useful AI agent from a stateless chatbot. Without memory, every conversation starts from zero. With memory, the agent knows your preferences, your clients, your processes, and your history.

OpenClaw's memory system is built on a simple but powerful principle: all memories are plain Markdown files stored on disk. There is no proprietary database, no vector store dependency (though one can optionally be used), and no opaque binary format. Every memory is a human-readable .md file that you can open, edit, and understand with any text editor.

When the agent has a conversation, it does two things with memory:

1. Reads: Before generating a response, OpenClaw searches the memory directory for files relevant to the current conversation. Matching memories are injected into the AI model's context window, giving the agent background knowledge.
2. Writes: After a conversation that contains noteworthy information (a new client name, a preference, a decision), the agent creates or updates a memory file to store that information for future use.

This read-write cycle creates a learning loop. Over time, your agent accumulates knowledge about you, your business, and your operations. The more conversations you have, the more useful the agent becomes.

The Memory File Format (QMD)

OpenClaw memory files use a format sometimes called QMD (Queryable Markdown). It is standard Markdown with YAML frontmatter — nothing proprietary or unusual. Here is an example:

---
title: Client - Acme Corp
created: 2026-02-15
updated: 2026-03-20
source: whatsapp_conversation
tags: [client, active, enterprise]
priority: high
---

# Acme Corp

## Contact Information
- Primary contact: Jane Smith (CEO)
- Email: jane@acmecorp.com
- Phone: +1-555-0123
- Preferred communication: WhatsApp

## Project History
- **Feb 2026:** Initial engagement. AI automation for customer support.
- **Mar 2026:** Deployed OpenClaw agent for their helpdesk. 500 tickets/month.

## Preferences
- Prefers brief, bullet-point updates
- Weekly status reports on Fridays
- Budget-conscious — always compare cost options

## Notes
- Referred by Bob at XYZ Corp
- Interested in expanding to multi-agent setup in Q2

The frontmatter fields are used by the memory search system:

• title: Used for keyword matching and display
• created / updated: Used for recency ranking and pruning
• source: Where the memory came from (conversation, manual entry, import)
• tags: Used for filtering and categorization
• priority: High-priority memories are more likely to be retrieved

Memory Search

When OpenClaw needs to find relevant memories, it uses a multi-step search process:

Step 1 — Keyword extraction: The current message is analyzed to extract key terms. "What's the status of the Acme project?" extracts "Acme" and "project" and "status."

Step 2 — File name matching: Memory files with matching terms in their filename or title frontmatter are scored highly. A file named client_acme_corp.md would match immediately.

Step 3 — Tag matching: Memory files with matching tags are included. A search for client-related information would match files tagged [client].

Step 4 — Content search: The body of memory files is searched for matching keywords. This catches memories that are relevant but do not have matching filenames or tags.

Step 5 — Semantic search (3.22+): In version 3.22 and later, OpenClaw optionally uses embedding-based semantic search. This finds memories that are conceptually related even if they do not share exact keywords. For example, a search for "revenue performance" might match a memory about "monthly income reports" even though the words are different.

To enable semantic search:

OPENCLAW_MEMORY_SEMANTIC_SEARCH=true
OPENCLAW_MEMORY_EMBEDDING_MODEL=text-embedding-3-small

Semantic search uses an embedding model to convert memory content and queries into vectors. This adds a small API cost (roughly $0.001 per search) but significantly improves memory retrieval accuracy.

Step 6 — Ranking and selection: All matching memories are ranked by relevance (keyword match score + semantic similarity + recency + priority). The top N memories (configurable, default 5) are included in the AI model's context window.

Manual Editing

One of the biggest advantages of the .md memory format is that you can edit memories directly. This is useful for:

• Correcting errors: If the agent stored incorrect information, open the file and fix it.
• Adding information: Bulk-load knowledge by creating memory files manually. For example, paste your client list, product catalog, or company policies into properly formatted .md files.
• Restructuring: Merge related memories into a single file, split a large file into topical files, or reorganize the directory structure.
• Removing sensitive data: If the agent stored something it should not have (a password, a private conversation), delete it from the memory file.

To edit memories on a Docker deployment:

# Find the memory directory
docker compose exec openclaw ls /data/memory/

# Edit a file directly in the container
docker compose exec openclaw nano /data/memory/client_acme_corp.md

# Or copy to your host, edit locally, and copy back
docker cp openclaw:/data/memory/client_acme_corp.md ./
# ... edit with your preferred editor ...
docker cp ./client_acme_corp.md openclaw:/data/memory/

Changes take effect immediately — there is no need to restart OpenClaw. The next time the memory system searches for relevant files, it will read the updated content.

Automatic Memory Creation

OpenClaw automatically creates and updates memory files based on conversations. The agent decides when something is worth remembering based on configurable criteria:

• New entities: When a new person, company, or project is mentioned for the first time, the agent creates a memory file.
• Preferences: When you express a preference ("I prefer weekly reports on Friday," "Always use bullet points"), the agent stores it.
• Decisions: When you make a decision ("Let's go with the $5K package for Acme"), the agent records it.
• Facts: When you share factual information ("My birthday is March 15," "Our fiscal year starts in July"), the agent stores it.

You can control automatic memory creation with these environment variables:

# Enable/disable automatic memory creation
OPENCLAW_MEMORY_AUTO_CREATE=true

# Minimum conversation length before memories are created (messages)
OPENCLAW_MEMORY_MIN_MESSAGES=3

# How aggressively the agent creates memories
# conservative: only facts and explicit preferences
# moderate: facts, preferences, and inferred patterns (default)
# aggressive: everything potentially useful
OPENCLAW_MEMORY_AGGRESSIVENESS=moderate

Organizing Your Memory Directory

A well-organized memory directory makes retrieval faster and more accurate. Here is a recommended structure:

/data/memory/
├── clients/
│   ├── acme_corp.md
│   ├── xyz_startup.md
│   └── jones_law_firm.md
├── people/
│   ├── jane_smith.md
│   └── bob_johnson.md
├── projects/
│   ├── acme_ai_automation.md
│   └── xyz_website_redesign.md
├── preferences/
│   ├── communication_style.md
│   ├── scheduling_rules.md
│   └── reporting_format.md
├── company/
│   ├── policies.md
│   ├── products.md
│   └── pricing.md
└── general/
    ├── daily_notes.md
    └── meeting_notes_march.md

Tips for organization:

• Use descriptive file names — the file name is the first thing the search system checks
• Use subdirectories to group related memories
• Keep one topic per file rather than one event per file
• Update existing files rather than creating duplicates
• Use consistent naming conventions (lowercase, underscores, no special characters)

Memory Limits and Performance

There is no hard limit on the number of memory files, but practical limits exist:

The context window is another limit. Each memory file injected into the context uses tokens. If you inject 5 large memory files, that could consume 5,000-10,000 tokens of context, leaving less room for the conversation itself. Configure the maximum memory tokens:

# Maximum tokens allocated to memory in the context window
OPENCLAW_MEMORY_MAX_TOKENS=4000

# Maximum number of memory files to inject per conversation turn
OPENCLAW_MEMORY_MAX_FILES=5

Pruning Old Memories

Over months of operation, your memory directory will accumulate outdated, redundant, and low-value memories. Regular pruning keeps the system fast and relevant.

Manual pruning: Periodically (monthly is a good cadence) review your memory directory and delete or archive memories that are no longer relevant. Old meeting notes, completed project files, and information about departed clients can be moved to an archive directory that OpenClaw does not search.

# Create an archive directory (not searched by OpenClaw)
mkdir -p /data/memory_archive/

# Move old files
mv /data/memory/projects/completed_project_2025.md /data/memory_archive/

Automated pruning: OpenClaw 3.23 introduced an automatic pruning feature that can be enabled:

# Enable automatic pruning
OPENCLAW_MEMORY_AUTO_PRUNE=true

# Prune memories not accessed in N days
OPENCLAW_MEMORY_PRUNE_DAYS=90

# Move pruned files to archive (instead of deleting)
OPENCLAW_MEMORY_PRUNE_ARCHIVE=true

With auto-pruning enabled, memories that have not been accessed (read or updated) in 90 days are moved to the archive directory. This keeps the active memory directory lean while preserving data in case you need it later.

Deduplication: If you notice the agent creating duplicate memories (multiple files about the same client, for example), you can merge them manually or run the deduplication tool:

# Scan for potential duplicates
npx openclaw memory dedupe --dry-run

# Merge duplicates (creates backup first)
npx openclaw memory dedupe --merge

A well-maintained memory system is the difference between an agent that is marginally useful and one that is indispensable. Invest time in organizing and pruning your memories, and the agent's performance will reflect that investment directly.