pin-memory

Mode

• With arguments (/PACT:pin-memory <content>): Pin the specified content.
• Without arguments (/PACT:pin-memory): Review the session for pin-worthy context and pin what matters.

Caps (enforced mechanically)

Cap violations are denied by hooks/pin_caps_gate.py when the Edit/Write tool call lands. You do NOT need to invoke a CLI check before adding — the hook is authoritative.

• Count: 12 pins maximum.
• Size: 1500 characters per pin body (excludes <!-- pinned: ... --> and <!-- STALE: ... --> auto-markers).
• Override: verbatim load-bearing content MAY carry a pin-size-override rationale (≤ 120 chars, single line) — see Size Override. The hook validates the rationale in-band.

When to Pin

• Critical gotchas that would waste hours if forgotten
• Key architectural decisions that explain "why" (not "what")
• Build/deploy commands needed every session
• Non-obvious patterns unique to this codebase

When NOT to Pin

• Routine session context (auto-memory and pact-memory handle this)
• Things easily found in code or docs
• Temporary information that will become stale

Process

Target file: The project CLAUDE.md may be at either $CLAUDE_PROJECT_DIR/.claude/CLAUDE.md (preferred) or $CLAUDE_PROJECT_DIR/CLAUDE.md (legacy). Use .claude/CLAUDE.md if it exists, otherwise ./CLAUDE.md. If neither exists, create at .claude/CLAUDE.md.

Adding a pin

1. Read existing CLAUDE.md.
2. Locate or create a ## Pinned Context section (place it before ## Working Memory).
3. If the file carries a <!-- PACT_MEMORY_PINNED_END --> line, the new entry MUST go ABOVE that line. The pinned region ends there. A pin placed below it sits outside the region, so the count and size caps do not measure it and the hook cannot deny it — the pin is silently uncapped. Insert immediately before that line, after the last existing entry. If the file has no such line, append at the end of the section as usual.
4. Add the new entry with a date tag. Make this write with the Edit tool. Do NOT use the Write tool. Step 1 gave you the full file, so a Write call looks like the short route to the new content. After a Write, a file that had CRLF line endings has LF line endings. The curator then sees a change to a file they did not edit. An Edit keeps the line endings of the file. Use the example below:

   <!-- pinned: YYYY-MM-DD -->
   ### Entry Title
   Content here (~5-10 lines max)
   

5. Commit — then confirm CLAUDE.md is actually in the resulting commit. Where a project git-ignores CLAUDE.md (a bare CLAUDE.md line in .gitignore matches at any depth), the failure is loud in the obvious cases and silent in the one that matters. An explicit git add CLAUDE.md errors, and a commit whose only change is CLAUDE.md reports "nothing to commit" — both non-zero, both visible. But a blanket git commit -a / -am that also picks up other changed files succeeds, exits 0, and simply omits CLAUDE.md. Checking the commit's exit status instead of its contents is what turns that into a pin reported as durable while it has no git backing at all. So verify the file is in the commit, not that the commit succeeded. If it is not, report the pin as applied to the working file but not version-controlled, so the curator knows it lives only on this machine. NEVER use git add -f to force it past the ignore rule — the rule is the project's decision, not an obstacle.