Memory promotion

Memory Promotion

Claude accumulates instructions in several places that don't automatically stay in sync: a hand-maintained CLAUDE.md, auto-memory files Claude writes on its own, per-project memory, and (for claude.ai users) a separate web-chat memory with no filesystem access at all. Left alone, the same correction gets re-taught in multiple places, or a genuinely important pattern sits in a file that's rarely re-read. This skill finds and reconciles those overlaps.

Instructions

Step 1: Identify what to reconcile

Always include, without asking:

• Personal auto-memory: ~/.claude/memory/MEMORY.md and linked topic files.
• The current project's memory (wherever this skill is invoked from): ~/.claude/projects/<current-project>/memory/. This is a single, cheap directory read, and it's the store most likely to hold a pattern the user learned here but never promoted anywhere global — exactly what this skill exists to catch. Don't wait to be asked; if you wait, the skill only ever surfaces what the user already remembered, which defeats the point.

Proactively offer, but never do without confirmation, the expensive, scope-widening version:

• Additional named project(s) beyond the current one, or a full sweep across everything under ~/.claude/projects/. Mention that other projects with memory exist and ask if the user wants them included — don't stay silent and wait for the user to think to ask. But don't scan them without a yes: this can be slow, and can cross into unrelated or client-separated projects the user didn't intend to expose to this particular cleanup.
• claude.ai web memory — this has no API or filesystem access. Ask the user to paste it (e.g. "List everything in your memory about me, verbatim", or via Settings > Capabilities > "View and edit your memory"). Skip this store entirely if the user is Claude-Code-only.

Step 2: Read current global state

Read ~/.claude/CLAUDE.md in full. Read personal MEMORY.md and every topic file it links to. If the user keeps a separate file for chat-UI-only preferences (some setups do — instructions relevant only to a web chat interface, with no Claude Code equivalent), read that too. Treat it as optional and skip it if it doesn't exist.

Step 3: Scan project-level memory

For the current project plus any additional projects in scope (Step 1), read its MEMORY.md, linked topic files, and any project-local CLAUDE.md / CLAUDE.local.md. Look for two distinct things:

• Patterns already written in project-specific language but actually generic — about how the user works, debugs, or communicates, not a project fact.
• A project-specific incident or decision that has a generalizable lesson underneath it. Extract the why or how it was approached, never the what — a migration that failed because it wasn't tested under concurrent writes isn't a reusable fact, but "test migrations under concurrent load, not just at rest" might be. Only extract a lesson when it's clearly supported by what's written; don't force a generalization out of a fact that's genuinely just project-specific.

Either way, the specific fact itself (paths, service names, exact decisions) stays in project memory — only an abstracted lesson, if one exists, becomes a candidate. Because that lesson comes from a single project, default to proposing it as a feedback-style auto-memory entry (Step 4) rather than an immediate CLAUDE.md promotion, unless it's obviously a strong principle already corroborated elsewhere — CLAUDE.md is for stable, proven-universal rules, not a first draft of one.

Step 4: Diff and categorize

For every candidate (web-memory paste, personal auto-memory entries, project-memory entries), compare against current CLAUDE.md content:

• Already covered → discard, no action.
• New, universal, and relevant to coding/agent work → propose adding to CLAUDE.md.
• New, universal, but only relevant to a chat UI (formatting or artifact preferences with no Claude Code equivalent) → propose adding to the user's chat-UI-preferences file, or suggest creating one if they don't have one.
• New, tied to a file type or recurring task shape, reusable across projects → propose as a new skill, or an addition to an existing matching skill.
• New, narrow, situational, or project-specific → leave it where it is, or add it to personal auto-memory as a feedback-style entry if it's worth remembering outside that one project. Don't promote project-specific facts (paths, service names, one-off decisions) anywhere global.

Step 5: Propose before writing

Show the user a summary of proposed changes, grouped by destination, plus any auto-memory entries that are now redundant with CLAUDE.md and should be retired. Wait for explicit confirmation before editing anything.

Step 6: Apply confirmed changes

Update CLAUDE.md and/or skill files; add feedback-style entries to personal auto-memory where appropriate; delete/retire redundant topic files; update MEMORY.md indexes to remove dangling links to anything deleted.

Step 7: Flag manual steps

If any destination requires a manual step outside the filesystem (e.g. pasting content into a claude.ai settings page), remind the user explicitly — this skill cannot push content there itself.

Examples

Example 1: routine cleanup

User says: "clean up my memory, I feel like I keep repeating myself"

Actions: personal auto-memory + CLAUDE.md + the current project's memory (Steps 1–3), no additional projects, no web memory. Diff, propose 2 promotions to CLAUDE.md and 1 retired duplicate topic file, apply on confirmation.

Example 2: cross-surface sync including claude.ai

User says: "sync my memory across everything, including claude.ai"

Actions: Ask for the web-memory paste, read CLAUDE.md and auto-memory, diff all three, propose changes grouped by destination, apply on confirmation, remind the user to paste any chat-UI-only additions back into claude.ai's settings.

Troubleshooting

No ~/.claude/memory/ directory exists yet. Nothing to reconcile there — proceed with just CLAUDE.md (and project memory / web memory if those are in scope).

User can't or won't paste claude.ai memory. Skip that store and say so in the summary — don't guess or fabricate its contents.

A "generic" pattern turns out to be project-specific on closer read. When in doubt, leave it in project memory rather than promoting it — a false negative (stays put) is cheaper to fix later than a false positive (pollutes a file every session loads).