project-memory
Skill2 starsChanged 42 days agoApache-2.0View on GitHub
The one ritual - check, polish, publish, evolve, then route the next session (phase, mode, optional maturation pass). Only the user opens it, by typing /project-memory at the end of a working session or after a milestone. When the user says "update memory", "log this session", "update the log", "curate memory", "update status", "wrap up", or "run the ritual", ask them to type /project-memory. NOT for planning or resuming work (use /plan-task), and NOT for a cold "where were we" (read .claude/STATUS.md).
- Commits and pushes
26 other projects use a version of this.
Adopted by
Most recently taken up by
- roronoazoroshao369/vibe-coding-ostheir own version, first seen Nov 15, 2026
- CheehooLabs/SpureeSkillstheir own version, first seen Nov 8, 2026
- cobibean/project-memory-skilltheir own version, first seen Nov 8, 2026
- RRFRRF/project-memory-skilltheir own version, first seen Nov 8, 2026
- xuyewild/multi-ai-skillstheir own version, first seen Oct 25, 2026
- kaushikhegde11/obsidian-project-memorytheir own version, first seen Oct 20, 2026
Other versions26 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 26
- SpillwaveSolutions/project-memory★ 88same name
- CheehooLabs/SpureeSkills★ 18same name
- RRFRRF/project-memory-skill★ 8same name
- scaleto/Antigravity-Super-Skill-Architecture★ 8same name
- cobibean/project-memory-skill★ 7same name
- me-cedric/agent-compass★ 3same name
- tasuku-9/project-memory-skill★ 3same name
- jukrap/ai-agent-playbook★ 2same name
- sakuruamayday-ops/enterprise-project-application-assistant★ 2same name
- g030105021203-cell/project-memory★ 1same name
16 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository4 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- adhdSkill
- adoptSkill
- plan-taskSkill
The file
We split this skill into the rules it gives an agent
10 rules. 0 are common, 6 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 21 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 25
Run this in the MAIN session, never as a sub-agent.
- Distinctive: line 31
Every generator in this system runs here and only here.
- Distinctive: line 43
Read the output properly. It reports one line per step:
- Distinctive: line 56
If CHECK failed and you are stopping, still tell the user what you learned.
- Very specific: line 96
2e. Close finished tasks: Verify each Plan item's done-evidence rather than assuming it, fill Outcome, flip the status line, archive to …
- Very specific: line 152
Never --force, never --no-verify, never push when CHECK failed.
- Distinctive: line 220
4f. Reconcile the map: if any component changed this session (git status --short tells you).
- Very specific: line 240
When a milestone is in flight, end the block with python3 .claude/tools/statectl.py progress, pasted as is.
- Very specific: line 268
2. Mode for the next session: Keep the current mode, or switch with python3 .claude/tools/statectl.py mode …
- Distinctive: line 279
3. Maturation pass now?: Default no. It suits a session whose goal is improving the system itself, not a side effect of shipping project …
“Common” is measured: kept by at least 6 in 10 of the 21 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/project-memory
Five phases, in order: CHECK, POLISH, PUBLISH, EVOLVE, then the report, then ROUTE.
This skill runs only because the user typed /project-memory. checkctl enforces it: the
prompt hook (.claude/hooks/ritual-ticket.sh) writes a ticket, .claude/state/ritual-ticket.json,
when the user's own prompt starts with /project-memory (or /adopt); checkctl run refuses
to open or continue a run without a fresh one, and checkctl complete needs it and consumes
it. The policy gate denies the file to every agent identity. The ticket is a tripwire, not
cryptography: it makes an agent-opened ritual fail loudly and leaves the issue in the record;
it does not make forging impossible, and it does not have to. If checkctl refuses for want of
a ticket, stop and ask the user to type /project-memory. Never work around it. If the prompt
hook never fires (an older Claude Code, hooks not trusted yet), the USER runs
python3 .claude/tools/checkctl.py ticket --grant in their own terminal (a ticket marked
event: "human-terminal"), then types /project-memory; the gate refuses that subcommand to
every agent, you included, so never try it yourself.
Run this in the MAIN session, never as a sub-agent. You are the only agent who saw the whole conversation, and curation is exactly the part that cannot be reconstructed from disk.
EVOLVE runs in the soft gear every time: evolve incrementally as part of wrapping up. The deeper maturation pass is a choice the user makes at ROUTE, described there.
Every generator in this system runs here and only here. That is not a stylistic preference: in the system this one was distilled from, the single regenerator nobody wired into the ritual sat frozen for two and a half months while every downstream surface quietly served stale data.
Phase 1 - CHECK
python3 .claude/tools/checkctl.py run --phase checkRead the output properly. It reports one line per step:
- FAIL stops the ritual. Fix what is fixable, then rerun. If it cannot be fixed now, say so
plainly and stop before PUBLISH: reporting a clean wrap-up over a failed check is the exact
false "done" that
.claude/protocols/honesty.mdforbids. - WARN informs. A stale generator at CHECK time is normal (POLISH is about to rebuild it). An empty price table, an unregistered tunable, a checkpoint that disagrees with disk: mention them in the final report.
Then verify the things a script cannot: for each active task in .claude/tasks/, does the
Checkpoint still describe reality? A checkpoint is a claim, not a fact. Where they disagree,
reality wins: correct the checkpoint first.
If CHECK failed and you are stopping, still tell the user what you learned. A failed ritual that reports honestly is worth more than a green one that skipped a step.
Phase 2 - POLISH
Curation first (this is you, not a script), then the generators (a script, all of them).
2a. Reconstruct the session. Decisions and their reasons, deliverables, analyses, mistakes on both sides, open questions, next steps. Favor signal; omit asides.
2b. Append to .claude/Project-log.jsonl - one condensed entry per real thing:
{"date":"YYYY-MM-DD","type":"decision|deliverable|milestone|analysis|note|mistake|tooling",
"title":"grep-skimmable","summary":"1-2 sentences: what and why",
"artifacts":["relative/path"],"tags":["..."],"source":"session|artifacts|git"}source is an epistemic tag, not decoration: session means you witnessed it, artifacts or
git means you inferred it from files afterwards. Append only; never edit or reorder past
lines. No volatile numbers, point at the source data instead.
2c. Curate .claude/LESSONS.jsonl. One row per real mistake, where real means it cost
something (rework, a wrong output, lost time, a misleading report):
{"id":"L-<n>","date":"YYYY-MM-DD","who":"agent|developer|both","what":"...",
"root_cause":"...","prevention":"mechanical and checkable","active":true}The prevention rule must be something a future session can execute ("run X before Y", "grep for
Z first"). "Be more careful" prevents nothing. Rotate active: keep one to three rows active,
retire what has been internalized. Active rows are what the console's WORK tab shows.
2d. Rewrite .claude/STATUS.md from scratch, not patched. Five sections, 15 to 25 lines
total: Current focus, Active tasks, Next steps (concrete enough to start from cold), Blockers
and open decisions, Watch-outs (mirrored from the active lessons).
2e. Close finished tasks. Verify each Plan item's done-evidence rather than assuming it,
fill Outcome, flip the status line, archive to .claude/tasks/archive/YYYYMMDD/. Surface any
unanswered ## NEEDS-HUMAN row to the user NOW, and make sure it exists in the queue:
python3 .claude/tools/statectl.py need open --title "..." --category decide --band SEV1 \
--context "<what is going on, why it matters, what it blocks - written for a human reading cold>" \
--action "<the one concrete thing to do>"2f. Set the resume pointer for whatever comes next:
python3 .claude/tools/statectl.py pointer "<the very next concrete action>"2g. Run every generator:
python3 .claude/tools/checkctl.py run --phase polishThis rebuilds the cards, the map, the story feed and the console, and stamps each generator's
content hash into .claude/state/generators.json. A generator that is skipped here is a
generator that will rot.
2h. Update .claude/CLAUDE.md only if locations or conventions changed this session. It is
a map, not a dump.
Phase 3 - PUBLISH
python3 .claude/tools/checkctl.py run --phase publishThis refuses to run unless POLISH completed in the SAME run id, so a half-built set of derived surfaces can never be committed as if it were whole. If it refuses, rerun POLISH; do not work around it.
It ingests token metadata from the transcripts, seals the raw record through the allowlist, writes the daily rollup and updates the anchor. Nothing verbatim crosses into the repo.
Then git. Stage, and commit with a conventional message:
git add -A && git commit -m "<type>: <what changed>"Push per push in .claude/config/memory.json:
ask(the default): ask once, with AskUserQuestion, naming the branch and remote.always: push without asking. Invoking the ritual is the standing instruction.never: commit only.
Never --force, never --no-verify, never push when CHECK failed.
Cutting a release - home repo only, and only when the maintainer names a version. Releases are the maintainer's call, never yours. When they say "release vX.Y.Z":
- Set
system_versiontoX.Y.Zin.claude/config/registry.json- the tag and the stamp move in step. Setversion:anddate-released:inCITATION.cff(repo root) to the same value and the release date;changelog_parityFAILS when the citation lags the stamp. - Pin the changelog: in
CHANGELOG.md(repo root), retitle## Unreleasedto## vX.Y.Z - YYYY-MM-DDand curate it fromProject-log.jsonlsince the previous tag - written for readers of the release, not a commit dump - then start a fresh## Unreleasedabove it. Thechangelog_paritycheck FAILS the ritual if any version tag or the stampedsystem_versionlacks its section, so a release cannot quietly outrun its changelog. - The zip step, on the release commit itself:
python3 .claude/tools/distctl.py build, thenpython3 .claude/tools/distctl.py verifymust say fresh (.claude/reference/release-flow.md; a pre-release cut fromdevtakes the same step, since its tag makes CI strict about the zips). Commitrelease: vX.Y.Z - <one line>with the zips and taggit tag vX.Y.Z. Push per thepushknob; if this session's credentials cannot push tags (branch-scoped tokens cannot), hand the maintainer the exact commands and say so in the report. Do not create the GitHub release by hand. Pushing the tag fires
.github/workflows/release.yml, which is the ONE publisher: it runs the suite on every supported OS, rebuilds both zips with the same registered generator the ritual uses, and publishes with this version's CHANGELOG section as the notes. Runninggh release createyourself races it and leaves a red run behind ("a release with the same tag name already exists") - that is exactly what happened on v0.2.2. Instead, watch it land:gh run watch $(gh run list --workflow=release --limit 1 --json databaseId -q '.[0].databaseId')Report the run's verdict. If the suite fails there, the release does not exist and the tag needs a fix-forward commit and a new tag - never a force-push over a published tag.
Why adopters never see any of this: CHANGELOG.md lives at the repo ROOT deliberately - the
zips package only the tracked .claude/ tree plus files distctl authors, and the adopt skill
copies only .claude/ paths, so the system's own history structurally cannot reach an
adopting repo and there is no filter to maintain. The changelog_parity check rides the same
knob as the home-only generators (distribution.enabled, absent reads false): in an adopting
project it reports SKIP, in this repo it enforces the pin.
Phase 4 - EVOLVE
4a. Build a session digest, 15 to 30 lines: goals and outcome; instructions you needed more than once (with counts); failures and their root causes; human corrections; gates asked and their answers; friction moments; which skills and agents were used and whether they fit.
4b. Dispatch the retro-analyst (Sonnet, propose-only by tool restriction) with the digest
plus an inventory of .claude/**/*.md, telling it to read .claude/protocols/evolution.md and
apply its bar. It returns at most three proposals in the Evolution proposal format, or the
single line NO-CHANGES: <reason>.
4c. Filter. The analyst saw only a lossy digest; you saw the session. Drop proposals whose
evidence does not actually hold. Expect to drop some. NO-CHANGES is a good outcome, not a
failure to produce.
4d. Confirm - a BLOCKING gate. Present the survivors with AskUserQuestion (multi-select, one
option per proposal, plus "None of these"). Never modify .claude/ without confirmation.
4e. Implement. For anything touching components, dispatch the anatomist; it implements with the smallest primitive that holds the fix and updates the card in the same pass. Log each change:
python3 .claude/tools/statectl.py tooling --change-type <kind> --what "..." --evidence "..."4f. Reconcile the map if any component changed this session (git status --short tells
you). Dispatch the anatomist; if nothing changed, say so explicitly rather than silently
skipping.
4g. Close the ritual (it needs the ticket and consumes it, so this is the last checkctl
write of the ritual):
python3 .claude/tools/checkctl.py complete --note "<one line>"The report
One condensed block, in this order: what CHECK said (including warnings), what was logged and what changed in STATUS, generators rebuilt, what PUBLISH did (commit, and whether it pushed), retro outcome (proposals confirmed, dropped, or NO-CHANGES), map reconciled or skipped and why, and open questions for the maintainer.
When a milestone is in flight, end the block with python3 .claude/tools/statectl.py progress, pasted as is.
Report skipped and failed steps faithfully. "Done" means verified-done.
Phase 5 - ROUTE
The last step: set up the next session. Read the dials first
(python3 .claude/tools/statectl.py status prints Mode and Phase), then ask ONE
AskUserQuestion with up to three questions. Skip a question that does not apply; when none
applies, say so in one line and stop.
1. Phase for the next session. Skip it in Freestyle: that mode has no phase contract. Options: stay in the current phase, or advance to the next one (plan, build, review, deploy, then plan again for the next milestone; with no phase set, offer to start in plan). Recommend staying unless this session's work met the phase's exit. On advance, run:
python3 .claude/tools/statectl.py phase <next>It runs the current phase's exit check first. If it refuses, show the failing rows as printed,
then ask whether to fix them first or leave anyway. Offer --override "<why>" only when the
user chooses to leave anyway, and use their reason, not yours. Leaving review needs the
human's sign-off: ask for it and pass their words verbatim as --signoff "<text>". Never write
a sign-off yourself.
2. Mode for the next session. Keep the current mode, or switch with
python3 .claude/tools/statectl.py mode <freestyle|guided-solo|fableous-orchestrated>. One line
each on what it costs and what it gives:
- Freestyle: costs nothing extra; gives the record, the gates and this ritual, with no phase contract and no exit checks.
- Guided Solo: costs an exit check at every phase change and a contract printed at each session start; gives a lifecycle that cannot quietly skip a test run or a sign-off. One agent.
- Fableous Orchestrated: costs more agent calls and a validated handoff envelope per task;
gives Guided Solo plus a lead routing work to a team (
protocols/orchestration.md).
3. Maturation pass now? Default no. It suits a session whose goal is improving the system itself, not a side effect of shipping project work. When the user says yes, run it now:
- Full anatomist audit: folder health, drift review, every component's card checked against its source, unclassifiable components surfaced. Not just reconciliation.
- Pruning sweep: usage evidence from the record (
obsctl.py report --by session, journal and log greps) against every skill, agent, tool and rule. Unused machinery becomes a demotion or archival proposal. Growth and shrinkage run on the same evidence. - Proposals become task cards for a plan phase: each surviving proposal goes through the
evolution bar and the user gate, then lands as a
/plan-taskfile in.claude/tasks/(Definition of done, one Test command, registered under a milestone), so the next plan phase picks it up. Each card's Test includes itscheckctl.py probeentry, so "it is built" stays a mechanical claim. - A decision list for the maintainer: every judgment call the audit could not make alone, with a recommendation.
Card and map changes the pass makes are rebuilt by the next ritual, which the user opens by
typing /project-memory again: this one is already complete.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

