Blog

OpenClaw memory: where it breaks for business facts

Aperisa · 8 min read

In OpenClaw's memory search, yesterday's correction ages and last spring's summary doesn't. Dated daily notes lose half their ranking weight every 30 days. MEMORY.md never decays, and it loads at the start of every session.

That is a sensible design for what OpenClaw memory is for: preferences, decisions, and context the agent picks up while working with you. It goes stale for business facts, the renewal dates and notice periods and invoice totals that live in documents other people change. Our view: keep memory for what the agent learns about you, and point a tool at a record for what your documents say.

This post is about memory-core's behavior, with file paths and config from the OpenClaw docs. It skips the basics.

How does OpenClaw memory work under the hood?

Per the memory overview, memory is Markdown in the agent workspace, ~/.openclaw/workspace by default. Four files matter:

  • USER.md: stable preferences and profile facts written as directives, loaded at session start on a separate small budget.
  • MEMORY.md: "the compact, curated layer for durable non-profile facts, standing decisions, and short summaries," loaded at session start.
  • memory/YYYY-MM-DD.md: daily working notes, indexed for memory_search and memory_get, not injected on every turn. Today's and yesterday's load on a bare /new or /reset.
  • DREAMS.md: the review surface for dreaming sweeps.

The default plugin is memory-core, SQLite-based, with PostgreSQL supported on the qualified runtime. Embeddings default to OpenAI, and memory.search.provider switches to Gemini, Voyage, Ollama, a local GGUF model and others. The memory search docs give the ranking rule:

hybrid relevance × recency decay × importance multiplier

followed by an MMR pass that reorders near-duplicate snippets.

Dreaming is on by default. It runs as a cron job managed by memory-core, scores short-term recall candidates, and promotes the ones that pass into MEMORY.md. You turn it off with plugins.entries.memory-core.config.dreaming.enabled: false.

Assembled from the OpenClaw docs as of October 2026. We haven't run it on a live install, so check it against your version.

openclaw memory status
openclaw memory search "harbor lane notice period"
openclaw memory index --force

Where does OpenClaw memory break for business facts?

In four places. None of them is a bug. They are tradeoffs that suit preferences and hurt facts.

It only knows what was written down

The docs are blunt: "The model only remembers what gets saved to disk; there is no hidden state." A clause in a signed amendment, an invoice in a vendor email, a start date moved in a calendar invite: none of it is in memory until the agent or you writes a note about it. And the note is a summary. It doesn't carry the document it came from, so you can't check it.

Staleness is built into the ranking

This is the one that surprises people. From the memory search docs: "Dated daily notes decay with a 30-day half-life; curated files such as MEMORY.md and USER.md are evergreen."

Walk through it with made-up data. In May, dreaming promotes "Harbor Lane: 30 days notice to cancel" into MEMORY.md. In August the client signs an amendment, and the agent writes "Harbor Lane amendment signed, notice now 60 days" into memory/2026-08-14.md. In October you ask on Telegram how much notice Harbor Lane needs.

The May line is already in the prompt, because MEMORY.md loads at session start. The August note is a little over two months old, so its ranking weight is below a quarter of where it started. It still qualifies, since minScore checks relevance before decay, but the docs say "an eligible older note can rank outside the returned window." The agent may answer 30 without ever searching. If it does search, the correction is competing at a discount.

Dreaming can supersede the old line if the August note gets promoted, and you can fix MEMORY.md by hand. Both work. Both depend on someone noticing.

Compaction is lossy, and the flush doesn't always run

Before compaction, OpenClaw runs a silent turn that reminds the agent to save context to memory. It is on by default (agents.defaults.compaction.memoryFlush.enabled). Two caveats from the docs:

  • When the safeguard summary can't fit everything, the fallback "is deliberately lossy," and "Older details, identifiers, and pending requests may therefore leave the model context."
  • "Sessions whose sandbox requires read-only or no workspace access skip the flush." If you followed the hardening advice and run a sandboxed reader with workspaceAccess: "none", that agent writes nothing durable before compaction.

The full transcript stays on disk. What the model sees on the next turn is the summary.

MEMORY.md has a budget

Paste contracts into MEMORY.md and it eventually crosses the bootstrap budget. The docs say OpenClaw "keeps the file on disk intact but truncates the copy injected into context." /context list and /context detail show raw versus injected size.

Is a better OpenClaw memory plugin the fix?

For conversation recall, sometimes. For business facts, mostly no.

The memory docs list Honcho and LanceDB as plugin engines. Third-party providers such as Supermemory and Memori offer OpenClaw integrations, and Supermemory's post ranks for this keyword with a comparison it ran itself. A better engine can recall what was said more reliably. It still recalls what was said. The amendment that never came up in chat is just as missing.

The closest built-in answer is memory-wiki, a bundled plugin that compiles knowledge into pages with "structured claims with evidence," provenance, and freshness fields such as lastRefreshedAt. That is the right shape: a claim, its evidence, and a date. But the memory wiki docs describe it as compiling from saved data and imported sources. You still have to get your documents into it and keep them current.

What pattern holds up?

Memory for preferences and decisions. A tool for facts, with the source attached.

Keep memory for what the agent learns about you

USER.md for "prefers invoices summarized in a table." MEMORY.md for "we stopped using the staging server on the old host." These are things only the conversation knows, and they rarely change behind your back.

Point a tool at the record of facts

Register a read-only data source under mcp.servers and pin its tools. The MCP docs show this shape for a remote server, here with a placeholder URL and tool names:

{
  mcp: {
    servers: {
      records: {
        url: "https://records.example.com/mcp",
        transport: "streamable-http",
        toolFilter: { include: ["search", "read_*"] },
      },
    },
  },
}

openclaw mcp doctor records --probe

Keep credentials out of config literals. The docs say to store sensitive headers through OpenClaw's secret mechanisms.

Write the routing rule into memory, as an action-sensitive note

The memory docs recommend capturing "when it is safe to act on the note, not just the fact itself." Use that to route questions, not to store answers:

Client contract terms, invoice amounts and dates: call the records tool and
reply with the document it returns. Do not answer these from MEMORY.md.
If the tool returns nothing, say so.

The docs also say memory "does not enforce policy." So this is guidance, and the tool is what makes it hold: the answer comes from a document you can open, not from a note a model wrote in May.

Make stale recall visible

OpenClaw's own recall guidance says "Partial, stale, or unavailable recall still requires disclosure." Ask for the source and its date in the reply. A Telegram answer that says "60 days, per Amendment 2 dated Aug 14" is one you can check from your phone. "30 days" with no source is one you can't.

Where does Aperisa fit?

Aperisa is one example of a record of facts outside memory. It reads Gmail, Drive, Calendar and Contacts with read-only Google access, plus the bank accounts you link, and keeps a searchable copy to answer from. It maps those records into one structured record and serves it through a read-only remote MCP server with no send, write or delete tools. It looks up your records instead of asking a model to recall them, and answers come with the email or document they came from.

Memory is for you, records are for facts

OpenClaw memory is good at the thing it was built for: remembering how you work. It goes stale on facts that live in documents, because evergreen notes don't age, corrections do, and compaction trims what doesn't fit. Keep the notebook for preferences and send fact questions to a tool that returns the document.

For keeping the same agent's inbox access safe, see OpenClaw Gmail read-only. For documents, see OpenClaw and Google Drive.

Aperisa connects as a remote MCP server over Streamable HTTP with a Bearer key, and each key can be limited by data area and level of detail. Try it out.

FAQ

How does OpenClaw memory search rank results? The builtin engine scores hybrid relevance times recency decay times an importance multiplier. Dated daily notes decay with a 30-day half-life. MEMORY.md, USER.md and undated files under memory/ are evergreen.

Which OpenClaw memory plugin should I use? memory-core is the default and is SQLite-based. The docs list Honcho and LanceDB as plugin engines, and memory-wiki as a bundled layer that adds claims with evidence and freshness tracking. All of them work on what gets saved into memory. None of them reads your inbox or Drive by itself.

Does OpenClaw lose facts during compaction? It can. A silent memory flush runs before compaction by default, but the docs call the fallback summary deliberately lossy, and say older details, identifiers and pending requests may leave the model context. Sessions with read-only or no workspace access skip the flush.

What should go in MEMORY.md? OpenClaw's docs describe it as the compact, curated layer for durable non-profile facts and standing decisions, not an archive. Keep preferences in USER.md and decisions in MEMORY.md, and send questions about contracts, invoices and dates to a tool that reads the source documents.

Sources

Questions

How does OpenClaw memory search rank results?

The builtin engine scores hybrid relevance times recency decay times an importance multiplier. Dated daily notes decay with a 30-day half-life. MEMORY.md, USER.md and undated files under memory/ are evergreen.

Which OpenClaw memory plugin should I use?

memory-core is the default and is SQLite-based. The docs list Honcho and LanceDB as plugin engines, and memory-wiki as a bundled layer that adds claims with evidence and freshness tracking. All of them work on what gets saved into memory. None of them reads your inbox or Drive by itself.

Does OpenClaw lose facts during compaction?

It can. A silent memory flush runs before compaction by default, but the docs call the fallback summary deliberately lossy, and say older details, identifiers and pending requests may leave the model context. Sessions with read-only or no workspace access skip the flush.

What should go in MEMORY.md?

OpenClaw's docs describe it as the compact, curated layer for durable non-profile facts and standing decisions, not an archive. Keep preferences in USER.md and decisions in MEMORY.md, and send questions about contracts, invoices and dates to a tool that reads the source documents.

Published

Keep reading