[FEATURE] Add memory-compaction-proof ~/.claude/INVARIANT.md

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

After months of daily Claude Code use, I've accumulated precise directives in
~/.claude/CLAUDE.md — coding style rules, security constraints, personal workflow
requirements. I expect these to hold unconditionally across every session and project.
They don't.

CLAUDE.md is injected into the conversation context at session start, where it competes
for space with tool outputs, file contents, and conversation history. When compaction
triggers, it gets summarized alongside everything else. Directives get paraphrased,
weakened, or lost entirely. The longer the session, the less reliable the rules become —
exactly backwards from what a rules file should do.

The result: I correct Claude on something, it acknowledges the rule, works correctly for
a while, then gradually reverts after one or two compactions. There is no way to tell
Claude "this directive is non-negotiable and must never be compressed."

Proposed Solution

Recognize ~/.claude/INVARIANT.md (name negotiable) as a special file injected at the
true system prompt level — not into conversation context — and explicitly excluded from
the compaction process.

Behavior contract:

• Loaded at session start into the system prompt, not the message history
• Never included in compaction input — the compaction process does not touch it
• Always present at full fidelity, regardless of session length or compaction count
• Survives /compact, auto-compact, and session resume
• Global scope only (like ~/.claude/CLAUDE.md) — no per-project equivalent needed

Intended separation of concerns:

| File | Purpose | Compressible? |
|---------------------------|-----------------------------------------------|------------------------|
| ~/.claude/INVARIANT.md | Hard user rules — style, constraints | Never |
| ~/.claude/CLAUDE.md | Global preferences, context, notes | Yes (current behavior) |
| ./CLAUDE.md | Project-specific context and conventions | Yes (current behavior) |

Alternative Solutions

--append-system-prompt — the intended solution, but per #4523 it injects a user
message, not a true system prompt addendum. It is subject to the same compaction
process. Even if fixed, it requires being passed on every invocation — not viable for
interactive use.

Shell alias workaround:

alias cc='claude --append-system-prompt "$(cat ~/.claude/invariant-rules.md)"'

Fragile: must be configured per machine, breaks in subshells, invisible to tools that
invoke claude directly, and still broken at the API level per #4523.

Keeping CLAUDE.md short and specific — reduces compaction damage but doesn't prevent
it. Rules still degrade over long sessions. Mitigation, not a solution.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

I have a rule: "Never use var in JavaScript. Always const or let." I put this
in ~/.claude/CLAUDE.md.

1. Session starts — Claude reads the rule, follows it correctly.
2. Two hours in, context approaches limit. Auto-compact fires.
3. Compaction summarizes everything including my rules. The rule survives as something

like "prefers modern JS syntax."

1. Claude writes var x = 5. I correct it. It apologizes and fixes it.
2. Another compaction. The correction is also summarized away.
3. Back to var. I've now corrected the same thing three times in one session.

With INVARIANT.md: the rule lives at the system prompt level, never enters the
compaction input, and is followed on turn 1 and turn 1,000 identically.

Additional Context

Related issues:

• #4523 — --append-system-prompt injects a user message, not a true system prompt

addendum (the intended workaround is broken)

• #29760 — Two-Tier Context Architecture (closed as duplicate; covers agent-curated

in-session knowledge — this request is about user-authored cross-session rules,
a distinct scope)

• #10643 — Request for ~/.claude/append-to-system-prompt.txt (open, no resolution)
• #6153 — Request for --append-system-prompt-file <path> (stale)
• #3021 — Claude forgets rules after compaction (bug report confirming the problem)

Implementation surface is narrow: exclude one known file path from the compaction
input and inject its contents at the system prompt level at session start. No changes
to existing CLAUDE.md behavior required.

Not a duplicate of #29760. That proposal asks the agent to auto-promote things it
discovers during a session. This is about user-owned directives that predate any
session and must never be touched by any automated process. Complementary, not
overlapping.