[FEATURE] Session-scoped compaction-resistant context (`/pin`)

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

When a user gives an in-session instruction — e.g. "don't use this library in this session" — it lives only in conversation history. After /compact, it disappears silently. There is no way to mark a conversation turn as compaction-resistant without writing it to CLAUDE.md (which is permanent and global).

This creates a gap between short-term volatile memory (conversation) and permanent instructions (CLAUDE.md). Human working memory naturally maintains a "pinned" layer of session-critical context. Claude has no equivalent.

| Layer | Retention | Problem |
|-------|-----------|---------|
| Conversation history | Lost on /compact | Volatile — key instructions vanish silently |
| CLAUDE.md | Permanent, global | Too heavy for session-specific instructions |
| .claude/rules/ | Permanent, re-injected every turn | Not user-controllable mid-session |
| PIN Memory (proposed) | Session-scoped, compaction-resistant | Fills the gap |

Problem Landscape

This problem surfaces across many existing issues. The following classifies them by whether this proposal addresses them:

Directly addressed by this proposal

| Issue | Title | How this proposal helps |
|-------|-------|------------------------|
| #32874 | Pin/bookmark messages within a conversation | This proposal provides the compaction-survival mechanism that #32874 describes as "ideally". The /pin, /pinned, /unpin commands cover the same UX surface. |
| #9796 | Context compaction erases project-context instructions | User-controllable pinning prevents critical instructions from being lost during compaction. |
| #33212 | Compact prompt should preserve historical context across multiple compactions | Pinned entries survive all compactions by design — re-injected after, not into, the summary. |

Partially addressed (overlapping scope)

| Issue | Title | Relationship |
|-------|-------|-------------|
| #43592 | Session-scoped working memory tool (MemoryWrite/MemoryRead) | Architecturally more ambitious (model-triggered, typed entries, key-value upsert). This proposal is a simpler user-triggered subset that could coexist or serve as a stepping stone. |
| #14258 | PostCompact Hook Event and Compaction Content Control | Option C ("Framework Pinning") overlaps. This proposal provides the user-facing UX that hooks alone cannot. |
| #34556 | Persistent Memory Across Context Compactions | Field report from a user who built a 3-tier external memory system. Validates the problem; this proposal addresses the session-scoped tier. |

Related but not addressed (different problem)

| Issue | Title | Why separate |
|-------|-------|-------------|
| #44166 | Option to exempt CLAUDE.md / auto-memory from compaction | About permanent files, not session-scoped context. But reveals that .claude/rules/ is already compaction-exempt — key implementation insight. |
| #39852 | Re-inject CLAUDE.md after context compaction | About CLAUDE.md fidelity, not user-controlled session memory. |
| #41279 | Compaction-protected Rulebook | File-based permanent rules, not session-scoped user instructions. |
| #34716 | Compaction-proof INVARIANT.md | Global scope, not session scope. |

Proposed Solution

Three commands that let users explicitly mark content as compaction-resistant:

/pin            → Pin the previous turn (compaction-resistant for this session)
/pinned         → List all current pinned entries
/unpin <id>     → Remove a specific pinned entry

Behavior:

• Pinned entries survive /compact — re-injected into context after compaction, not into the summary
• Session-scoped — cleared on session end, never written to CLAUDE.md or files
• User-controlled — only the user pins and unpins

Example output of /pinned:

📌 Pinned (3 entries)
──────────────────────────────────
#1 "Do not use this library"
#2 "Focus on Go implementation only"
#3 "User prefers minimal comments in code"
──────────────────────────────────
/unpin <id> to remove

Compression rules:

When pinned content is stored, compression must preserve meaning, not just shorten text.

✅ Remove filler / emotional modifiers
✅ Neutralize tone while preserving intent
❌ Do not change conditions or scope
❌ Do not invert or weaken negation
❌ Do not omit the subject or target

Example:
  Original : "This library is ancient garbage, don't use it"
  Pinned   : "Do not use this library"              ✅
  Bad      : "Avoid bad libraries"  ← subject lost  ❌

Roadmap

Phase 1 — Explicit /pin command (MVP)

The core feature. Users manually pin turns, pinned entries are re-injected after compaction. This alone solves the primary problem.

Phase 2 — Auto-pin with confidence layering and eviction

Claude detects high-salience instructions mid-conversation and suggests pinning, with user notification and confirmation:

📌 AUTO-PINNED: "Do not use this library"
[view original] · [promote to /pin] · [dismiss]

Once auto-pin is introduced, two related concerns arise naturally:

• Confidence layering: User-pinned entries are preserved verbatim (highest fidelity). Auto-pinned entries may be meaning-preserving summaries with varying confidence. User-pinned content always takes priority. The exact number of levels and retention characteristics would be implementation details.
• Eviction policy: When pinned entry count grows large, lower-confidence entries are evicted first. User-pinned entries are never auto-evicted. A soft warning may appear when entry count exceeds a threshold.

Implementation Note

Per #44166, .claude/rules/ files are already exempt from compaction and re-injected every turn. This confirms that compaction-exemption infrastructure already exists. /pin could leverage a similar mechanism — store pinned entries in a transient in-memory store that is re-injected after compaction, without requiring new compaction logic.

References

• #43592 — Most detailed existing proposal for session-scoped memory. Provides the architectural thinking (inject after compact, not into compact) that this proposal builds on.
• #44166 — Reveals .claude/rules/ compaction exemption as existing infrastructure.
• #34556 — Field report from a user who built a 3-tier external memory system over 59 compactions. Validates the severity of the problem.
• #32874 — Original /pin command proposal with UI/bookmark focus.

Feature Category

CLI commands and flags