carlheath Promote Memory
Role: dual-memory triage. Move stable insights from project auto-memory to global memory. Keep ephemeral details where they belong.
Memory architecture
Two layers:
Project auto-memory (
~/.claude/projects/{slug}/memory/)- Auto-captured per project context
- Volatile, often noisy
- Useful for ongoing project context but doesn't accumulate cleanly
Global memory (
~/.claude/memory/)- User-curated, structured
- USER/, SYSTEM/, KNOWLEDGE/, WORK/, learnings/
- Stable, intentional
The skill bridges between them: review the project inbox, promote what's stable.
Three-criteria evaluation
For each memory entry:
| Criterion | Promote if... | Otherwise |
|---|---|---|
| Recurrence | Mentioned in 3+ contexts | Project-scoped only |
| Generality | Applies beyond this project | Keep ephemeral |
| Stability | Hasn't changed in last 30 days | Wait, may change |
If all three are yes: promote. If any is no: keep or delete.
Three actions
1. Promote
Move entry from project memory to a global memory file. Preserve provenance:
---
promoted_from: project/{slug}/memory/{file}
promoted_on: {YYYY-MM-DD}
original_captured: {YYYY-MM-DD}
---
Target file in global memory depends on type:
- Personal facts →
USER/ - Technical patterns →
SYSTEM/PATTERNS.md - Domain knowledge →
KNOWLEDGE/ - Learnings →
learnings/
2. Keep ephemeral
Leave in project memory. Add a last_reviewed: {date} marker so it doesn't get re-evaluated next week.
3. Delete
Remove if:
- Already captured better elsewhere
- One-off context with no general value
- Stale (>90 days, not promoted)
Workflow
1. Scan project memory
List all files in ~/.claude/projects/{slug}/memory/ (or all projects if no specific one).
2. Per-file evaluation
Read each file. Apply the three criteria. Suggest action.
3. Present review
## Memory Review — {date}
### Recommended: PROMOTE (N)
- {file1} → {global path} — Reason: {recurrence + generality + stability}
- {file2} → {global path} — Reason: ...
### Recommended: KEEP EPHEMERAL (M)
- {file3} — Reason: project-scoped, not yet stable
- {file4} — Reason: may change, recheck in 2 weeks
### Recommended: DELETE (K)
- {file5} — Reason: superseded by {global file}
- {file6} — Reason: stale, never promoted
Approve? (y/all/per-row)
4. Execute approved actions
- For PROMOTE: copy to global, mark project file as promoted
- For KEEP: add
last_reviewed:marker - For DELETE: move to
_archived/(don't hard delete)
5. Report
Write a review report to ~/.claude/memory/learnings/memory-reviews/{YYYY-MM-DD}.md:
# Memory review {YYYY-MM-DD}
Promoted: N
Kept ephemeral: M
Deleted: K
Total reviewed: N+M+K
## Promoted entries
[list]
## Notes
[anything notable about the review]
Cadence
Recommended: weekly. Use /loop 7d /promote-memory if the user wants to schedule it.
Anti-patterns
- Promoting unstable memory (gets superseded fast)
- Deleting without archive
- Promoting without provenance metadata
- Skipping the user-approval step
🎯 COMPLETED: [SKILL:promote-memory] [memory review for date X] 🗣️ CUSTOM COMPLETED: [SKILL:promote-memory] [Memory review done]