Active Memory vs Stored Memory

People say, "the agent should remember this," as if memory were one big bucket. That is where the trouble starts.

In OpenClaw, memory behaves more like a workshop with shelves, sticky notes, and a quiet assistant who sometimes hands you the right note before you ask. Useful, yes. Mystical, no.

The official docs for concepts/active-memory, concepts/memory, and concepts/memory-search describe three different jobs: proactive recall before a reply, durable storage on disk, and search that retrieves relevant notes later. Mix those up, and you will misdiagnose half your memory problems.

The short version

• active memory = an optional blocking memory sub-agent that can surface relevant memory before the main reply
• stored memory = plain Markdown files such as MEMORY.md and memory/YYYY-MM-DD.md
• memory_search = the retrieval layer that finds saved notes later
• live context = what the model sees right now, which is not the same thing as saved memory

If you only keep one idea from this article, keep that one.

What active memory actually is

Active memory is not your whole memory system. It is an optional plugin-owned pre-reply pass.

Before the main assistant answer is generated, OpenClaw can run a bounded memory sub-agent for eligible conversational sessions. That sub-agent gets one job: check whether something already stored looks relevant enough to help the reply feel more natural.

That means active memory is about now. It is a just-in-time recall layer. If it finds something useful, OpenClaw injects a hidden untrusted memory prefix into the model input. If it finds nothing relevant, it returns nothing and the main reply continues normally.

A good analogy is a stage manager feeding a presenter one useful cue card right before they walk on stage. The cue card matters. But it is not the archive room where every script and rehearsal note lives.

What stored memory actually is

Stored memory is the durable layer. It lives on disk as plain files in the workspace.

• MEMORY.md for compact long-term memory, preferences, decisions, and stable facts
• memory/YYYY-MM-DD.md for daily notes, raw observations, session summaries, and working context
• DREAMS.md for optional dreaming summaries and review output

This is where many beginners expect magic and get bookkeeping instead. OpenClaw remembers by writing files. No hidden brain in the attic. If it is not stored on disk, it is just current conversation and may disappear from the live working window later.

That sounds less glamorous than the AI marketing version. It is also far more useful, because it tells you where to look when something is missing.

Why these are different systems

Stored memory answers, "What information exists?" Active memory answers, "Should any of that information be surfaced before this reply?"

Those are related questions, but they are not the same question.

You can have perfectly good stored memory and still get no active recall on a given turn. Maybe the memory is irrelevant. Maybe the plugin is off. Maybe the session is not eligible. Maybe the note was too vague to rank well. Existence does not guarantee retrieval.

That is the real mental shift. OpenClaw memory is closer to a good library than a telepathic hive mind. The book can be in the building and still not be on your desk.

Where memory_search fits

memory_search is the retrieval engine that helps OpenClaw find notes even when the wording is different from the original entry.

According to the docs, it can combine vector similarity and BM25 keyword search, then merge results. In plain English, that means it can match both meaning and exact terms.

• semantic match for ideas phrased differently
• keyword match for IDs, names, config keys, and exact strings
• optional ranking help such as temporal decay and MMR diversity

Active memory may use memory recall tools under the hood. The main agent may also use them directly. But the search layer still depends on the quality of what was stored, how it was indexed, and whether the current setup has the needed provider support.

Why recall fails even when you swear the agent knew it

This is the section people usually need after the first frustrating miss.

1. The fact was never promoted properly

If the detail stayed only in conversation and never made it into MEMORY.md or a daily note, there is nothing durable to retrieve later. A lot of "memory loss" is really "never written down."

2. The memory exists, but not in the live context

Saved memory and live context are different layers. A durable note can exist on disk without being loaded into the current prompt. That is normal.

3. Active memory is not running for this session

The active memory docs are pretty explicit here. The plugin must be enabled, the current agent must be targeted, the chat type must be allowed, and the session must be an eligible interactive persistent chat. Heartbeats, background work, one-shot runs, and internal helper paths are not where active memory normally shines.

4. Search quality or indexing is off

If embeddings are missing, stale, or badly configured, semantic recall gets weaker. If the note was poorly named or buried in noisy text, exact matching may also struggle. Retrieval systems are useful. They are not mind readers.

5. The memory was stored in the wrong layer

Stable preferences belong in MEMORY.md. Messy daily observations belong in dated notes. Action-sensitive follow-ups may belong in commitments or scheduled tasks instead of long-term memory. When everything goes everywhere, recall gets sloppier.

When to promote information

If you want better recall, promote information based on durability, not on panic.

Put it in MEMORY.md when it is stable

• user preferences that matter across sessions
• standing project decisions
• facts you expect to matter again later
• rules that should shape future private-session behavior

Put it in daily notes when it is raw or time-bound

• session summaries
• recent observations
• temporary details that may become important
• context you may want to distill later

Do not force long-term memory to do every job

Some future actions are better handled by commitments, scheduled tasks, or ordinary workflow state. Long-term memory is for durable context, not for pretending every reminder is a personality trait.

A practical operator workflow

If you want memory to feel reliable instead of spooky, use a boring process. Boring wins here.

/active-memory status
openclaw memory status
openclaw memory search "user preference or project fact"
/context detail

That quick sequence answers four useful questions:

• is proactive recall enabled for this session?
• is the memory index healthy?
• can the note be found at all?
• is the current live context missing something you assumed would be there?

Most memory issues stop looking mystical once you separate those checks.

Healthy habits that make memory work better

Keep MEMORY.md compact

The docs note that if MEMORY.md outgrows the bootstrap file budget, OpenClaw keeps the file on disk but truncates what gets injected into model context. That is a nasty little source of false confidence. The note exists, but not every turn sees all of it.

Distill, do not dump

Use daily notes as the messy workbench. Promote only the durable summary to long-term memory. This is basically kaizen for memory hygiene: small continuous cleanup beats one heroic rewrite later.

Write notes so retrieval has a chance

Vague notes are recall poison. Short, specific entries with concrete nouns, names, preferences, and decisions give both semantic and keyword search something useful to grab.

Treat active memory as enrichment, not proof

If a detail matters a lot, verify it. Active recall can improve continuity, but it is still a bounded helper, not a legal affidavit.

The mental model that keeps you sane

Use this model:

• stored memory is the archive
• memory_search is the librarian
• active memory is the assistant who places one likely-useful file on your desk before the meeting starts
• live context is the desk itself

If the archive is messy, the librarian struggles. If the assistant is off duty, nothing gets preloaded. If the desk is crowded, even good information may not stay visible. That is the whole game.

The operator payoff

Once you understand active memory versus stored memory, memory bugs stop feeling personal.

You stop saying, "the model forgot," and start asking better questions: Was the fact stored? Was it stored in the right layer? Was search healthy? Was active memory eligible here? Was the live context already too crowded?

That is a much better place to operate from. Less superstition, more systems thinking, and far fewer dramatic speeches about how the AI betrayed you.