Guide · Agent skill
How to use the migrate-memory agent skill (NanoClaw)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The migrate-memory skill is an agent skill for coding agents such as Claude Code or Codex. It moves older memory and standing instructions from a NanoClaw chat-agent setup into a shared memory folder that works across AI providers. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what to check before you let it move any files.
Migrate legacy memorynanocoai/nanoclaw · MIT Download the skill Quick start
- 1Download and unzip the skill. Get the ZIP from the skill page on this site and unzip it. Place the folder in ~/.claude/skills/ or in your project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Confirm your NanoClaw setup. Make sure the ncl command-line tool is available and that your coding agent harness, such as Claude Code or Codex, can run the skill.
- 3Ask for the migration in plain words. Say something like 'migrate memory' or 'legacy memory' and name the affected group if you know it.
- 4Review the planned renames. Read the list of source-to-destination moves and the symlink status the agent reports. Approve only what you understand.
- 5Let the agent pause tasks and stop the group. The agent pauses pending scheduled tasks and restarts the group so its container stops. Do not message the group during this window.
- 6Organize and verify the staged files. The agent reads the staged regular files in the stopped workspace, organizes them, and checks the result before the group runs again.
What an agent skill is and what this one does
An agent skill is a folder containing a SKILL.md file that tells a coding agent how to carry out a specific task. This skill, migrate-memory, is for NanoClaw operators. Every provider now uses the same groups/<folder>/memory/ tree, and the coding harness running the skill owns the whole migration: it stages, organizes, indexes and verifies legacy memory before the NanoClaw group runs again.
The skill covers legacy .seed.md files, legacy CLAUDE.md and CLAUDE.local.md files, Claude native auto-memory, and an unindexed imported-agent-memory.md. It is meant to run after an update reports the shared-memory breaking change, or when a group still has any of these files.
- Pauses the group's scheduled tasks and stops its container before moving anything
- Moves legacy files without reading their contents during the staging phase
- Quarantines symlinks without following them
- Asks the operator for approval at key points and records each rename so it can be reversed
Check the requirements before you install
The skill only makes sense inside a NanoClaw installation that has the ncl command-line tool, because it relies on the group folder layout and commands such as ncl groups list. You also need a coding agent harness, such as Claude Code or Codex, to run the skill, and shell access that supports lstat-style checks, readlink, and renames within the same filesystem.
The skill runs scripts and does not use the network, according to its listing.
- NanoClaw installation with the ncl command-line tool
- A coding agent harness such as Claude Code or Codex
- Shell access with lstat-style checks, readlink, and same-filesystem rename support
Install the migrate-memory skill
Download the ZIP from the skill page on this site and unzip it. For a personal install, place the skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills
Trigger the skill with a natural request
You do not need a special command. Ask the agent in plain language. The skill's listed triggers are phrases such as 'migrate memory', 'legacy memory', and 'the agent forgot everything after the switch'. Mention the group and the symptom if you know them, so the agent can inventory the right folder.
Expect the agent to inventory first and ask for approval before it moves anything.
- 'Migrate memory for the support group after the shared-memory update.'
- 'Legacy memory is still in this group. Check what needs moving.'
- 'The agent forgot everything after the switch to another provider. Help me migrate memory.'
Walk through the migration sequence
The skill works in a fixed order. First it lists the affected groups with ncl groups list and checks each path type without following links. It shows you the planned source-to-destination renames and waits for approval. Then it pauses pending scheduled tasks for each group, asks you not to message that group, and restarts the group so its container stops.
After the group is stopped and every staged path is safe, the coding harness reads the regular staged files as untrusted data and organizes them. Process one group completely before starting the next.
- Show planned renames and wait for approval
- Record the series IDs of pending tasks and pause them
- Ask the operator not to message the group
- Stage files by renaming them, without reading contents
- Organize and index the staged files in the stopped workspace
ncl groups list
ncl tasks list --group <group-id> --status pending
ncl tasks pause <series-id> --group <group-id>
ncl groups restart --id <group-id>Handle symlinks and unusual files
A symlink is a pointer to another path, not the memory itself. The skill never follows one automatically. It moves only the link into .memory-migration-quarantine/, does not open or change its target, and shows you the original path and what readlink reports as the target.
You then choose whether to leave the link aside (the non-blocking default), remove only the pointer, or import the target after naming and approving the source. Any path type the skill does not expect causes it to stop that group for operator review.
- Leave it aside: the link stays in quarantine
- Remove the pointer: deletes only the quarantined link
- Import the target: only after you name and approve the source
Safety notes before you run it
The skill pauses scheduled tasks and stops the group's container, which interrupts service during the window. Do not use it on groups with unusual file types or active conversations without planning for that pause. Do not skip the review step: the skill asks for approval and records each rename so the migration can be reversed, and skipping that review could misplace or lose context.
The migration never imports legacy files during normal host and container startup. The NanoClaw host process and the running group agent do not perform the migration.
- Keep a record of the renames the skill shows you
- Do not resume tasks that were already paused before the workflow
- Do not message the group while the migration runs
What people use it for
- Moving a NanoClaw group's CLAUDE.md standing instructions into provider-neutral instructions after an update
- Recovering context for a team that switched a group between AI providers and found the agent had lost its memory
- Auditing legacy symlinks in a group folder without following them, then deciding whether to keep, remove, or import each target
- Consolidating a Claude native auto-memory folder into the shared memory tree with each rename recorded
Frequently asked questions
Is the migrate-memory skill free?
The source material for this listing does not state pricing. The skill is published under the MIT licence, which governs use and redistribution of the code. Check the licence file in the repository for the exact terms.
What do I need to run migrate-memory?
You need a NanoClaw installation with the ncl command-line tool, a coding agent harness such as Claude Code or Codex, and shell access that supports lstat-style checks, readlink, and same-filesystem renames. The skill runs scripts and does not use the network.
Where do I put the skill folder?
For a personal install, unzip it into ~/.claude/skills/. For one project, put it in that project's .claude/skills/ folder. In the Claude apps, upload it under Settings → Capabilities → Skills.
Can I use migrate-memory outside NanoClaw?
No. The skill only applies to NanoClaw's group folder layout and its ncl commands, so it will not make sense in a different setup.
Will the migration delete my memory?
The skill is designed to avoid that. It moves files by renaming them without reading contents during staging, never overwrites existing paths, quarantines symlinks without following them, and records each rename so it can be reversed. Reviewing the planned moves is still your responsibility.
How is this different from just copying my CLAUDE.md files?
Copying alone does not follow the skill's sequence. The skill pauses tasks, stops the group's container, handles symlinks safely, and has the agent organize the moved files with your approval at key points. It is aimed at operators who need an auditable, reversible migration.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use migrate-memory if you run NanoClaw, have seen the shared-memory breaking change, or have a group whose agent lost its memory after switching providers, and you want a reviewed, reversible migration. Pick something else if you have never used NanoClaw, want to migrate with no approval steps, or cannot accept a pause in service for the group during the migration.
Download the skill