migrating-memory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrating Memory

内存迁移

This skill helps migrate memory blocks from an existing agent to a new agent, similar to macOS Migration Assistant for AI agents.

Requires Memory Filesystem (memfs)

This workflow is memfs-first. If memfs is enabled, do not use the legacy block commands — they can conflict with file-based edits.
To check: Look for a
memory_filesystem
block in your system prompt. If it shows a tree structure starting with
/memory/
including a
system/
directory, memfs is enabled.
To enable: Ask the user to run
/memfs enable
, then reload the CLI.

本技能可帮助将内存块从现有Agent迁移到新Agent，作用类似于面向AI Agent的macOS迁移助理。

需要内存文件系统（memfs）

本工作流优先使用memfs。如果已启用memfs，请勿使用旧版块命令——它们会与基于文件的编辑产生冲突。
检查方法： 查看你的系统提示中是否存在
memory_filesystem
块。如果它展示了以
/memory/
开头的树状结构，且包含
system/
目录，说明已启用memfs。
启用方法： 请用户执行
/memfs enable
命令，然后重载CLI。

When to Use This Skill

何时使用本技能

User is setting up a new agent that should inherit memory from an existing one
User wants to share memory blocks across multiple agents
User is replacing an old agent with a new one
User mentions they have an existing agent with useful memory

用户正在设置需要继承现有Agent内存的新Agent
用户想要在多个Agent之间共享内存块
用户正在用新Agent替换旧Agent
用户提到自己有一个存有有用内存的现有Agent

Migration Method (memfs-first)

迁移方法（优先使用memfs）

Export → Copy → Sync

导出 → 复制 → 同步

This is the recommended flow:

Export the source agent's memfs to a temp directory

bash

letta memfs export --agent <source-agent-id> --out /tmp/letta-memfs-<source-agent-id>

Copy the files you want into your own memfs

```
system/
```
= attached blocks (always loaded)
root = detached blocks

Example:

bash

cp -r /tmp/letta-memfs-agent-abc123/system/project ~/.letta/agents/$LETTA_AGENT_ID/memory/system/
cp /tmp/letta-memfs-agent-abc123/notes.md ~/.letta/agents/$LETTA_AGENT_ID/memory/

Sync to API

bash

letta memfs sync --agent $LETTA_AGENT_ID

This gives you full control over what you bring across and keeps everything consistent with memfs.

这是推荐流程：

将源Agent的memfs导出到临时目录

bash

letta memfs export --agent <source-agent-id> --out /tmp/letta-memfs-<source-agent-id>

将你需要的文件复制到自有memfs中

```
system/
```
= 已挂载块（始终加载）
根目录 = 未挂载块

示例：

bash

cp -r /tmp/letta-memfs-agent-abc123/system/project ~/.letta/agents/$LETTA_AGENT_ID/memory/system/
cp /tmp/letta-memfs-agent-abc123/notes.md ~/.letta/agents/$LETTA_AGENT_ID/memory/

同步到API

bash

letta memfs sync --agent $LETTA_AGENT_ID

该方案可让你完全控制需要迁移的内容，同时保证所有内容与memfs保持一致。

Legacy Fallback (only if memfs is disabled)

旧版降级方案（仅当memfs未启用时使用）

If memfs is not enabled, you can use block-level commands:

```
letta blocks list
```
```
letta blocks copy
```
```
letta blocks attach
```

⚠️ Do not use these if memfs is enabled — they can diverge from file-based edits.

如果未启用memfs，你可以使用块级命令：

```
letta blocks list
```
```
letta blocks copy
```
```
letta blocks attach
```

⚠️ 如果已启用memfs请勿使用这些命令——它们会导致与基于文件的编辑内容不一致。

Handling Duplicate Label Errors

处理重复标签错误

You cannot have two blocks with the same label. If you try to copy/attach a block and you already have one with that label, you'll get a

duplicate key value violates unique constraint

error.

Solutions:

Use
--label
(copy only): Rename the block when copying:

bash

letta blocks copy --block-id <id> --label project-imported

Use
--override
(copy or attach): Automatically detach your existing block first:
bash
```
letta blocks copy --block-id <id> --override
letta blocks attach --block-id <id> --override
```
If the operation fails, the original block is automatically reattached.
Manual detach first: Use the
```
memory
```
tool to detach your existing block:
```
memory(agent_state, "delete", path="/memories/<label>")
```
Then run the copy/attach script.

Note:

letta blocks attach

does NOT support

--label

because attached blocks keep their original label (they're shared, not copied).

不可存在两个标签相同的块。 如果你尝试复制/挂载的块的标签已存在，会收到

duplicate key value violates unique constraint

错误。

解决方案：

使用
--label
参数（仅复制场景可用）：复制时重命名块：
bash
```
letta blocks copy --block-id <id> --label project-imported
```
使用
--override
参数（复制或挂载场景均可使用）：自动先卸载现有块：
bash
```
letta blocks copy --block-id <id> --override
letta blocks attach --block-id <id> --override
```
如果操作失败，原有块会自动重新挂载。
先手动卸载： 使用
```
memory
```
工具卸载现有块：
```
memory(agent_state, "delete", path="/memories/<label>")
```
再执行复制/挂载脚本。

注意：

letta blocks attach

不支持

--label

参数，因为已挂载块会保留原有标签（它们是共享而非复制的）。

Workflow

工作流

Step 1: Identify Source Agent

步骤1：确定源Agent

Ask the user for the source agent's ID (e.g.,

agent-abc123

If they don't know the ID, invoke the finding-agents skill to search:

Skill({ skill: "finding-agents" })

Example: "What's the ID of the agent you want to migrate memory from?"

请用户提供源Agent的ID（例如

agent-abc123

）。

如果用户不知道ID，调用finding-agents技能进行搜索：

Skill({ skill: "finding-agents" })

示例：「你要迁移内存的源Agent的ID是什么？」

Example: Migrating Project Memory

示例：迁移项目内存

Scenario: You're a new agent and want to inherit memory from an existing agent "ProjectX-v1".

Get source agent ID from user: User provides:
```
agent-abc123
```

Export their memfs:

bash

letta memfs export --agent agent-abc123 --out /tmp/letta-memfs-agent-abc123

Copy the relevant files into your memfs:

bash

cp -r /tmp/letta-memfs-agent-abc123/system/project ~/.letta/agents/$LETTA_AGENT_ID/memory/system/

Sync:

bash

letta memfs sync --agent $LETTA_AGENT_ID

场景：你是一个新Agent，想要从现有Agent「ProjectX-v1」继承内存。

从用户处获取源Agent ID： 用户提供：
```
agent-abc123
```

导出源Agent的memfs：

bash

letta memfs export --agent agent-abc123 --out /tmp/letta-memfs-agent-abc123

将相关文件复制到你的memfs中：

bash

cp -r /tmp/letta-memfs-agent-abc123/system/project ~/.letta/agents/$LETTA_AGENT_ID/memory/system/

同步：

bash

letta memfs sync --agent $LETTA_AGENT_ID