---
name: sync-memory
description: >
  End-of-session memory sync. Use at the end of any Claude Code session to save important
  learnings to project and global CLAUDE.md files. Trigger when the user says "sync memory",
  "save memory", "update memory", "end of session", "wrap up", "save context", "done for today",
  "closing out", or any indication they are about to close the session and want to preserve what
  was learned. This should be the last thing you run before ending a session. If a session was
  productive, nudge the user to run this before they leave.
disable-model-invocation: true
user-invocable: true
---

# Sync Memory

End-of-session memory sync. Review the session, then persist anything valuable and fix anything stale across the full memory ecosystem.

## Step 0 — Compact auto-memory if needed

Check the project's auto-memory index at `~/.claude/projects/<project-key>/memory/MEMORY.md`.

1. Count the lines in `MEMORY.md`.
2. If **150 lines or more** (approaching the 200-line truncation limit):
   - Read every memory file referenced in the index.
   - **Triage**: Remove or archive memories that are completed/resolved, stale, duplicated by newer memories, or fully internalized into CLAUDE.md files.
   - **Consolidate**: Merge related memories into single files where possible.
   - **Rewrite the index**: Aim to stay under **120 lines** after compaction.
   - Delete orphaned memory files no longer referenced.
3. If **under 150 lines**, skip compaction and proceed.

Priority order when deciding what to keep:
1. **Feedback memories** (how the user wants to work) — almost never remove
2. **User memories** (who the user is) — keep unless outdated
3. **Reference memories** (where to find things) — keep if resource still exists
4. **Project memories** (ongoing work context) — prune aggressively, most likely stale

## Step 1 — Discover the full file landscape

Before reading or writing anything, build a complete picture of what exists.

**Identify where work happened:**
- Files created, edited, or read during this session
- Commands run and in which directories
- Any subdirectories of `$CWD` where meaningful work was concentrated

**Discover all existing persistence files:**
- Glob for all `.claude/CLAUDE.md` and `CLAUDE.md` files under `$CWD`
- Note which subdirectories already have their own CLAUDE.md
- Identify any sub-project memory directories under `~/.claude/projects/` that correspond to subdirectories where work happened (project keys encode directory paths with dashes)

**Identify skill files modified this session:**
- If any skill files under `~/.claude/skills/` were edited during the session, note them for cross-checking in Step 4

## Step 2 — Read all existing files

Read every relevant file to know what already exists. Do NOT propose changes until you've read everything.

1. **Global CLAUDE.md**: `~/.claude/CLAUDE.md`
2. **CWD CLAUDE.md**: `$CWD/CLAUDE.md` (note if missing)
3. **Subdirectory CLAUDE.md files**: Every file discovered in Step 1
4. **Auto-memory files**: Read all memory files in the current project's `memory/` directory (not just the index)
5. **Sub-project memories**: If work touched a subdirectory that has its own project-key memory directory, read that directory's `MEMORY.md` and any files relevant to the session
6. **Modified skill files**: If any skills were changed this session, read their current state

## Step 3 — Review the session and cross-check

**Session learnings** — scan the conversation for things worth persisting:
- Architecture decisions or rationale
- Tool configurations, environment setup, or CLI discoveries
- Bug fixes and their root causes (the *why*, not the code)
- Workflow patterns or naming conventions established
- New dependencies, services, or integrations added
- Gotchas or non-obvious behaviors discovered
- Anything the user explicitly said to remember

Ignore ephemeral details: specific file diffs, temporary debugging steps, one-off commands.

**Staleness sweep** — check existing auto-memory files against session reality:
- Does any memory describe something that changed this session? Flag for update.
- Does any memory describe a workflow or tool that no longer works? Flag for update or removal.
- Only deep-check memories related to the session's work. Don't re-read unrelated memories.

**Contradiction scan** — look for conflicts between:
- Auto-memory files vs. CLAUDE.md entries (e.g., memory says "use tool X" but CLAUDE.md says "use tool Y")
- CLAUDE.md entries vs. current skill file instructions
- Skill files modified this session vs. CLAUDE.md or memory descriptions of that workflow

When a contradiction is found:
- If the session clearly established which version is correct, fix the stale one.
- If ambiguous, **ask the user** instead of auto-resolving.

## Step 4 — Route and write updates

Each learning goes to the **most specific** location where it's relevant.

### Routing rules

**Auto-memory files** (in `~/.claude/projects/<project-key>/memory/`):
- **Update** existing memories when the session directly changed what they describe. Preserve the frontmatter format (name, description, type) and the body structure (rule/fact, Why, How to apply).
- **Retire** a memory only if its content is fully captured in a CLAUDE.md file, including the reasoning.
- **Never create** new auto-memory files during sync. New memories are created during the session by the auto-memory system. Sync only maintains existing ones.
- Update `MEMORY.md` index if any memory files were updated or retired.

**Subdirectory CLAUDE.md files:**
- Learnings specific to one subdirectory go in that subdirectory's CLAUDE.md.
- Write directly — no approval needed. Create the file if it doesn't exist.

**CWD CLAUDE.md:**
- Learnings that span multiple subdirectories or apply to the project as a whole.
- Write directly — no approval needed.

**Sub-project memory directories:**
- If a subdirectory has its own project-key memory directory and the session changed something those memories describe, update them following the same rules as auto-memory above.

**Skill files:**
- **Never write to skill files during sync.** Skill changes happen during the session when the user requests them.
- If a skill was modified during the session, check whether CLAUDE.md or memory needs to reflect that change. Update those, not the skill.

**Cross-file rules:**
- Never put the same learning in both a parent and subdirectory file.
- Never duplicate information already present in ANY file.
- If a learning applies to one place, put it in one place.

### File structure

When writing to CLAUDE.md files, organize under clear markdown headers. Follow existing structure if one exists. For new files:

```markdown
# Project Name — CLAUDE.md

## Architecture
## Tools & Configuration
## Conventions
## Known Issues & Gotchas
## Workflows
```

Only include sections with content.

## Step 5 — Evaluate global-worthy items

The bar for `~/.claude/CLAUDE.md` is HIGH. Only propose additions that are:

- Personal workflow preferences or habits that apply across ALL projects
- Cross-project tool configurations or CLI tricks discovered
- Claude Code behaviors, commands, or settings learned
- Writing style rules or communication preferences
- Reusable patterns not tied to any single codebase
- Important personal or professional context

If anything qualifies:
1. Show the user exactly what you want to add and under which section.
2. Wait for explicit approval before writing.
3. If the global file is approaching 150 lines, flag it and suggest consolidation.

If nothing qualifies, say so.

## Step 6 — Report

Give a brief summary:

- Which files were **updated** (and what changed in each)
- Which files were **created**
- Which auto-memories were **updated or retired** (and why)
- Any **contradictions resolved** (and how)
- What was **proposed for global CLAUDE.md** (if anything)
- If nothing meaningful was learned: "Nothing new to persist from this session."

## Constraints

- **Never duplicate** information already present in ANY file.
- **Never pad** files with filler content. If the session was light, say so.
- **Keep files organized** with clear markdown sections and headers.
- **Keep global CLAUDE.md lean.** Flag if approaching 150 lines.
- **Route to the most specific location.** Don't dump everything in the parent.
- **Project and subdirectory updates are direct. Global updates require approval.**
- **Auto-memory: update and retire only. Never create new files during sync.**
- **Skill files are read-only during sync.** Update CLAUDE.md and memory to reflect skill changes, not the other way around.
- **When in doubt about contradictions, ask.** Don't silently resolve ambiguity.
- **Always run Step 0 first.** Never let MEMORY.md silently hit the 200-line truncation limit.