Every OpenClaw agent starts the same way. You create a workspace, and somewhere in your AGENTS.md you write “store important things in MEMORY.md.” It works for a while. Then it doesn’t.

If you’ve landed here, you probably already feel the pain. Your MEMORY.md is hundreds of lines long. Your agent burns tokens loading memories about projects you finished months ago. It can’t find the one correction you made last Tuesday because grep doesn’t understand what you meant, only what you typed.

This guide walks through the full migration. Takes about fifteen minutes.

Why bother

Two reasons, and I’ll keep them short.

Semantic search beats grep. When your agent recalls “deployment preferences,” MemoClaw returns the memory where you said “always use Railway, never Vercel” even though neither word appears in the query “deployment preferences.” MEMORY.md can’t do that. Your agent would need to load the entire file and hope the relevant section is close enough to the question in the context window.

Memories survive compaction. When your context window fills up, OpenClaw compacts older messages. Any memories your agent noted “mentally” during the conversation vanish. Memories stored in MemoClaw persist regardless of what happens to the chat context. They exist outside the session.

There are other benefits (namespaces, importance scoring, deduplication), but those two are the ones that made me switch.

Before you start

You need the MemoClaw CLI:

npm install -g memoclaw

If this is your first time, run the init command to generate a wallet:

memoclaw init

This creates ~/.memoclaw/config.json with your wallet address and private key. That wallet is your identity. No accounts, no API keys, no registration.

Check that everything works:

memoclaw status

You should see your wallet address and free tier info. Every wallet gets 100 free API calls. The migration will use some of these depending on how many memories you have.

Step 1: Look at what you’ve got

Before migrating, take stock. Open your MEMORY.md:

wc -l ~/.openclaw/workspace/MEMORY.md
cat ~/.openclaw/workspace/MEMORY.md

Mine was 847 lines when I finally migrated. Yours might be shorter or longer. Either way, scan through it and notice a few things:

• How much of it is still relevant?
• Are there duplicates? (There always are.)
• Is anything structured with headers, or is it a wall of text?

You don’t need to clean it up. The migration tool handles messy files fine. But knowing what’s in there helps you verify the results.

Step 2: Run the migration

The CLI has a migrate command built for this:

memoclaw migrate ~/.openclaw/workspace/MEMORY.md

That’s the simple version. It reads your markdown file, splits it into individual memories, generates embeddings, and stores everything in MemoClaw.

For more control:

memoclaw migrate ~/.openclaw/workspace/MEMORY.md --namespace main-agent

The --namespace flag is worth using. It keeps your imported memories grouped together, and your agent can query just that namespace later. If you have multiple memory files, consider separate namespaces:

memoclaw migrate ~/.openclaw/workspace/MEMORY.md --namespace general
memoclaw migrate ~/.openclaw/workspace/memory/project-alpha.md --namespace project-alpha

If you have a memory/ directory with dated files:

memoclaw migrate ~/.openclaw/workspace/memory/ --namespace daily-logs

The migrate command handles directories recursively. It skips .git, node_modules, and other junk automatically.

What the migration actually does

For each chunk of text it finds, the migration:

1. Splits the content into logical memory units (respecting markdown headers and paragraph breaks)
2. Generates an embedding via OpenAI
3. Stores the memory with auto-assigned importance scores
4. Tags each memory based on its content

Importance scores are estimated from context. A line that says “IMPORTANT: never deploy on Fridays” gets a higher score than “tried a new linter today.” It’s not perfect, but it’s better than everything being equal weight.

Each memory costs $0.01 to migrate (covers GPT-4o-mini extraction plus embedding). A 200-line MEMORY.md might produce 30-50 individual memories, so budget $0.30-0.50 for a typical migration. If you’re within your 100 free calls, it costs nothing.

Step 3: Verify the import

Check what landed:

memoclaw list --namespace main-agent

You’ll see a table of memories with their IDs, snippets, importance scores, and tags. Scroll through and sanity-check a few things:

• Did your corrections get high importance scores?
• Are the tags reasonable?
• Did anything get split weirdly?

Try a few recalls to test semantic search:

memoclaw recall "deployment preferences"
memoclaw recall "coding style"
memoclaw recall "things I corrected"

Compare the results to what you’d get by grepping MEMORY.md. The difference should be obvious. Recall returns relevant memories ranked by similarity. Grep returns exact string matches or nothing.

Step 4: Update your AGENTS.md

This is the part that actually switches your agent over. Open ~/.openclaw/workspace/AGENTS.md and replace your memory instructions.

Before (MEMORY.md approach):

## Memory

Read MEMORY.md on every session start. Append new learnings at the end.
If MEMORY.md is getting long, summarize older entries.

After (MemoClaw approach):

## Memory

Use MemoClaw for persistent memory. Do NOT use local markdown files.

### How to remember things
- Store: memoclaw store "what you learned" --importance 0.8 --tags tag1,tag2
- Recall: memoclaw recall "query" before making assumptions
- Always recall before storing to avoid duplicates

### When to store
- User states a preference: importance 0.7-0.9
- User corrects you: importance 0.95
- Important decision made: importance 0.9
- Lesson learned: importance 0.8

If you’re using the MCP server instead of the CLI, the instructions are similar but reference tool names (memoclaw_store, memoclaw_recall) instead of shell commands. See the MCP server tutorial for that setup.

Step 5: Handle the old files

Don’t delete MEMORY.md yet. Rename it:

mv ~/.openclaw/workspace/MEMORY.md ~/.openclaw/workspace/MEMORY.md.bak

Run your agent for a few sessions. Make sure it’s using MemoClaw correctly, storing and recalling as expected. Once you’re confident the migration worked, you can delete the backup. Or keep it. Disk space is cheap and nostalgia is free.

If you have dated memory files in a memory/ directory, same approach:

mv ~/.openclaw/workspace/memory ~/.openclaw/workspace/memory.bak

Hybrid workflows still work

If you still like cracking open a file before each session, you can ease into MemoClaw instead of ripping out everything on day one. A practical split looks like this:

1. Keep a tiny MEMORY.md (call it 10 lines max) with evergreen identity facts: pronunciation, timezone, hard rules.
2. Put everything mutable in MemoClaw — preferences, corrections, project history, and lessons learned.
3. Leave the dated memory/YYYY-MM-DD.md logs alone if you rely on them as transcripts. They make great audits while MemoClaw keeps the distilled takeaways.

You still get a human-readable anchor file, but semantic recall handles the growing pile of knowledge. As you learn to trust the external memory, you can shrink the markdown even further.

What changes in practice

The day-to-day difference is subtle but real.

Your agent stops loading 12,000 tokens of memory on every session start. Instead, it pulls 3-5 relevant memories per recall, maybe 500 tokens total. That’s context window space you get back for actual work.

Corrections stick. When you tell your agent “use spaces, not tabs” and it stores that with importance 0.95, that memory surfaces every time code formatting comes up. No more re-correcting the same things.

Old memories fade naturally. MemoClaw’s recall is relevance-based, so memories from six months ago about a finished project just stop appearing in results. You don’t need to manually prune them.

And the search actually works. “What did I say about the API redesign?” returns the right memories even if you never used the word “redesign” in the original text. You stored something about “rewriting the endpoints” and semantic similarity connects the dots.

Cost breakdown

For a typical migration and ongoing usage:

Operation	Cost
Migrating a 200-line MEMORY.md (~40 memories)	~$0.40
Storing a new memory	$0.005
Recalling memories	$0.005
Listing, deleting, counting	Free

The free tier covers 100 API calls. If your MEMORY.md is small and you don’t store obsessively, the free tier lasts a while. After that, you’re paying fractions of a cent per operation in USDC on Base.

Common issues

“My agent still tries to read MEMORY.md” Check your AGENTS.md for any remaining references to the file. Also check SOUL.md and any custom instruction files. Agents follow their instructions literally.

“The migration produced too many small memories” You can consolidate after import:

memoclaw consolidate --namespace main-agent --dry-run

The --dry-run flag shows what would be merged without doing it. If it looks good, run without the flag.

“I want to keep some things in markdown” That’s fine. Some people keep a small IDENTITY.md or TOOLS.md for quick-reference stuff that doesn’t need semantic search. The point isn’t “never use files again,” it’s “stop using files as a memory database.”

Fifteen minutes of setup, and your agent stops forgetting things. That’s the whole pitch.