5 Ways to Give OpenClaw Persistent Memory That Actually Works

OpenClaw's default memory works fine for the first few weeks. Then it starts falling apart. Search results get noisier as files accumulate. The agent retrieves text from old projects when you're asking about current ones. It knows facts exist somewhere but can't connect them — it might know Alice is on your team and that your auth system needs work, but it can't connect those two things.

The core issue isn't that OpenClaw can't store information. It's that storing and retrieving are different problems, and the default system only does one of them well.

Here are five methods for giving your OpenClaw agent memory that persists across sessions and actually improves over time. They range from a 5-minute setup to a full knowledge graph architecture. Most serious users end up combining two or three of these, each handling a different type of information. If your memory is currently broken, start with our OpenClaw Memory Not Working: Fix Guide to diagnose the issue first. For the complete copy-paste configuration files that underpin most of these methods, see our OpenClaw Memory Configuration Guide. This guide is part of our Complete Guide to OpenClaw.

Method 1: Structured Memory Folders

OpenClaw's simplest persistent memory method uses a dedicated folder structure of organised markdown files that gives operators full transparency over what the agent remembers.

Best for: Getting started immediately. Full transparency. Works with any LLM provider.

Setup time: 5 minutes.

This is the simplest approach, and it's genuinely underrated. You create a dedicated folder structure in your workspace specifically designed to organise persistent context.

The structure that works well for most users:

memory/
├── projects/
│   ├── project-alpha/
│   │   ├── goals.md
│   │   ├── decisions.md
│   │   └── current-status.md
│   └── project-beta/
│       ├── goals.md
│       └── decisions.md
├── preferences/
│   ├── coding-style.md
│   └── communication.md
└── knowledge/
    ├── research-notes.md
    └── reference.md

Then instruct the agent to use these files. Add to your AGENTS.md:

## Memory Management
- At the end of every task: update the relevant files in the memory folder
- When a decision is made: record it in the project's decisions.md with date and reasoning
- When preferences are expressed: update preferences/ files

This isn't sophisticated. It's not vector search or semantic retrieval. But it has three major advantages: you can open those markdown files and see exactly what your agent remembers (no black box), it works regardless of which LLM provider you use, and you control the structure — you decide what's worth remembering rather than hoping automated extraction gets it right.

For most users who are just getting started with OpenClaw, this is the right first step.

How Do You Configure OpenClaw's Built-In Memory Search?

OpenClaw's built-in memory_search function provides natural language recall across stored memories, but most users never get it working properly because it fails silently when the embedding model download is interrupted.

Best for: Natural language recall within OpenClaw. Quick lookups across memory files.

Setup time: 10-15 minutes.

OpenClaw has a built-in memory_search function designed for searching through stored memories, past context, and things you've told the agent to remember. When it works, it's seamless — you can say "remember that I prefer TypeScript" and later the agent retrieves that preference automatically.

The problem is that most users never get it working properly, and it fails silently.

The critical thing to know: memory search requires an embedding model. The built-in local provider downloads a small model automatically, but if that download failed, search silently does nothing. Your agent just won't remember things and you'll have no idea why.

Here's the configuration that works:

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "local",
        "local": {
          "modelPath": "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf"
        },
        "query": {
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.7,
            "textWeight": 0.3
          }
        },
        "cache": {
          "enabled": true
        }
      }
    }
  }
}

Enable hybrid search. This combines keyword matching (finds "pricing" when you search for "pricing") with semantic matching (finds "we picked the $29 tier" when you search for "pricing decision"). The 70/30 vector-to-text split works as a solid default.

Even with search configured, the agent won't use it unless you tell it to. Add a retrieval rule to AGENTS.md:

## Retrieval Protocol
Before doing non-trivial work:
1. memory_search for the project/topic/user preference
2. memory_get the referenced file if needed
3. Then proceed

The local embedding model is free and runs entirely on your machine. No API calls, no ongoing cost. For most users with a reasonable volume of memory files, this is all the search infrastructure you need.

What Is QMD and When Should You Use It with OpenClaw?

QMD (Query Markdown Documents) is an experimental OpenClaw memory backend built by Tobi Lutke that replaces the built-in indexer and handles thousands of files, Obsidian vaults, and past session transcripts.

Best for: Searching thousands of files. Indexing Obsidian vaults, project docs, past session transcripts.

Setup time: 15-20 minutes.

QMD (Query Markdown Documents) is an experimental memory backend built by Tobi Lütke that replaces OpenClaw's built-in indexer. Where the default system works well for a few dozen files, QMD is designed for thousands.

The conceptual difference: the built-in search is the agent checking its own diary. QMD is the agent searching your entire knowledge base — your Obsidian vault, project documentation, meeting notes, past session transcripts, everything.

{
  "memory": {
    "backend": "qmd",
    "qmd": {
      "searchMode": "search",
      "includeDefaultMemory": true,
      "sessions": {
        "enabled": true
      },
      "paths": [
        { "name": "obsidian", "path": "~/Documents/Obsidian", "pattern": "**/*.md" },
        { "name": "projects", "path": "~/Documents/Projects", "pattern": "**/*.md" }
      ]
    }
  }
}

QMD starts with fast BM25 keyword search by default — sub-second results, no ML models needed, no cold-start risk. The tradeoff is it won't find "the API pricing decision" if you stored it as "we chose the $29/month tier." For that, you need to enable semantic search mode, which loads ML models and takes longer on first use. Start with keyword mode, upgrade if you're hitting missed results.

A significant practical advantage: QMD returns small, relevant snippets instead of entire files. The agent doesn't dump a 50-page document into context just to find one sentence. This directly helps avoid triggering compaction — a real concern when you're indexing large knowledge bases.

The Obsidian integration is where QMD really shines. Point QMD at your Obsidian vault and your agent can search everything — notes, projects, daily journals, research, reference material. It's free, runs locally, and syncs automatically as files change.

One important gotcha: QMD defaults to DM-only scope. If you're running OpenClaw in Discord or Slack group channels and memory search seems broken, check the scope configuration.

If you want even tighter Obsidian integration — having the agent create, organise, and maintain notes inside your vault structure — that requires some additional setup in your AGENTS.md with rules about how to handle the vault's folder structure and WikiLinks. For the full step-by-step walkthrough, see our dedicated OpenClaw Obsidian Integration Guide. But even basic QMD search over an existing vault is a massive upgrade.

How Does Mem0 Give OpenClaw Automatic Memory?

Mem0 takes a fundamentally different approach to OpenClaw memory by automatically observing every conversation, extracting meaningful information, and surfacing it when contextually relevant without any manual intervention.

Best for: Automated long-term memory with zero maintenance. The "set it and forget it" option.

Setup time: 10 minutes.

Every other method so far relies on either you or the agent explicitly deciding what to save. Mem0 takes a fundamentally different approach: it watches every conversation, automatically extracts what matters, and brings it back when relevant.

Mem0 uses vector search to store information not as exact text but as mathematical representations of meaning. So if you told your agent three weeks ago "our client prefers minimalist design" and today you ask about design direction, Mem0 surfaces that memory even though you used completely different words.

The plugin installs with a single command and works in three steps automatically: it observes conversations in the background, extracts meaningful information (preferences, decisions, facts, project details), stores them as vector embeddings, and retrieves them at the start of each conversation or whenever they're contextually relevant.

The key difference from built-in memory search: you don't need to tell the agent what to save or when to search. Mem0 handles both automatically. This directly solves the two most common memory failures — important information never getting written to a file, and the agent not checking its notes before acting.

The trade-off is that it's a third-party dependency. You're adding a plugin and potentially sending data through external infrastructure, so read their privacy documentation if that matters for your use case. And like any automated system, it might occasionally surface irrelevant memories or miss something you wanted captured.

But for users who want persistent memory without building habits around manual saves and retrieval rules, Mem0 is the strongest option available.

Method 5: Knowledge Graphs with Cognee

Cognee solves a problem none of the other OpenClaw memory methods address: understanding relationships between entities, such as knowing that Sarah manages the auth team when you ask about API permissions.

Best for: Complex projects where relationships between entities matter. Enterprise settings, multi-agent teams, large codebases.

Setup time: 30 minutes.

This solves a problem that none of the other methods address: relationships.

Here's the scenario. On Monday, you mention that Sarah manages the auth team. On Wednesday, you ask "who handles API permissions?" Every other method here will search for similar text — they know Sarah exists, they know the auth team exists, but they can't connect them. They retrieve both memories but don't understand that Sarah manages auth.

Cognee is an open-source knowledge engine that makes your documents both searchable by meaning and connected by relationships. When you say "Sarah manages the auth team," Cognee extracts structured data: Sarah (Person) → manages → Auth Team (Team). Later, when you ask about API permissions, it traverses the graph: Auth Permissions → related to → Auth Team → managed by → Sarah.

This is fundamentally different from semantic search. The graph understands structure, not just similarity.

Cognee installs as an OpenClaw plugin and operates in three phases: on startup it scans your memory files and processes them into the graph, before each agent run it searches the graph for relevant memories (traversing relationships, not just matching text), and after each run it syncs any changes back so the graph stays current.

Your markdown files stay exactly as they are. The graph runs alongside them as an additional retrieval layer.

Setting it up requires running Cognee locally in Docker and installing the integration plugin:

# docker-compose for local Cognee
# Then install: npm install @cognee/openclaw-plugin
# Configure in ~/.openclaw/config.yaml

The honest assessment: Cognee is powerful but adds complexity. For straightforward personal agent setups, it's likely overkill. For teams managing complex projects with lots of interconnected people, systems, and dependencies, it solves a real problem that simpler methods can't.

Bonus: SQLite for Structured Data

OpenClaw can natively read from and write to a SQLite database without plugins or extra API keys, making it ideal for dense structured data like API endpoint catalogues and product records.: OpenClaw can natively read from and write to a SQLite database. No plugin needed. No extra API key. It's just there.

This matters when you're working with dense, structured data — hundreds of API endpoints, product catalogues, customer records, financial figures. Markdown files fall apart with that kind of data. Vector search is great for fuzzy retrieval, but sometimes you need exact queries: "show me every API endpoint that uses POST and requires authentication." That's a SQL query, and SQL is very good at it.

Tell your agent to create a SQLite database for structured data and it will handle the schema, population, and querying. Because SQLite is a single file, it's portable, persistent, and survives session resets. You can even version-control it.

Which Methods to Combine

The best OpenClaw setups use two or three methods together, each handling a different type of information:

For most users: Start with Method 1 (structured folders) for transparency, add Method 2 (built-in search) for natural language recall. This covers 90% of use cases.

For knowledge-heavy workflows: Add Method 3 (QMD) to search your Obsidian vault or large document collections. This is particularly powerful if you already use Obsidian for note-taking.

For zero-maintenance memory: Add Method 4 (Mem0) if you want automatic capture without building manual save habits.

For complex team projects: Layer Method 5 (Cognee) when relationships between entities are critical to your work.

For structured data: Add SQLite whenever you're dealing with dense, queryable datasets alongside conversational memory.

The underlying principle across all of these is the same: if it's not written to a file (or a database), it doesn't exist. Every method here is a different strategy for getting important information out of the ephemeral context window and into durable storage where it can be found again.

The Memory Architecture Summary

Start with what's simple. Add layers when the simple approach isn't enough. And whatever you do, make sure your agent has a rule in AGENTS.md to actually search memory before acting — because the most sophisticated storage system in the world is useless if the agent doesn't check it. Also keep in mind that your memory architecture directly impacts token costs — larger memory files and more frequent compaction mean higher API bills. See our OpenClaw Token Cost Reduction Guide for strategies to balance memory quality with cost efficiency.

Don't Want to Build This Yourself?

At Remote OpenClaw, we deploy fully configured OpenClaw instances on your own VPS — with optimised memory, security hardening, Tailscale networking, and integrations with Telegram, WhatsApp, or Slack. Your agent runs 24/7 with memory that works from day one.

Book a free strategy call →