claude-migrate-memory-to-doc
Migrates Claude Code personal memory (the per-project memory/ directory) into tool-agnostic reference docs so other AI CLIs that auto-load AGENTS.md (Codex primarily) can read the same user profile and preferences
Install / Use
npx skills add daymade/claude-code-skills --skill claude-migrate-memory-to-docInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of claude-migrate-memory-to-doc
claude-migrate-memory-to-doc scores 92/100 on our quality scale, 913th of 4,698 Development & Engineering skills we index (top 20%).
Its SKILL.md is 16 KB long, well organised into 14 sections with 2 code examples: a thorough specification that gives an agent plenty to work with.
With 1,426 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so claude-migrate-memory-to-doc is actively maintained.
- Our last check on 2026-10-27 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
claude-migrate-memory-to-doc compared with similar skills
All 4 of these similar skills score higher than claude-migrate-memory-to-doc; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| claude-migrate-memory-to-doc (this skill)by daymade | 92 | 1.4k | 53d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install claude-migrate-memory-to-doc?
- Run
npx skills add daymade/claude-code-skills --skill claude-migrate-memory-to-doc. The install tabs above show the steps for each supported agent. - Which AI agents does claude-migrate-memory-to-doc work with?
- It is written for Claude Code, Cursor and OpenAI Codex, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is claude-migrate-memory-to-doc safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is claude-migrate-memory-to-doc still maintained?
- The repository was last updated about 2 months ago, so claude-migrate-memory-to-doc is actively maintained.
Skill content
View source on GitHubname: claude-migrate-memory-to-doc disable-model-invocation: true description: >- Migrates Claude Code personal memory (the per-project memory/ directory) into tool-agnostic reference docs so other AI CLIs that auto-load AGENTS.md (Codex primarily) can read the same user profile and preferences. Use when the user says "migrate my memory", "my memory is locked to Claude Code", "make Codex/Cursor read my profile", or reports memory has grown bloated with content that should be shared across tools. Also use it to retire a project's auto memory entirely (turn it off, move everything into documents, archive the directory).
Migrate Claude Code Memory to Tool-Agnostic Docs
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.
This skill moves the cross-tool-shareable content out of memory into a tool-agnostic location, and leaves memory as a thin handoff cache. The real problem it solves is tool lock-in, not "messy memory".
This skill runs inline (never context: fork): it spawns parallel review subagents and runs codex via Bash — a forked subagent could do neither.
First: which goal?
| Goal | The user wants | Path | |---|---|---| | A — end tool lock-in | other AI tools to read the same profile and preferences; memory stays as a thin handoff cache | the Workflow below, all phases | | B — retire auto memory | a project to stop using auto memory, with documents owning everything it held | references/retire_auto_memory.md; from the Workflow below use Phase 1's scope table and Phase 6's archive rules, and do Phases 2 and 5 only if the user also wants Codex to read the result |
Goal B has no "stays in memory" bucket: handoff state, external pointers and pending rulings need a document home, the memory directory ends empty, and the project switch is turned off and proven with a control probe. When the request does not say which goal, ask.
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.
- Claude Code auto-preloads a reference only via
@importsyntax. A plain-text pointer ("see~/.claude/references/user/foo.md") is on-demand: the agent must choose to open it. - Codex is stricter: it does not parse or follow text paths written inside CLAUDE.md at all. It only auto-injects the doc files themselves (its
AGENTS.md/ configured fallback) along the~/.codex → git-root → cwdchain. Reference files named anything else, sitting in~/.claude/references/, are never auto-loaded by Codex.
Therefore the architecture must be a two-layer split:
| Layer | Where | Guarantee |
|---|---|---|
| Guaranteed-hit — the few facts that must be true every turn | inlined into CLAUDE.md body (both tools inject it) | always present |
| On-demand detail — full profile, war-stories, edge cases | references/ files, reached by pointer | loaded when relevant |
Putting the hardcore facts only in a reference and trusting a pointer is the #1 way this migration silently fails. Inline them.
Tool-agnostic architecture
~/.claude/CLAUDE.md global instructions — BOTH tools inject this.
Inline the hardest user facts here (a short "User context" section).
~/.claude/references/user/ SSOT for profile / preferences / methodology / personal affairs.
~/.claude/references/user-profile.md hub: condensed core + index into the user/ files
~/.codex/AGENTS.md ──symlink──▶ ~/.claude/CLAUDE.md
so Codex's GLOBAL layer injects the same file Claude Code reads.
~/.codex/config.toml raise project_doc_max_bytes — Codex truncates docs at 32 KiB by default,
which silently drops the back half of a long CLAUDE.md.
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-rootAGENTS.md, not~/.codex/) — not implemented or verified here.
Workflow
Copy this checklist into your working notes and check items off:
Memory → Tool-Agnostic Doc Migration:
- [ ] Phase 1: Diagnose & scope — classify every memory file by SCOPE
- [ ] Phase 2: Tool-agnostic migration — references/ + inline hardcore + symlink + config
- [ ] Phase 3: Multi-agent review — 4 parallel reviewers
- [ ] Phase 4: Fix everything review surfaced
- [ ] Phase 5: VERIFY BY RUNNING CODEX (not by reasoning)
- [ ] Phase 6: Memory cleanup — clean / thin / keep + soft-delete to backup
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.
The short version:
- Team rules / standards / SOPs → project
CLAUDE.mdordocs/(version-controlled, team-visible). - Cross-tool user profile / collaboration preferences / methodology / personal affairs →
~/.claude/references/user/(tool-agnostic). This is the bucket that migrates. - Temporary handoff snapshots / external system pointers → stay in memory. This is memory's legitimate purpose; do not migrate them. (Goal B: these go to documents instead, see
references/retire_auto_memory.md§4.)
Before calling any entry "not covered anywhere", search every place that could own it: global and project instruction files, ~/.claude/references/, every skill source repository (public and private), project docs and handover packs, and hook or script headers. Name all of these roots in any sub-agent prompt — an agent searches only the roots it is told about. Calibrate each search command on a string you know exists before trusting a zero.
Do NOT migrate everything. Over-migrating handoff state into long-lived docs is its own mistake. But do look at the whole directory — not just feedback_*.md — because project SOPs and operational war-stories often sit in project_*.md or architecture_*.md files and belong in the repo's docs.
Also flag private-context / PII in this pass: a memory file that maps system usernames to real names, private contacts, or other personally identifying information should stay in private memory even if it is project-relevant. Project docs are version-controlled and potentially shared; identity-mapping belongs in the thin handoff layer.
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.
For each "migrates" item, move the content into ~/.claude/references/user/ (group by theme into a handful of files + a user-profile.md hub). Then wire the two-layer architecture:
- Inline the hardcore into a
# User contextsection near the top of~/.claude/CLAUDE.md(within the first ~32 KiB so Codex sees it): the 3–6 facts that must hold every turn (e.g. how to address the user, hard preferences, the single most important identity fact). Everything else stays as pointers. - Symlink
~/.codex/AGENTS.md → ~/.claude/CLAUDE.md(only if~/.codex/AGENTS.mdis absent or an empty placeholder — never clobber a real file). - Raise
project_doc_max_bytesin~/.codex/config.tomlif CLAUDE.md exceeds 32 KiB. - Update the project's knowledge-storage rule (if one exists) so "user preferences → memory" doesn't contradict the new "user profile →
~/.claude/references/user/" reality.
Exact directory layout, the hub-and-spoke pattern, and the governance-rule fix: references/tool_agnostic_migration.md.
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.
Agent findings are hypotheses, not verdicts — filter them (probability × cost × does-it-actually-happen) before acting.
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.
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. Run codex from any dir with --skip-git-repo-check, match its session log by session id (not by mtime), and grep for your inlined hardcore section + a back-of-file string. The inlined section may be titled # User context, # 用户上下文, or whatever localization the user uses — grep for the actual heading string, not a hardcoded English one. A passing run greps 1 for that heading and 1 for the back-half string (if CLAUDE.md > 32 KiB). The exact, empirically-verified command block — --skip-git-repo-check, session-id extraction (it's in the header, not the tail), the 32 KiB check, plus the < 32 KiB and codex-not-installed shortcuts and expected console output — is in references/review_and_verification.md. Use it verbatim; don't hand-roll a variant here (that's how the two copies drift).
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").
- Keep — legitimate handoff / already a clean pointer → leave it. (Not in Goal B: everything is archived.)
Update the memo
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
