DEV Community

Ana Julia Bittencourt
Ana Julia Bittencourt

Posted on • Originally published at blog.memoclaw.com

How to migrate your agent from MEMORY.md to MemoClaw in 10 minutes

#ai #agents #memory #openai

Your OpenClaw agent has been running for weeks. Maybe months. It has a MEMORY.md file that started small and now weighs in at 30KB, 40KB, maybe more. Every single session, your agent loads the entire thing into context. That's thousands of tokens burned before it even starts thinking about your actual request.

Here's how to move all of that into MemoClaw and get semantic recall instead of brute-force context stuffing. The whole process takes about 10 minutes.

What You'll Need

  • An OpenClaw agent with an existing MEMORY.md (or daily memory files)
  • The MemoClaw CLI: npm install -g memoclaw
  • A wallet (your agent probably already has one from OpenClaw)

Step 1: Check What You're Working With

First, see how big the problem actually is:

wc -c ~/.openclaw/workspace/MEMORY.md
# Example output: 38420 ~/.openclaw/workspace/MEMORY.md
Enter fullscreen mode Exit fullscreen mode

38KB. At roughly 4 characters per token, that's ~9,600 tokens loaded every session. If you're on Claude Sonnet, that's context space you could use for actual work.

If your agent also writes daily files to memory/, check those too:

du -sh ~/.openclaw/workspace/memory/
Enter fullscreen mode Exit fullscreen mode

Step 2: Export Your Memory

The MemoClaw CLI can ingest markdown files directly. No reformatting needed.

For a single MEMORY.md file:

memoclaw migrate --file ~/.openclaw/workspace/MEMORY.md
Enter fullscreen mode Exit fullscreen mode

For a directory of daily memory files:

memoclaw migrate --dir ~/.openclaw/workspace/memory/
Enter fullscreen mode Exit fullscreen mode

The migrate command splits your markdown into individual memories, generates embeddings for each one, and stores them. It handles headers, bullet points, and paragraphs as natural splitting points.

You'll see output like:

Migrating ~/.openclaw/workspace/MEMORY.md...
Split into 47 memories
Stored 47/47 memories (batch mode)
Cost: $0.04 (1 batch operation)
Done.
Enter fullscreen mode Exit fullscreen mode

That's it for the data migration. Your entire memory history is now searchable by meaning, not just keywords.

Step 3: Install the MemoClaw Skill

If you haven't already, add the MemoClaw skill to your agent:

clawhub install anajuliabit/memoclaw
Enter fullscreen mode Exit fullscreen mode

This gives your agent store and recall tools. When it needs to remember something, it stores it. When it needs context, it recalls only what's relevant to the current conversation.

Step 4: Update AGENTS.md

Open your agent's AGENTS.md and remove (or comment out) the section that tells it to load MEMORY.md every session. Replace it with instructions to use MemoClaw.

Before:

## Every Session
1. Read `MEMORY.md` for context
2. Read `memory/YYYY-MM-DD.md` for recent notes
Enter fullscreen mode Exit fullscreen mode

After:

## Every Session
1. Use MemoClaw recall to fetch relevant context for the current conversation
2. Store important decisions, preferences, and corrections after each session
Enter fullscreen mode Exit fullscreen mode

Your agent no longer loads everything. It loads what matters.

Step 5: Verify the Migration

Run a few recall queries to make sure your memories came through:

memoclaw recall "user preferences"
memoclaw recall "project decisions"
memoclaw recall "things to remember"
Enter fullscreen mode Exit fullscreen mode

You should see relevant results from your old MEMORY.md content. The semantic search means you don't need exact keyword matches. Searching for "UI theme" will find a memory that says "the user prefers dark mode."

Step 6: Keep the Old Files (For Now)

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

mv ~/.openclaw/workspace/MEMORY.md ~/.openclaw/workspace/MEMORY.md.bak
Enter fullscreen mode Exit fullscreen mode

Run your agent for a few days. If everything works and recalls are accurate, you can archive or remove the backup.

What Changes After Migration

Before: Every session loads 9,600+ tokens of flat text. Your agent reads about that pizza place you liked three months ago when you're asking it to debug a TypeScript error.

After: Your agent recalls 5-10 relevant memories (maybe 500 tokens) based on what you're actually talking about. The pizza place memory stays quiet until you ask about dinner.

Token savings depend on your MEMORY.md size, but for a typical agent running a few months, expect to reclaim 5,000-15,000 tokens per session. That's context space your agent can now use for reasoning about your actual request.

Cost

The migrate command uses batch storage. Up to 100 memories per batch at $0.04 each. A typical MEMORY.md with 47 memories costs $0.04 total to migrate. After that, each recall is $0.005.

If you're still in the free tier (100 calls per wallet), the migration itself counts as 1 call per batch.

Common Issues

"My agent still tries to read MEMORY.md" - Check AGENTS.md. Make sure you removed the instruction to load the file. Some agents have it in multiple places.

"Recall returns too many irrelevant results" - Use tags when storing. After migration, you can tag memories with memoclaw update <id> --tags "preferences,important" to improve filtering.

"I have daily files AND a MEMORY.md" - Migrate both. Run migrate on the directory first (daily files), then the MEMORY.md. MemoClaw handles deduplication during consolidation if needed.

That's the whole process. Ten minutes, mostly waiting for the CLI to finish uploading. Your agent goes from loading everything to recalling what it needs.

Top comments (0)