Memory System: Making Claw Remember You

The commands in the previous lesson all take effect "on the spot"; this lesson covers how to make the effects** stick around**. OpenClaw's memory system design philosophy can be summed up in one sentence: no hidden state—Claw only remembers what is written to disk, and what's on disk is plain Markdown files you can open with any text editor (by default in ~/.openclaw/workspace).

This means two things: to make Claw remember you, just say it directly ("Remember: I prefer TypeScript"); to check or modify what it remembers, just open the file and look. This lesson covers memory writing, recall, automatic consolidation, cross-session sharing, and migration all at once, with all examples based on OpenClaw v2026.10.9.

What You'll Be Able to Do After This Lesson

• Say "Remember: ..." to have Claw write your preferences and facts into USER.md / MEMORY.md
• Use /new to start a new session and verify that cross-session memory persists, and articulate the boundary between session context and long-term memory
• Have Claw use memory_search to retrieve old topics from the journal layer (Chinese trigram tokenization natively supported)
• Turn on 2.0's cross-session recall: private chats with the same agent remember each other (on by default in personal installations)
• Understand what dreaming's automatic consolidation does, and import old memories from Claude Code / Codex / Hermes

Your Current Predicament

• Having to introduce yourself all over again every new session: "I use TypeScript" "Answer in Chinese" "Don't be verbose"
• The material it looked up last week and the plans it settled on—when you ask this week, it looks innocent: "We never talked about that"
• You migrated from Claude Code, where you'd accumulated months of memories—do you really have to rebuild them from scratch here?

When to Use This Technique

When you need:

• Claw to remember your preferences, project background, and past decisions across sessions
• It to dig through old notes on its own to answer questions like "How did we decide this before?"
• Memory that's inspectable and editable—if something goes wrong, you can open the file and fix it yourself

And you don't want to:

• Re-state your background knowledge in every new session
• Entrust important facts to an invisible, intangible "cloud black-box memory"
• Manually maintain a prompt document that keeps getting longer

🎒 Before You Start

• Completed the Daily Use Guide; if you're not familiar with the chat entry points, first read Control UI: The Console in Your Browser
• Gateway is running: openclaw gateway status shows the listening status (memory indexing and retrieval are both provided by the Gateway-side memory-core plugin)
• At least one model provider configured (if not, first go to Connecting Models Overview)
• Open any chat entry point: the Control UI chat box, the terminal with openclaw for the TUI, or an already-connected chat channel
• (Optional) To use semantic retrieval: have an embeddings provider available. It uses OpenAI embeddings by default; you can also switch to a local option like Ollama or just use keyword-only retrieval (covered in detail in Step 3 and the advanced tips)

Core Idea

**OpenClaw Memory = Markdown files on disk + a SQLite index. ** The files are the substance; the index exists for retrieval. In the official docs' own words: the model only remembers what is saved to disk—there is no hidden state.

Four memory-related files, each covering one layer:

File	What goes in it	When it's loaded
USER.md (optional)	User profile: stable preferences, communication style, relationships, ongoing projects, written as directive-style entries	Injected at the start of every session (with its own small budget)
MEMORY.md	Long-term memory: persistent facts, decisions, and summaries that aren't profile material	Injected at the start of every session
memory/YYYY-MM-DD.md	Journal layer: the current day's working context, observations, session summaries	Today's and yesterday's journals are auto-loaded on bare /new, /reset; earlier ones are retrieved only on demand
DREAMS.md (optional)	dreaming's dream reports, written for humans to read	Never injected, purely for review

Claw has three memory tools (provided by the default memory plugin memory-core): memory_search (semantic retrieval, matches even with different wording), memory_get (read a specific file or line range), and intent (register event-conditioned reminders; time-based reminders go through scheduled tasks and are not handled by memory).

Two design bottom lines—knowing them upfront helps you avoid pitfalls:

1. Writing has a threshold—not everything gets recorded. Every memory entry carries a provenance tag: owner (something you said yourself in a trusted channel), agent (inferred by Claw from your content), untrusted (web pages, tool output, external content from group chats), system (runtime instructions). The latter two categories will never be promoted into long-term memory—this is a structural block, not "being more cautious probabilistically." So if you want Claw to remember something, saying it yourself works best.
2. Recall runs in two lanes. The cheap lane makes zero model calls: USER.md/MEMORY.md injected at session start, memory_search ranked retrieval, and automatic injection of trigger phrases (at most 3 entries per turn). The expensive lane is the Active Memory sub-agent, which only starts when "you ask about something from the past and the cheap lane found no strong hit"—everyday chats don't pay extra latency for recall.

💡 Memory ≠ reminders

Time-based reminders** like** "remind me to check the data on Friday afternoon" don't go into the memory system; Claw turns them into cron scheduled tasks. Event-based reminders** like** "ping me when the release comes out" go through the intent tool into a separate SQLite table. Memory handles "remembering facts," scheduled tasks handle "doing things at the right time"—see Scheduled Tasks Automations for details.

Follow Along

Step 1: Make Claw remember you—just say "remember"

Why: OpenClaw memory has no hidden state. To make Claw remember something, you don't need any command or configuration—just tell it. The official docs' example is simply "Remember that I prefer TypeScript."

Send a message in any chat entry point:

Remember: I primarily use TypeScript, and code examples should be written in TypeScript by default.

You should see: Claw confirms it has taken note and writes this entry into the memory file under ~/.openclaw/workspace—stable profile-type preferences are written, by convention, as directive-style entries (starting with Always / Never / Prefer) and go into USER.md; non-profile facts and decisions go into MEMORY.md. Which file it goes into is decided by Claw's judgment of "the appropriate file."

Seeing is believing—take a look in the file:

cat ~/.openclaw/workspace/USER.md

You should see: a new directive-style entry, usually with an observation date. USER.md itself is an optional file; if it didn't exist before, this write will create it. If you'd rather not open a terminal, the Control UI's Agents page → Memory tab also shows it (that page also has the dreaming toggle and the Dream Diary reader).

💡 If it remembers wrong, just say so

If your preferences change, just tell it "I mostly use Python now." By official convention, preference updates in USER.md arein-place replacements of old entries, not appending a contradictory one—otherwise Claw will answer you with the old value.

• USER.md (or MEMORY.md) contains the entry you just wrote

Step 2: Verify cross-session memory—it still remembers after /new

Why: The test of "remembering you" is whether it persists in a different session. Session context gets cleared; memory files don't—that's the dividing line between the two.

/new

You should see: a new session opens (as covered in the previous lesson: the model pin is retained). Then ask it:

What programming language do I prefer?

You should see: Claw answers TypeScript. Because USER.md and MEMORY.md are injected into the contextat the start of every session—this is "startup injection," OpenClaw's first layer of cross-session memory.

Note one detail: today's and yesterday's diary entries memory/YYYY-MM-DD.md are also automatically loaded on a bare /new or /reset. So it also "casually remembers" yesterday's context—this isn't a bug, it's the diary layer's design (expanded on in the pitfalls section).

• /new After /new, Claw can still answer your preference

Step 3: Make Claw recall—memory_search semantic retrieval

Why: The diary layer accumulates more and more over time; it's impossible to stuff it all into the context. memory_search uses hybrid retrieval (semantic vectors + keywords) to find relevant notes on demand—ask in different wording and it can still hit.

Method A (recommended): just ask about an old topic in chat. When the answer isn't in the context, Claw will call memory_search on its own:

What was the conclusion of the deployment plan we discussed last week?

You should see: Claw gives the conclusion and (usually) notes which day's diary it came from. Even if your phrasing differs completely from what was recorded at the time, semantic retrieval can still match it.

Method B: search directly from the CLI. openclaw memory search routes through the Gateway directly while the Gateway is running—no need to stop the service:

openclaw memory search "部署方案"

You should see: relevant memory snippets returned from the available indexes. It works just as well in Chinese—the built-in engine tokenizes with trigrams (three-character groups), with native support for Chinese, Japanese, and Korean. This is a built-in capability of memory-core and requires no extra configuration.

💡 You can search even without embeddings configured

Semantic retrieval uses OpenAI embeddings by default, but keyword retrieval (SQLite FTS5) works out of the box. Setting memory.search.provider to "none" gives you a pure keyword mode with no vectors; for a fully local setup, there's an Ollama solution in the advanced techniques section.

• Asked about an old topic, and Claw retrieved the answer from memory

Step 4: Configure cross-session recall—rememberAcrossConversations

Why: Startup injection only covers USER.md/MEMORY.md and the last two days of diaries. What about details discussed inanother private chat last week? OpenClaw 2.0's cross-session recall (introduced in v2026.8.1) lets the same agent recall relevant context from itsother private chat sessions—this is the core of the 2.0 memory upgrade (for background, see OpenClaw 2.0 what's new).

Personal installs (session.dmScope not set or set to "main", with no binding overriding it) have itenabled by default; installs that have configured DM isolation have it disabled by default. To enable it explicitly or confirm, add one line in openclaw.json:

{
  agents: {
    entries: {
      personal: {
        memory: {
          search: {
            rememberAcrossConversations: true,
          },
        },
      },
    },
  },
}

You should see: after the configuration is saved, OpenClaw will index that agent's session records and run an Active Memory retrieval before eligible private chat replies—a plan discussed in private chat A can be recalled when you ask about it in private chat B.

The privacy boundaries are hard-coded—remember three rules:

• Onlyprivate chats of the same agent can recall from each other; groups and channels serve neither as recall sources nor as recall destinations
• Sessions of other agents never participate
• Unknown/archived session records with insufficient metadata are rejected

⚠️ Cross-session recall uses the expensive lane

This recall is performed by the Active Memory sub-agent and only triggers when "the message asks about the past and the cheap lane has no strong hit" (default escalate mode). Ordinary casual chat pays no extra latency for it, but the deep-recall turn is a bit slower—that's a trade-off by design.

• Confirmed that your installation has this enabled by default, or that you have explicitly configured the field

Step 5: Hand it over to dreaming—automatic consolidation of OpenClaw memory

Why: The diary layer keeps growing, and manually moving useful entries into MEMORY.md isn't realistic. dreaming is a background consolidation system enabled by default: every day at 3 AM (cron 0 3 * * *) it runs a three-phase pass—light (organize short-term material) → REM (reflect, distill themes) → deep (promote qualified entries into MEMORY.md). Only the deep phase writes MEMORY.md.

Check the status with a chat command:

/dreaming status

You should see: The receipt shows dreaming's current on/off state. /dreaming on and /dreaming off can toggle it (requires owner or admin permissions). This scheduled task is managed automatically by memory-core under the fixed name Memory Dreaming Promotion; you don't need to create a cron yourself—to confirm it exists, run openclaw automations list --all.

The human-readable report is written to DREAMS.md (the Memory tab of the Control UI has a Dream Diary reader). To manually trigger a promotion preview:

openclaw memory promote

You should see: A candidate list drawn from memory/YYYY-MM-DD.md (default thresholds: weighted score ≥ 0.75, recalled ≥ 3 times, query diversity ≥ 3). This is only a preview; adding --apply is what appends the selected entries to MEMORY.md. Note that this command requires stopping the Gateway first (the pitfall notes explain why).

💡 What can be promoted? Only what you say

The promotion threshold isn't just about scores: candidates with untrusted or system provenance are structurally excluded before entering the ranking. Things seen on webpages or said by group members, no matter how frequently recalled, never make it into long-term memory.

• /dreaming status shows dreaming is enabled

Step 6: Bring in your old assistant's memories—Import Memory

Why: Users migrating from Claude Code, Codex, or Hermes don't need to rebuild old memories from scratch. The Control UI supports one-click import of local Markdown memories.

How to do it: Control UI Settings → Import Memory, pick the target agent, preview the detected files, and confirm the import. For the default agent there's an even lighter entry point: in Settings → Ask OpenClaw, just say import memory.

Each source reads these files (only Markdown is copied; source files are left untouched):

Source	Imported content
Claude Code	~/.claude/projects/*/memory Auto-memory Markdown for each project under it (including the autoMemoryDirectory you configured)
Codex	~/.codex/memories The consolidated MEMORY.md and memory_summary.md under it
Hermes	The MEMORY.md and USER.md detected under the Hermes home directory

You should see: The imported files are sorted into memory/imports/claude-code/, memory/imports/codex/, and memory/imports/hermes/ under the target agent's workspace, immediately indexed by memory_search and readable via memory_get. Note that they will not be merged into the startup-injected MEMORY.md—old memories exist as retrievable material; Claw's long-term memory is still maintained by itself (and dreaming).

• After the import finishes, source subdirectories appear under memory/imports/

Checkpoint ✅

• After saying "Remember: ...", you saw the new entry in the files under ~/.openclaw/workspace
• /new After starting a new session, Claw can still answer questions about your preferences
• You asked about an old topic and Claw retrieved the answer via memory search (Chinese works too)
• You know whether cross-session recall in your installation is on by default or requires explicit configuration
• /dreaming status You've checked the status once and can say which of the three phases writes MEMORY.md

Pitfall notes

❌ "Why does it still remember yesterday's stuff after /new?"

Cause: /new clears the session context, not memory. The startup-injected USER.md/MEMORY.md are loaded at the start of every session; today's and yesterday's diaries are also auto-loaded on a bare /new or /reset. The three layers each manage their own thing: session context (gets cleared), diary layer (last two days auto-loaded), long-term memory (always there).

Correct approach: If you want it to "forget" a memory, just tell it directly, or open the file and delete that line (Markdown is freely editable); for batch deletion traced by session, use openclaw memory forget (covered in the advanced tips). For a truly clean session, don't expect /new to clear memory—that's not its job.

❌ Gateway is running, and openclaw memory status / index / promote get rejected

Cause: Apart from search and plain session-backfill, which are routed through the running Gateway, the other memory subcommands require exclusive access to the memory store—when the Gateway owns the state directory, these commands refuse outright before opening the store.

Correct approach:

openclaw gateway stop &&
openclaw memory status &&
openclaw gateway start

❌ MEMORY.md keeps growing and Claw starts "forgetting" earlier entries

Cause: When MEMORY.md exceeds the startup injection budget, the file on disk is preserved as-is, but the copy injected into the context gets truncated—the file is still there, yet Claw "can't see" the latter half.

Correct approach: Use /context list, /context detail, or openclaw doctor to see original size vs. injected size and truncation status; move details into the memory/*.md diary layer and keep only durable summaries in MEMORY.md; if the budget really isn't enough, then consider raising the startup limit (trading prompt budget for it).

❌ Expecting Claw to record webpage content or group chat messages as long-term memory

Cause: Provenance grading blocks this at write time—memories derived from webpages, tool outputs, or external content inside or outside the group are tagged untrusted, runtime instructions are tagged system, and both categories of candidates are structurally excluded before dreaming consolidation—"no matter how frequently recalled, they can't be promoted into core memory." Cron jobs, heartbeats, and sub-agent sessions likewise produce no persistent memory candidates.

Correct approach: Say important facts yourself in a private chat (owner provenance); if you see something in a group chat worth remembering, relay it to Claw. This is both a safety design and helps you filter noise.

Advanced tips (optional)

Switching embeddings providers, or going fully local. Semantic search uses OpenAI embeddings by default;memory.search.provider you can switch to gemini, voyage, mistral, bedrock, deepinfra, ollama, lmstudio, github-copilot, openai-compatible, and more. If you don't want to use any API key: install the official llama.cpp provider (openclaw plugins install @openclaw/llama-cpp-provider) and then set provider: "local", or use Ollama's local embeddings directly. A note for Chinese-language users: semantic search quality depends on the embedding model, while keyword search (trigram) is always available.

Manually fine-tune the recall weight of a specific memory. Memory entries support end-of-line comments; include trigger phrases and importance when writing them (1–10):

- Keep the gateway on loopback. @@I18N_KEEP_000038@@ @@I18N_KEEP_000039@@

Entries whose trigger phrases match (score ≥ 0.65) are automatically injected as hidden context (only entries in MEMORY.md / USER.md; the diary layer does not participate), up to 3 entries per turn; importance participates in retrieval ranking. Entries without comments stay neutral and are not penalized.

Delete memories by session. openclaw memory forget does traceable deletion—preview first, then execute:

openclaw memory forget --agent <agent-id> --session <id-or-key> --dry-run --json

After confirming the report, remove --dry-run to actually delete (deletes immediately with no second confirmation; the source session records are kept). If you only want to rebuild the index without deleting files: openclaw memory reset followed by openclaw memory index.

Switch the memory engine. Besides the built-in memory-core (SQLite, default), plugins are available: Honcho (AI-native cross-session memory with user modeling), LanceDB (vector-store backend, supports local Ollama embeddings); the memory-wiki plugin can also add a knowledge-base layer with evidence chains alongside. For everyday personal use, the default engine is sufficient.

Automatic rescue before compaction. Before a session's context is compacted, OpenClaw runs a silent memory flush first, reminding Claw to store important context into memory files—enabled by default (agents.defaults.compaction.memoryFlush.enabled). So when a long session gets compacted midway, key facts have usually already been written into the diary layer.

Lesson Summary

✅ OpenClaw memory has no hidden state: it's all Markdown files + a SQLite index under ~/.openclaw/workspace; if you want it remembered, say so directly, and if you want to check, just open the files.

✅ Four files in layers: USER.md (user profile, instruction-style entries), MEMORY.md (long-term facts and decisions), memory/YYYY-MM-DD.md (diary layer, today and yesterday auto-loaded), DREAMS.md (dream reports, never injected).

✅ Two layers of protection for cross-session memory: startup injection (loads USER.md/MEMORY.md each session) + memory_search semantic search (native trigram support for Chinese).

✅ 2.0 cross-session recall: direct chats with the same agent can recall each other (on by default for personal installs); group chats and other agents never participate.

✅ dreaming is on by default: three-phase consolidation at 3 a.m. daily (light → REM → deep); only deep writes to MEMORY.md; untrusted/system are structurally excluded by tracing.

✅ Old memories can be migrated: Settings → Import Memory imports from Claude Code / Codex / Hermes, landing in memory/imports/, searchable and not merged.

Configuration field	Recommended value	Description
agents.entries.<id>.memory.search.rememberAcrossConversations	true (on by default for personal installs)	Cross-session recall between direct chats of the same agent
plugins.entries.memory-core.config.dreaming.enabled	true (default)	Toggle for background automatic consolidation
plugins.entries.memory-core.config.dreaming.frequency	0 3 * * * (default)	dreaming scan frequency; memory-core manages the cron automatically
memory.search.provider	openai (default) / ollama / none	Embeddings source for semantic search
agents.defaults.compaction.memoryFlush.enabled	true (default)	Automatically flush important context into memory files before compaction

CLI quick reference: openclaw memory status (check index status; the Gateway must be stopped), openclaw memory search "query" (can be run while the Gateway is running), openclaw memory promote (preview promotion candidates), openclaw memory forget (traceable deletion; run --dry-run first). See the full command table in CLI Commands and Configuration Quick Reference.

Next Lesson Preview

Memory solves "remembering"; the next lesson, Efficient Workflows: Automation, Browser, and MCP, solves "running automatically"—Claw can work on a schedule without you asking.

You will learn:

• Scheduled tasks with Automations: cron, reminders, and webhook triggers (turning "remind me on Friday" into a real scheduled task)
• Browser automation: letting Claw operate web pages for you
• MCP: connecting Claw to external tools and data sources
• Given a task, how to choose the right mechanism among skills, scheduled tasks, and memory

Related Tutorials

• Chat Command Crash Course: /model, /think, and Slash Commands
• OpenClaw 2.0 What's New: What v2026.8.1 Actually Updated
• Skill Workshop: Letting Claw Learn Skills on Its Own