Stop Losing Context: A Guide to OpenClaw Memory

I used to get frustrated when my agents would “forget” a key decision halfway through a session. Context windows are getting bigger, but they still feel like a leaky bucket. If the conversation goes on long enough, the important stuff eventually spills out.

In OpenClaw, memory isn’t some black-box database. It’s just plain Markdown files sitting in your workspace. I like this because if the agent writes something wrong, I can just open the file and fix it myself. It makes the whole process transparent and easy to manage.

What You’ll Need

1. OpenClaw installed and a workspace initialized (usually at ~/.openclaw/workspace).
2. An API key for embeddings (OpenAI, Gemini, or Voyage) or a local setup for node-llama-cpp.

Quick Start

You can get memory up and running in about five minutes. Here is the fastest path to a persistent agent:

1. Create your memory files: Open your workspace and make sure you have a MEMORY.md file for long-term facts and a memory/ folder for daily logs.
2. Configure your provider: Add your embedding provider to your config.json5. If you have an OpenAI key, it often works out of the box.
3. Enable Hybrid Search: This combines keyword matching with semantic search so the agent can find exact terms and general concepts.
4. Test it out: Tell your agent, “Remember that we are using Port 8080 for this project.” Check your MEMORY.md to see if it wrote it down.

// Example config for OpenAI embeddings
agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      query: {
        hybrid: {
          enabled: true,
          vectorWeight: 0.7,
          textWeight: 0.3
        }
      }
    }
  }
}

How It Works

The agent uses two layers of memory. The daily logs (memory/YYYY-MM-DD.md) act like a diary of what happened recently. The MEMORY.md file is for durable facts, like your preferences or project architecture.

If a session gets too long, OpenClaw does something clever called a “memory flush.” Before it clears out old messages to save space, it asks the agent to write down anything important to the Markdown files. This way, the context stays small but the knowledge stays put.

Why Hybrid Search?

I recommend keeping hybrid search enabled. Vector search is great for finding ideas that are phrased differently, but it is surprisingly bad at finding specific IDs or code symbols. By mixing in BM25 (keyword search), the agent can find a specific Git commit hash or an environment variable name without getting confused.

Using Local Memory with QMD

If you want to keep everything on your own machine, you can use the QMD backend. It’s a local-first search tool that handles the indexing for you.

memory: {
  backend: "qmd",
  qmd: {
    includeDefaultMemory: true,
    update: { interval: "5m" }
  }
}

Troubleshooting

• Search returns nothing: Check if your workspace is marked as read-only. If the agent can’t write to the files, it can’t store new memories. Also, verify that your API key has access to the embedding models.
• Local mode is slow: On the first run, local models like Gemma-300M need to download. This can take a few minutes depending on your internet speed.
• Wrong results: If you changed your embedding provider or model, the old index is probably invalid. OpenClaw usually handles this, but you can manually delete the SQLite file in ~/.openclaw/memory/ to force a fresh start.
• SQLite errors: If you see errors about sqlite-vec, you might need to install a newer version of SQLite or use the JS fallback by disabling the vector extension in your config.

If you hit a wall, you can always ask the AI Setup Assistant for a hand with your specific config.

What’s Next

• Agent Workspace Concepts
• Session Compaction Details