claude migrate memory to doc

Other Community

Skill notes

Why this skill exists

Claude Code's personal memory lives in ~/.claude/projects/<project-slug>/memory/. It is locked to Claude Code: not version-controlled with the repo, invisible to every other tool. The moment the user runs Codex, Cursor, or any other AI CLI in the same directory, those tools cannot read "who the user is / how to work with them" — even though a user profile and collaboration preferences are exactly what any AI assistant should read first.

The core insight — read this before touching anything

The hard part is not moving files. It is this: A reference file reached only by a plain-text pointer is read on-demand and is NOT guaranteed to load — in either tool.

Tool-agnostic architecture

Scope note: the wiring (the ~/.codex/ symlink, the config edit, and the Phase 5 verification) is Codex-specific and was verified against Codex only (2026-06). The ~/.claude/references/user/ content layer transfers to any tool that auto-loads a project doc, but Cursor and others need their own wiring (Cursor reads .cursor/rules / a project-root AGENTS.md, not ~/.codex/) — not implemented or verified here.

Workflow

Copy this checklist into your working notes and check items off:

Phase 1 — Diagnose & scope

Preflight — find the memory directory. Claude Code memory lives at ~/.claude/projects/<project-slug>/memory/, where <project-slug> is the working directory path with / → -. A user may have memory across several projects — list them with ls ~/.claude/projects/*/memory/ and pick (or merge) the project(s) whose memory holds the cross-tool user content. List every file under that memory directory. Classify each by scope, not by "is it messy". Full decision table and the agent-can't-judge-private-context caveat: read references/diagnosis_and_scoping.md.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Other
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@daymade · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Phase 1 — Diagnose & scope

Preflight — find the memory directory. Claude Code memory lives at `~/.claude/projects/<project-slug>/memory/`, where `<project-slug>` is the working directory path with `/` → `-`. A user may have memory across several projects — list them with `ls ~/.claude/projects/*/memory/` and pick (or merge) the project(s) whose memory holds the cross-tool user content. List every file under that memory directory. Classify each by scope, not by "is it messy". Full decision table and the agent-can't-judge-private-context caveat: read references/diagnosis_and_scoping.md.

02
Phase 2 — Tool-agnostic migration

Snapshot CLAUDE.md first (`cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak`) — you're about to edit it. If `~/.claude/CLAUDE.md` doesn't exist, create it (some users only have a project-level one). If `command -v codex` is empty (Codex not installed): do only steps 1 and 4 below (the `references/` + inline-CLAUDE.md work), and skip the symlink (2), config (3), and all of Phase 5. The content migration still stands; leave a note that wiring Codex later needs the symlink + `project_doc_max_bytes`.

03
Phase 3 — Multi-agent review

Spawn 4 review subagents in parallel (one message, multiple Task calls). Each audits one dimension: content completeness (did any fact get dropped/altered), cross-reference breakage (which `[[links]]` will dangle if memory is deleted), tool-agnostic link integrity (does the symlink/pointer chain actually resolve; does Codex really read it), duplication/drift (does a reference duplicate a CLAUDE.md rule). Exact prompts: references/review_and_verification.md.

04
Phase 4 — Fix

Address what review surfaced. Common real findings (all from a live run): a hub file that forgot to index one of its own children; hardcore facts left only in a reference (move them inline); `[[links]]` in surviving files pointing at to-be-deleted memory (repoint to the new reference); a governance table row updated but the judgment sentence in the same section left contradicting it.

05
Phase 5 — VERIFY BY RUNNING CODEX (do not skip, do not delegate to the user)

The step you'll be tempted to replace with "looks right" or "you can check it yourself later". Don't.

06
Phase 6 — Memory cleanup

For the memory files that did NOT migrate, do one of three things (decision detail in references/diagnosis_and_scoping.md): Clean — expired (past-dated handoffs) or stale (derived counts that should be computed, not stored) → archive. Thin — a handoff that restated a SSOT living elsewhere → cut the duplication, keep only the pointer + the volatile state (e.g. "instance X still billing, shut it down").

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.