Description

When a user saves a feedback/preference memory like "After every wrap-up, paperwork updates must be pushed to main", that memory is loaded in every session's auto-memory context. The user reasonably believes the rule will be enforced.

It is not. Memory is advisory. The model may acknowledge the rule, may even cite it, and still proceed to violate it under perceived time pressure or workflow friction.

In a real RISM project case, this exact rule was active for 13 consecutive sessions and failed all 13 times. Each session's bootstrap pointed at the same paperwork branch, paperwork accumulated, and the rule was never enforced. Net effect: 13 sessions of drift before the user noticed.

Expected behavior

Claude Code's documentation should clearly distinguish three categories of user rules:

1. Preference memories (use auto-memory): "I prefer concise responses," "I write Swift not Python," "default to Sonnet for paperwork."
2. Project context memories (use auto-memory or CLAUDE.md): facts about the user, project conventions, file paths.
3. Workflow enforcement rules (use hooks or skill-level gates, NOT memory): "always do X at boundary Y," "never edit Z files directly," "wrap-up cannot complete until W."

For category #3, the docs should explicitly recommend hooks (PreToolUse, PostToolUse, SessionEnd) or skill-level mandatory steps that exit non-zero on violation. The update-config skill should detect when a user is saving a category-3-shaped rule and prompt: "this looks like a workflow enforcement rule. Memory is advisory; would you like to scaffold a hook for mechanical enforcement?"

Actual behavior

The auto-memory documentation does not draw this distinction. New users (and even experienced users) save "always do X" rules to memory expecting enforcement. They don't get it.

Real-world example

User saved memory: "After updates, all project documents must be pushed to main." Saved at Session 76. Active for Sessions 77-88 (13 sessions) without enforcement. Each session, the memory was loaded, Claude acknowledged it, then a wrap-up landed paperwork on a side branch without pushing to main.

Fix required: the user had to build a paperwork-on-main-check.sh script + add Step 6b mandatory gate to /kk-wrap-up skill + add Step 0 gate to /kk-coding skill. Memory was never the right enforcement layer.

Reproduction steps

1. Save a feedback memory: "At every wrap-up, run the linter before commit."
2. Run a session that ends with /kk-wrap-up (or any wrap-up flow).
3. Observe: Claude may or may not run the linter. Memory does not enforce.
4. Compare to a PreToolUse hook on Bash matching git commit that runs the linter — that DOES enforce.

Environment

• Claude Code CLI all versions
• Auto-memory feature

Severity

Medium. Not a correctness bug — memory works as designed (advisory). But the design is undocumented in a way that erodes user trust. Users save rules expecting enforcement and feel betrayed when they're violated.

Suggested fix scope

Documentation-only:

1. Add a new docs page: "Memory vs Hooks vs Skills — when to use each."
2. Cross-link from update-config docs and auto-memory docs.
3. Optional: detect category-3-shaped memory writes (regex on "always|never|every time|at <event>|before <action>") and surface a soft prompt: "this looks like a workflow rule. For mechanical enforcement, consider a hook."

Suggested example to include in docs

# Wrong: this won't enforce
# (saved as feedback memory)
"At every wrap-up, paperwork must be merged to main same-session."

# Right: this enforces
# (saved as ~/.claude/scripts/paperwork-on-main-check.sh + skill mandatory step)
[script that exits 1 if drift detected; called from /kk-wrap-up final step]

Real-world severity evidence

The user lost ~30-60 minutes catching up on 13 sessions of drifted state. Memory had been doing nothing for that entire period. The cost of NOT having clarity in the docs is paid in user time and trust.