promote-memory
Review candidate learnings in Claude Code's native auto memory (`~/.claude/projects/<project>/memory/`, machine-local) and run them through a five-critic council in parallel: generality, staleness, redundancy, evidence, format. Majority vote (3+ of 5) promotes the entry to MEMORY.md
Install / Use
npx skills add pedrohcgs/claude-code-my-workflow --skill promote-memoryInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Education & ResearchSupported Platforms
Our assessment of promote-memory
promote-memory scores 90/100 on our quality scale, 162nd of 421 Education & Research skills we index (top 39%).
Its SKILL.md is 12 KB long, well organised into 22 sections with 2 code examples: a thorough specification that gives an agent plenty to work with.
With 1,598 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 3 months ago, so promote-memory is actively maintained.
- Our last check on 2026-10-30 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-07. Automated pattern scan on 2026-10-07. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
promote-memory compared with similar skills
All 4 of these similar skills score higher than promote-memory; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| promote-memory (this skill)by pedrohcgs | 90 | 1.6k | 3mo ago | SKILL.md |
| last30days-skillby mvanhorn | 100 | 68.0k | today | CLAUDE.md |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
Frequently asked questions
- How do I install promote-memory?
- Run
npx skills add pedrohcgs/claude-code-my-workflow --skill promote-memory. The install tabs above show the steps for each supported agent. - Which AI agents does promote-memory work with?
- It is written for Claude Code, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is promote-memory safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is promote-memory still maintained?
- The repository was last updated about 3 months ago, so promote-memory is actively maintained.
Skill content
View source on GitHubname: promote-memory
description: Review candidate learnings in Claude Code's native auto memory (~/.claude/projects/<project>/memory/, machine-local) and run them through a five-critic council in parallel: generality, staleness, redundancy, evidence, format. Majority vote (3+ of 5) promotes the entry to MEMORY.md. Use when user says "promote memory", "review my learnings", "what should graduate to MEMORY.md", "five-critic council", or as monthly memory maintenance.
argument-hint: "[entry-substring or 'all']"
disable-model-invocation: true
allowed-tools: ["Read", "Write", "Glob", "Grep", "Agent", "Task", "Bash"]
metadata:
author: Claude Code Academic Workflow
version: 1.0.0
<!-- Pattern adapted with attribution from Chris Blattman's claudeblattman v2.1
"Five-critic council" (claudeblattman.com, Apr 2026 continuous-improvement
loop). Blattman uses it to decide what enters his MEMORY layer; we adapt
it to the auto-memory → MEMORY.md promotion question codified in
.claude/rules/meta-governance.md. -->
/promote-memory — five-critic council for memory promotion
The template's meta-governance.md rule splits memory into two tiers:
MEMORY.md(committed, ≤ 200 lines) — generic learnings that help all forkers.- native auto memory (
~/.claude/projects/<project>/memory/— machine-local, typeduser/feedback/project/reference, no size cap on topic files) — machine-specific and user-specific learnings.
The rule says generic patterns should sync via git; personal patterns stay local. What it doesn't say is who decides which is which. /promote-memory operationalizes the call: spawn five critics in parallel, each reviewing the candidate [LEARN] entries on a single dimension, and promote on majority vote (3+ of 5).
When to use
- Monthly memory maintenance. Personal-memory accumulates faster than MEMORY.md; the council periodically harvests the genuinely generic learnings.
- Before sharing a fork. Someone is about to clone your template — what should they inherit?
- After a large project ships. Lessons from a paper or a course cycle deserve curation before the next project starts adding noise.
- Not on a schedule. This skill is user-invoked (
disable-model-invocation), so a scheduled task cannot fire it, and its candidates live in machine-local auto memory that a cloud routine cannot see. Set yourself a monthly reminder and run it in a local session; every promotion waits for your approval anyway.
When NOT to use
- For a single fresh
[LEARN]after a single correction. Just let auto memory record it; let it sit until the next council runs. - For deleting stale entries. Edit MEMORY.md by hand, per
meta-governance.md(dated addendum, or a merge to hold the cap)./promote-memorynever deletes — though near the cap it proposes a demotion (Step 4). - For project-specific context. That belongs in CLAUDE.md or session logs, not in either memory tier.
The five critics
Each critic runs in an isolated, fresh context (its own Agent call — never a conversation fork) — they don't see each other's verdicts or the user's draft. Each casts one YES/NO vote per candidate entry with a one-sentence rationale.
1. Generality critic
"Would a non-econ forker benefit from this
[LEARN]entry — a biology PhD, a sociology postdoc, a CS instructor? If the lesson is specific to your setup (your bibliography path, your machine's TeX install, your discipline's notation), vote NO."
2. Staleness critic
"Does this entry contradict the current state of the codebase? Run
grep -ron the file paths, function names, or settings the entry references. If the referenced thing has been renamed, removed, or significantly changed, vote NO — the entry is stale and would mislead a future session."
3. Redundancy critic
"Is this lesson already encoded in MEMORY.md, CLAUDE.md, or an existing rule? Read the relevant files. If yes (even paraphrased), vote NO — duplication erodes the index's signal."
4. Evidence critic
"Does the entry cite the incident, file path, or specific case that motivated it? If the entry is
[LEARN:foo] always do Xwith no anchor to why, vote NO. Future Claude can't judge edge cases without the rationale."
5. Format critic
"Does the entry fit the format of the tier it lands in? MEMORY.md entries are
[LEARN:category] wrong → right(seeMEMORY.mditself); a feedback/project candidate coming from native auto memory should carry the**Why:**+**How to apply:**lines auto memory writes, so the reason survives the move. If it's just a free-form note, vote NO — fix the format first, then re-submit."
Council verdict
Each critic returns YES/NO + rationale. The promotion threshold is majority (3+ YES).
- 5 YES — promote without modification.
- 4 YES — promote with a one-line note about the dissenting concern.
- 3 YES — promote but address the dissenting critics' concerns first (typically: trim, add evidence, fix format).
- 2 or fewer YES — do not promote. Either fix the entry per the dissenting critics' feedback and re-submit, or leave it in auto memory.
Steps
Step 1: Read candidate entries
If $ARGUMENTS is all, read every topic file in ~/.claude/projects/<project>/memory/ (skip the MEMORY.md there: it is only an index pointing at the topic files); each topic file is one candidate. Otherwise treat $ARGUMENTS as a substring filter on a topic file's filename, description, or type (e.g., latex matches feedback_latex_texinputs.md, and feedback matches every feedback memory). Auto memory does not store entries in [LEARN:category] form; a candidate is rewritten into that shape only for the proposal in Step 4.
Step 2: Spawn the council
Five Agent invocations in parallel, one per critic, each in a fresh context:
- Generality critic — context: the candidate entry + a one-paragraph description of who the template's audience is (academic researchers across disciplines).
- Staleness critic — context: the candidate entry + the ability to
Read/Grepthe codebase. Should explicitly check any file paths / function names / settings the entry references. - Redundancy critic — context: the candidate entry + the current
MEMORY.md+CLAUDE.md+ relevant rule files. - Evidence critic — context: the candidate entry only. Vote based on whether the entry self-describes its motivation.
- Format critic — context: the candidate entry +
.claude/rules/meta-governance.mdfor the schema reference.
Use the Haiku tier for all five critics (per .claude/rules/model-routing.md: mechanical-ish review work). The user can override via the agent's model: field if they want Sonnet for the harder calls.
Step 3: Aggregate votes
Collect verdicts. For each candidate entry, compute the vote count + per-critic verdicts.
Step 4: Present the verdicts
For each entry:
## `[LEARN:foo] <summary>`
**Vote:** 4-of-5 YES (promote with note)
| Critic | Vote | Rationale |
|---|:---:|---|
| Generality | YES | ... |
| Staleness | YES | ... |
| Redundancy | YES | ... |
| Evidence | NO | Entry doesn't cite the originating incident. Add a one-line "Incident:" pointer before promoting. |
| Format | YES | ... |
**Recommendation:** Address Evidence critic, then promote.
**Proposed MEMORY.md addition:**
```text
[LEARN:foo] <full proposed text>
**Near the cap, adding means removing.** MEMORY.md is capped at 200 lines **and** 25KB, and the byte cap usually binds first. When the file plus the proposed additions would pass ~190 lines or ~24KB (`wc -c MEMORY.md`), the report also names the **weakest current entry** as a demotion candidate — stale (a named file, flag, or model that no longer exists), contradicted by a newer rule, or local rather than generic — with the evidence, and asks the user whether to move it to auto memory or delete it. The test for keeping an entry: *would removing it cause a mistake on many tasks?*
### Step 5: User approves the promotions
The user reviews the report and explicitly approves which entries to promote. The skill writes approved entries to MEMORY.md, marks the same entries in their auto-memory topic files with `# promoted YYYY-MM-DD` for audit, and surfaces a summary.
Do **not** auto-promote — even on 5-of-5 YES votes. The user's approval is the final gate.
## Output
- Per-entry council report (verdicts, rationales, recommendations) — to the conversation.
- On approval: MEMORY.md updated (append at appropriate `[LEARN:category]` section), the auto-memory topic file updated (entry marked promoted).
- A `quality_reports/memory_promotion_<date>.md` audit file recording the full council session for forensics.
## Anti-patterns
- **Auto-promoting on 5-of-5 YES.** Even unanimous critic agreement can be wrong; the user's domain judgment is the final gate.
- **Re-running the council on the same entry repeatedly** hoping for a different result. If 4 critics consistently say NO, the entry doesn't belong in MEMORY.md — leave it in auto memory and stop.
- **Skipping the Evidence critic** because the entry "looks obvious." Evidence is what makes the entry portable across forkers; obvious-to-you ≠ obvious-to-them.
- **Demoting via this skill.** It only promotes. Demotion is a manual edit + commit.
## Cross-references
- [`.claude/rules/meta-governance.md`](../../rules/meta-governance.md) — the two-tier memory contract this skill operationalizes.
- [`.claude/agents/promote-memory-council.md`](../../agents/promote-memory-council.md) — the five-critic implementation (one agent file with five role specs, dispatched in parallel via the `Agent` tool).
- [`.claude/rules/model-routing.md`](../../rules/model-routing.md) — why critics default to Haiku tier.
- `/learn` (existing skill) — captures new `[LEARN]` entries; pairs with `/promote-memory` (which decides what graduates).
## Source of candidates (v2.5)
Candidates come from **native auto memory** — `~/.claude/projects/<project>/memory/`. Claude
writes these itself as it works, typed `user` / `feedback` / `project` / `reference`, and the
`MEMORY.md` there is an index, not the content.
The promotion question is unchanged and is the whole point: *would a researcher in a different
field, forking this template, be better off knowing this?* If yes it belongs in the committed
`MEMORY.md`; if it is about this machine, this dataset, or this person's preferences, it stays
local.
**Retired:** `.claude/state/personal-memory.md`. The two-tier idea was right; Claude Code now
ships the local tier natively, so the hand-rolled file is redundant. An existing one still
reads as a plain file, but nothing writes to it.
## The capture gate — before anything is remembered
Promotion decides what becomes *shared* knowledge. This gate decides what is worth recording
**at all**. Five questions; a candidate must pass all five:
1. **Durable** — will this still be true in six months, or is it about today's branch?
2. **Non-obvious** — would a competent person rediscover it in five minutes anyway?
3. **Stable** — does it describe a rule, or a symptom that a fix will erase?
4. **Specific** — is it actionable, or is it a mood? *"Be careful with merges"* is a mood.
5. **Not already captured** — does an existing entry cover it? Extend that one instead.
> **Just-in-case memories are banned.** They pollute the index and make the useful entries
> unfindable. A memory store nobody trusts is a memory store nobody reads.
Promotion from local observation to committed knowledge is a **reviewed act, not an autosave** —
which is why the five-critic council exists and why the user is the final gate even on a
unanimous vote.
Related Skills
last30days-skill
68.0kAI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
