Migrate Memory

How it works

NanoClaw does not migrate memory at runtime. Each provider keeps its own store, and switching a group’s provider leaves both stores untouched — the new provider simply starts with its own. Carrying memory across is a separate, explicit step, and /migrate-memory is that whole mechanism: your coding agent reads the source store, distills what’s durable, writes it into the target store, and restarts the group.

The skill translates between two store shapes, not provider names:

• Flat file — CLAUDE.local.md at the group workspace root (the Claude provider).
• Scaffold tree — a memory/ directory used by any provider with a memory scaffold, such as Codex. memory/index.md is the index, and durable notes live under memory/memories/.

A switch only needs migration when it crosses shapes. Two providers that both use the scaffold share the same memory/ tree, so switching between them carries nothing. The real work is always one of two directions: flat to scaffold, or scaffold to flat.

Three principles govern the migration. Copy, never move — the source store stays intact, because it is the rollback. Idempotent — re-running must never duplicate what a previous run imported. Distill, don’t dump — the agent is the inference step, keeping identity and seed instructions, user preferences, and durable facts while dropping conversational residue.

Setup

Switching the provider is an operator action, run from the host before the skill:

ncl groups config update --id <group-id> --provider <name>
ncl groups restart --id <group-id>

Then run /migrate-memory. It works in four steps:

1. Identify the group and direction. The skill uses ncl groups list and ncl groups config get --id <group-id> to read the current (target) provider, maps each side to its store shape, and inspects the group folder. If both sides use the same shape — or the source is empty — there’s nothing to migrate, and it says so and stops.
2. Flat to scaffold. It reads CLAUDE.local.md and any files it references, then distills the content into memory/memories/imported-agent-memory.md, leading with anything that defines who the agent is. It adds a line to memory/index.md pointing at the imported file.
3. Scaffold to flat. It reads memory/index.md and the notes it points to, then integrates the durable facts into CLAUDE.local.md under a clearly marked, dated section, deduplicating against what’s already there.
4. Restart and verify. It runs ncl groups restart --id <group-id> and asks you to send the group a test message that depends on a migrated fact.

Tips

• If memory/memories/imported-agent-memory.md already exists from a previous run, the skill shows you what’s there and asks before touching it, integrating only what’s new.
• Because the source store is never modified, rollback is lossless — switch the provider back and the old store is waiting exactly as it was.
• If the test agent doesn’t know a migrated fact, re-check that the target file landed in the right group folder.
• For a full picture of what a provider switch carries over automatically, see the provider-migration docs.