Migrating existing memory

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.

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.