| name | memory-merge |
| description | Resolve conflicts and consolidate duplicate memories in .claude/memory/. Invoke after git pull surfaces conflict markers in memory files, when two memory files cover overlapping topics, when project.md hot cache has grown past ~100 lines, or when the user asks to "clean up memory" / "merge memories". Do not run proactively without a trigger — merging rewrites team-shared files. |
Memory Merge
.claude/memory/ is committed, so multiple devs (and their agents) write in parallel. Conflicts and duplicates are expected. This skill resolves them without data loss.
The guiding rule: zero knowledge loss, minimum redundancy, maximum scannability. Every merge is a curation step, not a concat.
When to invoke
git status shows conflict markers in .claude/memory/- Two deep files clearly cover the same topic (e.g.,
auth.md + auth-decision.md)
project.md or reference.md exceeds ~100 lines- User asks to clean up, consolidate, or prune memory
Do NOT invoke speculatively. Merging without a trigger risks rewriting valid team memory.
Merge flow
1. Detect
Run one of:
git diff --name-only --diff-filter=U .claude/memory/
grep -r '<<<<<<<' .claude/memory/
wc -l .claude/memory/project.md .claude/memory/reference.md
Cross-reference: for each topic slug in a conflicted/oversized file, grep the rest of .claude/memory/ for overlapping topics.
2. Classify
| Pattern | Meaning | Resolution |
|---|
| Same file, different section | Additive conflict (both devs added content) | Keep both, re-sort |
| Same section, different phrasing | Semantic duplicate | Merge into one paragraph, preserve richer detail |
| Same section, conflicting content | One is stale or wrong | Use last-updated + authors + code reality to decide winner; mark loser with supersedes or delete |
| Two separate files, same topic | Duplicate topic | Consolidate into the better-named file; the other gets supersedes: [kept-slug] and is deleted |
3. Propose
Show the user a diff plan before writing:
proposal:
keep: .claude/memory/project/auth-decision.md (richer, last-updated 2026-04-10)
drop: .claude/memory/project/auth.md (older, last-updated 2026-03-01)
merge: 2 sentences from dropped file into kept file's "Trade-offs" section
index: remove auth.md pointer from project.md
Await approval unless the conflict is purely syntactic (e.g., both devs added different pointers to project.md — safe to keep both).
4. Apply
- Update
last-updated on the surviving file
- Append dropped file's slug to
supersedes: [...]
- Delete the dropped file (
git rm)
- Update
project.md / reference.md hot cache — remove dead pointers, keep the canonical one
- Update
INDEX.md TOC
5. Verify
grep -r '<<<<<<<' .claude/memory/
wc -l .claude/memory/project.md
git diff --stat .claude/memory/
Consolidating oversized hot cache
When project.md exceeds ~100 lines without a conflict:
- Identify the least-referenced pointers (ask user, or use heuristic: oldest
last-updated on the deep file)
- Remove those pointers from
project.md
- Leave deep files intact — recall via
INDEX.md + grep still works
- If a deep file is also >90 days stale, move to
project/archive/ or delete if obsolete
Safety rules
- Never merge conflicts without user approval unless the conflict is additive and non-semantic
- Never delete without
supersedes trail or explicit user OK — memory deletion is hard to audit
- Never mass-regenerate memory files — edits only, preserve authorship and timestamps
- Commit the merge as its own commit — don't bundle with feature work. Message:
chore(memory): consolidate <topic>
Pairs with
memory skill — invoked on write, this skill on consolidatememory-compact skill — end-of-session compaction; merge-conflict resolution is different from compaction, don't confuse
Red flags
- The merge would drop a memory with
confidence: 0.9 → stop, show user
- The conflict spans >5 files → probably a bad merge upstream, investigate before consolidating
supersedes chains forming loops (A→B→A) → someone's merging in a loop; reset to latest timestamp
