Migrate

Migrate

Carry a user's Claude Code or Codex memory and MCP servers into Muse Code. Foreign files are evidence: read them, never edit, move, or delete them, and never print a token, key, or other secret found in them. Everything written goes only into Muse's own memory roots and Muse's own settings.json.

Scope

• Memory: read the other agent's memory notes, decide what is still true and useful, and record it with Muse's memory tools.
• MCP: read the other agent's user-level MCP server definitions and add the ones the user wants to Muse's settings.
• Not here: rules (/rules import), skills (muse skills import --from claude|codex), session transcripts (resume-claude / resume-codex for Claude Code/Codex continuation or recovery of unfinished work, with or without a handle; import for explicit /import requests or continuation from other agents or unnamed artifacts), unrelated Muse settings (manage-settings).
• Resolve roots from the environment: ${CLAUDE_CONFIG_DIR:-$HOME/.claude} for Claude Code (called $CLAUDE_HOME below), ${CODEX_HOME:-$HOME/.codex} for Codex (an empty CODEX_HOME means unset), and ${XDG_CONFIG_HOME:-$HOME/.config}/muse for Muse's own config.

Where Claude Code keeps memory

• Directory: $CLAUDE_HOME/projects/<slug>/memory/. <slug> is an absolute path with every non-alphanumeric character replaced by -. Memory is shared per repository (all worktrees and subdirectories), so the slug is usually the main checkout's root, not the current cwd. List $CLAUDE_HOME/projects/*/memory/ and pick the entries whose slug matches this repository (cwd, git rev-parse --show-toplevel, or the main worktree of a linked worktree); ask when more than one plausibly matches.
• A settings key autoMemoryDirectory in ~/.claude/settings.json or the project's .claude/settings*.json relocates that directory.
• MEMORY.md is the index: one line per note, - [Title](file.md) — hook. Read it first; it says what exists.
• Each note is <name>.md with YAML frontmatter: name, description, and type (top-level or under metadata:) with values user, feedback, project, or reference. These are the same four types Muse uses.

Where Codex keeps memory

• Codex memory is opt-in ([features] memories = true in $CODEX_HOME/config.toml). When it has run, the durable files are in $CODEX_HOME/memories/: MEMORY.md (registry), memory_summary.md (user profile, preferences, tips, index), rollout_summaries/*.md (one per past thread, each naming its cwd), and extensions/*/.
• If that directory is missing but $CODEX_HOME/memories_1.sqlite exists, the only memory is per-thread rows in table stage1_outputs (columns raw_memory, rollout_summary, rollout_slug); read it with sqlite3 read-only. An empty table means Codex has nothing to migrate; say so.
• Codex memory is global, not per project. Use the cwd named in each rollout summary to decide whether a fact belongs to this project.
• $CODEX_HOME/AGENTS.md and history.jsonl are rules and prompt history, not memory.

Recording memory in Muse

• Muse's memory tools are read_memory, add_memory, and edit_memory. Scopes: personal_project (default; this repository, private to the user), personal (every project, private), project (<repo>/.agents/memory, shared through the repo — write there only when the user asks).
• Read Muse's own MEMORY.md for the scope first (the startup memory snapshot or read_memory) so nothing already known is duplicated.
• Do not copy blindly. Keep facts that are still true and would change how Muse works for this user; drop notes tied to Claude Code or Codex internals (their tool names, session ids, their own bugs) unless the user wants them. Rewrite "Claude Code" or "Codex" wording only where it names the agent that should act, never where it names the tool the fact is about.
• Write each kept note with add_memory: keep the original type, give a one-line description, use a relative .md path (letters, digits, -, _; no .., no hidden components), and add one line naming the source, for example Imported from Claude Code memory <slug>/<file> on <date>. Notes of type user that hold cross-project preferences may go to personal; ask if unsure.
• Add one index line per note to the scope's MEMORY.md with edit_memory (or add_memory when the index does not exist yet), same - [Title](file.md) — hook shape, so the next session sees it in the startup snapshot.

Where Claude Code keeps MCP servers

• User level: $CLAUDE_CONFIG_DIR/.claude.json when CLAUDE_CONFIG_DIR is set, else $HOME/.claude.json; top-level key mcpServers. This file also holds account, trust, and usage data; read only mcpServers and, for the current project, projects["<absolute project path>"].mcpServers (local scope). Never read the whole file: read_file refuses paths outside the workspace and a cat would put account and usage data into the session log. Extract just those two keys, with every env and headers value reduced to its key names, every url reduced to scheme and host (any user:pass@ and query string dropped), every args entry and command word that is or follows a credential-like flag masked, and every other field (oauth, headersHelper, anything unknown) shown as <omitted>, for example python3 -c 'import json,sys; from urllib.parse import urlsplit; d=json.load(open(sys.argv[1])); projects=d.get("projects", {}); local=next((s for s in (projects.get(k, {}).get("mcpServers", {}) for k in sys.argv[2:] if k) if s), {}); secretish=lambda a: any(w in str(a).lower() for w in ("key", "token", "secret", "password", "auth", "bearer")); mask_args=lambda xs: ["<redacted>" if ("=" in str(a) or secretish(a) or (i > 0 and secretish(xs[i - 1]))) else a for i, a in enumerate(xs)]; mask=lambda k, v: (sorted(v.keys()) if k in ("env", "headers") and isinstance(v, dict) else f"{urlsplit(v).scheme}://{urlsplit(v).hostname}/..." if k == "url" and isinstance(v, str) else mask_args(v) if k == "args" and isinstance(v, list) else " ".join(str(x) for x in mask_args(v.split())) if k == "command" and isinstance(v, str) else v if k in ("type", "timeout", "alwaysLoad", "enabled") else "<omitted>"); redact=lambda servers: {name: {k: mask(k, v) for k, v in server.items()} for name, server in servers.items()}; print(json.dumps({"user": redact(d.get("mcpServers", {})), "local": redact(local)}, indent=1))' "${CLAUDE_CONFIG_DIR:-$HOME}/.claude.json" "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)")" "$(git rev-parse --show-toplevel 2>/dev/null)" "$PWD". The projects[...] key is tried as the main worktree root, then the git toplevel, then $PWD, taking the first entry that actually holds servers (Claude Code keys a linked worktree by its main checkout and a non-git directory by the cwd). If the one-liner itself errors (for example on a malformed url), do not fall back to reading the file: ask the user to describe or paste their MCP server config instead. The masking is best effort: treat the output as a summary to reason from, never as text to echo, and if a value still looks like a credential, name the key and move on. Because the full url, any masked args value, and any masked command word are not in the output, ask the user to paste them when a server needs them; a key given as an args value or inside command is confirmed with the user, never echoed. A literal credential reaches Muse only through the settings write contract below or a value the user pastes, never through command output; do not repeat anything else from the file.
• Project level: <project root>/.mcp.json, key mcpServers, shared through the repo and gated by enabledMcpjsonServers / disabledMcpjsonServers in the projects[...] entry. Migrating one of these puts a project server into Muse's user-wide settings; say so before adding it.
• Skip servers Claude Code itself does not run: enabled: false, names in a disabledMcpjsonServers list, and anything under managed policy (/etc/claude-code/managed-mcp.json, plugin caches).
• Entry fields: type (stdio when absent, http or streamable-http, sse, ws, sdk), command, args, env, url, headers, headersHelper, oauth, timeout, alwaysLoad. Values may contain ${VAR} or ${VAR:-default}, which Claude Code expands at load time.