Memory Migration: What to Keep, Archive, and Discard When Moving Your Agent

An agent without its memory is a stranger wearing a familiar face. It responds, but it does not remember your preferences, your customers, or the hundred edge cases it learned to handle over the past six months. Memory migration is the hardest part of any agent move, and it is the part most teams underestimate.

The challenge is not just copying files. It is deciding what to copy, what to leave behind, and how to verify that what arrived at the destination is intact and usable.

## Types of agent memory

OpenClaw agents maintain several distinct types of memory, each with different migration characteristics.

**Short-term memory** holds the current conversation context. Active sessions, recent interactions, working state for in-progress tasks. This memory is ephemeral by design. If your agent restarts, short-term memory resets. During migration, you generally do not need to transfer this. Any active conversations will restart naturally.

**Long-term memory** contains learned preferences, user profiles, historical context, and accumulated knowledge. This is the memory that makes your agent feel like it knows you. Long-term memory is stored in files or databases and grows over the agent's lifetime. This is the critical migration target.

**Episodic memory** records specific interactions and their outcomes. Your agent remembers that customer X asked about feature Y three weeks ago, and that the conversation resolved with a workaround. Episodic memory is valuable for continuity but can be massive for high-volume agents. You need a strategy for what to bring and what to archive.

## What transfers cleanly

Configuration-based memory transfers without issues. SOUL.md personality rules, AGENTS.md skill definitions, any behavioral rules written as config files — these are text and they copy perfectly. If your agent's "memory" is mostly configuration, migration is straightforward.

File-based memory (Markdown files, JSON documents, plaintext logs) transfers cleanly as long as you preserve the directory structure and file permissions. The content is portable. The challenge is finding all of it, since skills sometimes store memory files in unexpected locations.

## What breaks during migration

**Database-backed memory** is the first failure point. If your agent stores long-term memory in PostgreSQL on one provider and needs SQLite on another, you need format conversion. Schema differences, encoding issues, and data type mismatches can corrupt records silently. A timestamp that looked fine in PostgreSQL might lose timezone information when imported into SQLite.

**Index files** are the second. Many memory systems maintain indexes for fast retrieval: search indexes, embedding caches, relationship maps. These are derived from the primary data but are expensive to rebuild. Some transfer between platforms, others do not. Embedding caches in particular are tied to the model that generated them. If you switch embedding providers during migration, every cached embedding is invalid.

**Relative path references** are the third. Memory entries that reference other files by relative path break if the directory structure changes even slightly during migration. A memory entry pointing to ../../skills/crm/cache.db fails if the skill directory moves.

## Pruning before migration

Migration is the ideal time to clean house. Agents accumulate memory bloat just like any long-running system.

**Stale conversation summaries.** If your agent summarizes every conversation and stores the summaries indefinitely, you likely have thousands of entries from months ago that will never be referenced again. Set a retention window (90 days is reasonable for most use cases) and archive everything older.

**Duplicate knowledge entries.** Agents sometimes learn the same fact multiple times through different conversations. A deduplication pass before migration reduces transfer size and prevents conflicting entries on the destination.

**Failed interaction records.** Episodic memories of conversations that went wrong (errors, timeouts, malformed responses) are useful for debugging but rarely needed after migration. Archive these separately from production memory.

**Orphaned skill data.** If you uninstalled a skill three months ago but its data files are still in the memory directory, there is no reason to migrate them. Identify files that belong to skills no longer in your AGENTS.md manifest and exclude them.

## Format conversion between platforms

When source and destination use different storage backends, you need a conversion step. The safest approach is a two-phase process.

Phase one: export from source to a neutral format. JSON is the most universal choice. Every memory entry becomes a JSON document with explicit types, timestamps, and relationship references. This is your checkpoint. If anything goes wrong during import, you can restart from the JSON export without touching the source again.

Phase two: import from neutral format to destination. Build the destination's schema first, then populate it from the JSON documents. Validate record counts and spot-check content after import.

ClawSail handles this conversion automatically for supported storage backends (PostgreSQL, SQLite, file-based, Redis). For custom storage, ClawSail exports to JSON and provides import hooks for the destination format.

## Testing memory integrity post-migration

A migrated agent that seems to work but has corrupted memory is worse than one that fails loudly. You need active verification.

**Record count verification.** Compare the number of memory entries in source and destination. If the source had 14,832 long-term memory entries and the destination has 14,831, find the missing one.

**Spot-check retrieval.** Pick 20 specific memory entries that you know exist (important customers, critical learned rules, recent interactions) and query for them on the destination. Verify the content matches exactly.

**Behavioral comparison.** Send the same prompt to both the old and new agent instances. The responses should be substantively similar. They will not be identical (LLM responses have inherent variance) but they should demonstrate the same knowledge and preferences.

**Relationship integrity.** If memory entries reference each other (a conversation summary linking to the original transcript, a user profile linking to interaction history), verify those links resolve correctly on the destination.

## ClawSail's memory diff tool

ClawSail includes a memory diff tool that compares source and destination memory state entry by entry. It flags missing entries, content mismatches, broken references, and type conversion issues. Run it after every migration as the final verification step.

The diff tool also generates a migration report showing exactly what transferred, what was archived, what was discarded, and what needs manual attention. Keep this report. If behavior issues surface weeks later, the report tells you whether the problem is a migration gap or something new.

## The bottom line

Memory migration is not a file copy operation. It is a data migration with all the complexity that implies. Plan for conversion, budget time for verification, and keep the source running until you are confident the destination has everything it needs. Your agent's memory is irreplaceable. Treat the migration accordingly.

Related posts