Memory promotion tool for Claude Code — scans memory/errors.md and memory/learnings.md in the current project and upgrades qualifying entries to permanent memory (~/.claude/CLAUDE.md or project MEMORY.md).
/promote-memory
No arguments. Automatically scans the current project's memory directory.
Step 1 — Locate paths: resolves PROJECT_MEMORY_DIR from the current working directory, confirms source files exist.
Step 2 — Invoke memory-promoter agent: the agent reads errors.md and learnings.md, evaluates each status:new entry against promotion criteria, and writes qualifying entries to the appropriate target file.
Promotion criteria:
| Source | Condition |
|---|---|
errors.md |
status:new + both "root cause" and "solution" fields filled; or same error pattern appears ≥2 times |
learnings.md |
status:new + both "content" and "applicable context" fields filled; or entry is ≥7 days old with both fields filled |
Target selection:
| Entry type | Target |
|---|---|
| Project-specific (contains project path, name, or tech stack) | MEMORY.md in project memory dir |
| General (keywords: "all projects", "universal", "any project") | ~/.claude/CLAUDE.md |
| Undetermined | MEMORY.md (conservative default) |
Step 3 — Show report:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Memory Promotion complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Promoted to ~/.claude/CLAUDE.md: X entries
Promoted to MEMORY.md: Y entries
Skipped (criteria not met): Z entries
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Full log: <SCRATCH_DIR>/promotion_report.md
Promoted entries are marked status:promoted in the source file and kept for audit. A separate memory file per entry is written into memory/errors/ or memory/learnings/.
/plugin marketplace add easyfan/promote-memory
/plugin install promote-memory@promote-memory
git clone https://github.com/easyfan/promote-memory
cd promote-memory
bash install.shbash install.sh --dry-run # preview without writing
bash install.sh --uninstall # remove installed files
CLAUDE_DIR=/custom bash install.sh # custom Claude config pathcp commands/promote-memory.md ~/.claude/commands/
cp agents/memory-promoter.md ~/.claude/agents/- When to run: every 3–5 work sessions; or when
errors.mdhas ≥5status:newentries; or the same error appears ≥2 times - Before running: fill in the "root cause" and "solution" fields manually for
status:newerrors — entries missing these fields will be skipped - Concurrency: avoid running in multiple projects simultaneously — concurrent writes to
~/.claude/CLAUDE.mdmay lose data
~/.claude/
├── commands/
│ └── promote-memory.md # /promote-memory slash command
└── agents/
└── memory-promoter.md # promotion logic agent (called automatically)
promote-memory/
├── .claude-plugin/
│ ├── plugin.json # CC plugin manifest
│ └── marketplace.json # marketplace entry
├── commands/promote-memory.md
├── agents/memory-promoter.md
├── evals/evals.json
├── install.sh
└── package.json
- Claude Code CLI
- No other dependencies
evals/evals.json contains 5 test cases:
| ID | Scenario | What is verified |
|---|---|---|
| 1 | Both errors.md and learnings.md present, entries complete | Both files promoted, report shows counts |
| 2 | Only errors.md present (learnings.md missing) | Promotes errors only, no crash on missing file |
| 3 | Single complete error entry | Promoted count > 0, target file mentioned |
| 4 | Incomplete entry (missing "solution" field) | Entry skipped, report shows skip reason |
| 5 | errors.md already promoted, fresh learnings entry | Only learnings promoted, errors correctly skipped |
MIT
