# Migrating existing memory

> Bringing memory from existing agents and consumer AI products into the format.


Because the format was designed as a superset of shipping memory systems, most migrations are small. This page covers the two directions: memory that already lives in files (agent harnesses), and memory that lives inside a product (consumer assistants).

## Layouts that already conform

If your agent's memory is one of these, there is nothing to do — the directory is already a valid memory root:

- **OpenClaw** (`~/.openclaw/workspace`): `MEMORY.md`, `USER.md`, and `DREAMS.md` are root files; `memory/YYYY-MM-DD.md` daily notes are a progressively disclosed directory.
- **Hermes Agent** (`~/.hermes/memories`): `USER.md` and `HUMAN.md` are root files. No directories yet; the format leaves room to grow into them.
- **Codex** (`~/.codex/memories`): `MEMORY.md` and `memory_summary.md` at the root, with `rollout_summaries/` and other detail deferred in directories, already git-tracked.
- **Claude Code** (`~/.claude/projects/<project>/memory`): `MEMORY.md` is a root index and sibling topic files are read on demand. Optional per-file frontmatter matches the spec's optional frontmatter.

For these, adopting the spec means at most adding a `.memoryspec` marker and, where useful, indexes for directories that lack them.

## Migrating a Letta Code agent

Letta Code's earlier layout kept in-context memory in a nested `system/` tree, with each file individually injected into the prompt. The new layout is a flat root: files at the top of the memory directory are in context, everything else is deferred behind directories.

The migration is a flattening:

1. **Promote** each `system/` file to a root file. Nesting inside `system/` collapses into file names: `system/human/prefs.md` becomes `human_prefs.md`.
2. **Budget check**: the old layout let the in-context tree grow without a visible cost signal. If the flattened root exceeds the recommended budget, this is the moment to demote detail — move the long tail of each topic into a directory and leave a summary at the root.
3. **Index**: write a root `MEMORY.md` describing the remaining directories (`reference/`, `skills/`, projects, notes) so disclosure works from the first session.
4. **Mark**: add `.memoryspec` with the version.

Because Letta Code memory is git-tracked, the whole migration is one commit, and reverting it is one revert. Letta Code agents can run the migration on their own memory using a migration skill, which is how this migration is intended to be exercised: by the agents themselves, with the user reviewing the diff.

> **Note:** Migration is also the right time to apply the spec's judgment rules rather than translating mechanically: content that exists because the *project* demands it belongs in `AGENTS.md`; step-by-step procedures belong in skills; what remains — experience, identity, relationships — is memory.

## Migrating consumer product memory

Consumer assistants keep memory inside the product, but all of them can be exported into memory files:

- **ChatGPT**: Settings → Personalization → Memory shows saved memories ("Manage memories"). Copy them out (or ask ChatGPT to list all its memories about you verbatim) and save them as a root file such as `human.md`, or as topical files if there are many.
- **Claude**: ask Claude to summarize what it remembers about you from its memory, then save the result the same way.
- **Gemini**: Saved Info lists remembered facts; copy them into a root file.

The exported material is typically a few hundred lines of facts and preferences about one person, which is exactly what a root `human.md` is for. Once it lives in a memory directory, any conforming harness can pick it up, and the agent can maintain and extend it from there.

## Verifying a migration

- Every file the agent needs constantly is at the root, and the root is within budget.
- Every directory the agent should know about appears in the root listing, and directories with subdirectories have indexes.
- No index entry points at a path that no longer exists.
- The agent can answer "what do you know about me?" from a fresh session at least as well as before the migration.