English · 简体中文
A "project mental model" skill for Claude Code: lets every new session pick up this project's full context in the first second — no re-stepping on old landmines.
AI agents have a chronic problem: every new session starts amnesiac — the pitfall you corrected last time, the architecture decision you settled on, a component's non-obvious constraint, all gone, and you re-explain from scratch. PMM fixes exactly this.
The core principle is one sentence: only record what reading the code can't give you. Anything derivable from code, comments, global rules, or model common sense is not recorded — so the memory store never piles up into noise.
What lets a new session "pick up the context" is these three, split by where it belongs and how long it lives:
| Artifact | Location | Role |
|---|---|---|
| ① Constitution | project CLAUDE.md (resident, ≤150 lines) |
dev paradigm / cross-platform constraints / one-line business thread / pitfall pointers |
| ② Cognition | auto-memory | non-derivable stable invariants (device / protocol / architecture / SDK behavior) |
| ③ Volatile state | current-state.md |
in-flight phase / temporary workarounds / known pitfalls / tech debt / blockers |
- Will it recur? — only a stable invariant root-cause recurs. One-off problems aren't stored.
- Can it be derived (cold test)? — imagine a fresh AI that can only read this repo. Could it figure this out on its own? If yes, don't store it.
In practice ~3 of 40 candidates pass. When in doubt, don't store.
PMM ships a global UserPromptSubmit hook: whenever your message contains a decision / correction / new constraint, the AI does a cheap first pass on the spot — you don't have to say "remember this."
But the working AI does not get to write memory itself — it's biased (just-discovered-it-so-it-feels-precious + survivorship bias), and self-writing is the root of garbage piling up. Every plausible candidate is handed to an independent reviewer memory-gatekeeper (a subagent shipped with this package): it did not do the work, knows only the strict bar, defaults to REJECT, and independently rules reject / update-existing / add — only a pass gets written, silently. Taking "write or not" out of the biased party's hands is the structural defense against noise entering the store.
Why pin it to "the moment you send a message": survivorship bias — if the AI did great you just leave and there's no next message; your sending a message (especially a correction) is the highest-value signal.
cp -r project-mental-model ~/.claude/skills/project-mental-model
bash ~/.claude/skills/project-mental-model/templates/bootstrap-verify.sh --install--install idempotently sets up the chains (command alias / auto-memory skeleton / freshness & autonomous-capture hooks / memory-gatekeeper reviewer agent / CLAUDE.md entry pointer) and re-verifies. Reopen a session once so the /pmm alias registers.
| Command | Action |
|---|---|
/pmm |
create / incrementally refresh the project mental model |
/pmm log |
capture what this session is worth recording, now |
/pmm check |
health-check the four chains + orphan-memory reconciliation + anchor reconciliation |
/pmm --rebuild |
rebuild from scratch (lists files to overwrite first) |
When you need a module map / call graph / impact set, read the code on the spot or use the vendored (zero-install) codegraph:
python3 tools/codegraph/cli.py map|where|callers|deps|impact <file>...- CLAUDE.md stays ≤150 resident lines; only what can't be derived from code / lockfile / git; reference code by "file + symbol name" anchors, not drifting line numbers.
- Don't maintain derivable structure maps.
- Incremental over full rebuild, new overrides old (recency-wins); no running logs.
- Self-contained & portable: copy the whole directory + run
--installonce and it works on a new machine; no hard-coded paths inside.