How OpenClaw Memory Gives AI Agents 24/7 Long‑Term Memory

Memory storage

OpenClaw stores all conversation context in plain Markdown files under ~/.openclaw/workspace/. Example layout:

memory/
├── 2026-02-23.md
├── 2026-02-22.md
└── MEMORY.md

The files can be edited directly (e.g., fixing an IP address) and tracked with Git. Placing the workspace/ directory under version control makes every new piece of knowledge appear as a diff, and the whole memory can be copied to another machine with cp -r.

Two‑layer memory structure

Daily logs ( memory/2026-02-23.md etc.) are append‑only. At the start of a session OpenClaw automatically loads the logs for today and yesterday, providing recent context without loading the entire history.

Long‑term memory ( MEMORY.md) is manually maintained for preferences, important decisions, and sensitive data. It is loaded only in private chats, so group conversations never expose the contents.

Hybrid vector + BM25 search

OpenClaw provides two primitives: memory_search – semantic vector search. memory_get – direct file‑path read.

The hybrid mode combines vector similarity (weight 0.7) with BM25 keyword matching (weight 0.3). In a test searching for the environment variable name REDIS_PASSWORD:

Pure vector search returned no result because the token does not match the stored phrase.

Hybrid search returned the correct entry instantly thanks to BM25 exact matching.

Conversely, searching for "performance issue" demonstrated the opposite: Pure BM25 failed because the stored note used the phrase "response time too slow". Hybrid search succeeded because the vector component recognised the semantic similarity.

Temporal decay

To prevent stale entries from dominating results, OpenClaw applies a half‑life decay. The parameter halfLifeDays: 14 halves the weight of a memory every 14 days. Example weights: Today – 100 % Two weeks ago – 50 % One month ago – ~22 % Three months ago – ~1 % Files without a date (e.g., MEMORY.md or memory/projects.md ) are treated as permanent and are not decayed.

SQLite vs. QMD backend

SQLite (default) – zero‑configuration, suitable for a few hundred Markdown files. Ideal for personal use. QMD – an external search service that merges BM25, vector search, and re‑ranking. It delivers faster retrieval for large or multi‑directory corpora but requires installation and configuration. If QMD crashes, OpenClaw automatically falls back to the built‑in SQLite index.

Offline scenario with a local embedding model

pnpm approve-builds
# choose node-llama-cpp
pnpm rebuild node-llama-cpp

Configuration ( ~/.openclaw/config.json5 ) for a local GGUF model:

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "local",
        "local": {
          "modelPath": "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf"
        },
        "fallback": "none",
        "query": {
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.7,
            "textWeight": 0.3
          }
        },
        "extraPaths": ["~/notes/tech", "~/projects/docs"],
        "cache": {"enabled": true, "maxEntries": 50000}
      }
    }
  }
}

Common pitfalls observed:

Model download can be slow on restricted networks; a proxy or manual download may be required.

Initial indexing of dozens of files may take several minutes; subsequent runs are fast thanks to caching.

The local inference engine consumes 1–2 GB RAM, which may be prohibitive on very small machines.

Multi‑directory indexing with QMD

bun install -g https://github.com/tobi/qmd
brew install sqlite
qmd --version

Sample QMD configuration:

{
  "memory": {
    "backend": "qmd",
    "citations": "auto",
    "qmd": {
      "searchMode": "search",
      "includeDefaultMemory": true,
      "paths": [
        {"name": "projects", "path": "~/projects", "pattern": "**/*.md"},
        {"name": "notes", "path": "~/notes", "pattern": "**/*.md"}
      ],
      "update": {"interval": "5m", "debounceMs": 15000, "onBoot": true},
      "limits": {"maxResults": 10, "timeoutMs": 4000}
    }
  }
}

Advantages observed:

Automatic re‑indexing within 15 seconds after a file change (controlled by debounceMs).

Graceful fallback to SQLite if QMD becomes unavailable.

Better performance for large or multi‑directory corpora, at the cost of a more complex setup.

Long‑term project configuration with temporal decay

Configuration that enables hybrid search, MMR diversity re‑ranking, and half‑life decay using OpenAI embeddings:

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "openai",
        "model": "text-embedding-3-small",
        "remote": {"apiKey": "${OPENAI_API_KEY}"},
        "query": {
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.6,
            "textWeight": 0.4,
            "mmr": {"enabled": true, "lambda": 0.7},
            "temporalDecay": {"enabled": true, "halfLifeDays": 14}
          }
        },
        "extraPaths": ["~/projects/main-project/notes"]
      }
    }
  }
}

Result comparison (before → after) for three typical queries:

Search deployment process : previously returned a three‑month‑old flow; after enabling decay it returned the update from the previous week.

Search API configuration : previously mixed old and new entries; after decay the recent configuration ranked higher.

Historical decisions : previously required manual scrolling; after decay the older entries remain but with low weight, reducing noise.

Practical tips

Archive daily logs monthly, e.g.:

mkdir -p memory/archive/2026-01
mv memory/2026-01-*.md memory/archive/2026-01/

Store passwords, IPs, and other sensitive data only in MEMORY.md, which is loaded exclusively in private chats.

Use extraPaths to index project documentation and personal notes together, allowing the agent to draw from both conversation history and external resources.

Disable the memory plugin entirely when only plain file retrieval is needed:

{
  "plugins": {"slots": {"memory": "none"}}
}