Feature: On-demand file loading into Memory context mid-session

Problem

Currently, files can only enter the Memory context (which survives compaction/compression) through two mechanisms:

1. @-imports in CLAUDE.md — resolved at session start
2. Path-triggered rules (.claude/rules/*.md) — auto-injected when touching matching files

There is no way for a user to manually promote an arbitrary file into Memory mid-session. If you read a file normally, it enters the Messages context and will be compressed away when the conversation grows long enough to trigger auto-compaction.

Why this matters

In large monorepos or multi-app projects, not all context is relevant at session start. Teams often have:

• Architecture decision records (ADRs)
• API specifications or protocol docs
• Migration guides, runbooks, or domain-specific references
• Shared convention files that apply to some tasks but not others

Pre-loading everything via @-imports wastes context tokens. Path-triggered rules only work for files tied to specific directory patterns. There's a gap for task-specific reference files that a developer knows they'll need throughout a session but can't predict at configuration time.

Current workaround

The closest workaround is writing a CLAUDE.local.md file mid-session with an @-import pointing to the desired file, then triggering a file read to load it as a system reminder. The content loads immediately as a system reminder (in Messages), and only promotes to Memory after compaction re-reads CLAUDE.md from disk. This is fragile, indirect, and not discoverable.

Proposed Solution

Introduce a built-in command (e.g., /load <path>) that promotes a file into the Memory section for the remainder of the session.

Behavior

• /load path/to/file.md — loads the file's content into Memory context immediately
• The file persists through compaction (re-read from disk, same as @-imported files)
• /unload path/to/file.md — removes the file from Memory context
• /context reflects loaded files under the Memory section

Example usage

> /load docs/api-v2-migration.md
✓ Loaded docs/api-v2-migration.md into Memory (1.2k tokens)

> /load shared/protocols/scoring.md
✓ Loaded shared/protocols/scoring.md into Memory (800 tokens)

> /context
Memory files
├── CLAUDE.md: 500 tokens
├── docs/api-v2-migration.md: 1.2k tokens  (loaded via /load)
└── shared/protocols/scoring.md: 800 tokens (loaded via /load)

Design considerations

• Token budget awareness: Show token count on load, warn if Memory section is getting large
• Session-scoped by default: Loaded files don't persist across sessions (that's what @-imports in CLAUDE.md are for)
• Glob support (nice-to-have): /load docs/api-*.md to load multiple related files
• Idempotent: Loading an already-loaded file is a no-op (or refreshes from disk)

Alternatives Considered

| Approach | Limitation |
|----------|-----------|
| @-imports in CLAUDE.md | Must be configured before session start; loading everything wastes tokens |
| Path-triggered rules | Only works for directory-pattern-based loading, not arbitrary files |
| Writing CLAUDE.local.md mid-session | Fragile workaround; content only enters Memory after compaction |
| Just reading the file | Enters Messages context, gets compressed away |

Use Cases

1. Monorepo task switching: Developer starts working on API, then pivots to mobile — loads mobile architecture doc without restarting session
2. Reference-heavy tasks: Loading a database schema, API spec, or protocol doc that will be referenced repeatedly throughout a complex task
3. Onboarding/pairing: Loading team conventions or style guides for a specific subsystem on demand
4. Debugging sessions: Loading relevant log formats, error catalogs, or infrastructure docs mid-investigation

Related Issues

• #27298 — Layered memory system (automatic on-demand loading based on relevance)
• #17428 — Enhanced /compact with file-backed summaries
• #6972 — On-demand loading of subdirectory CLAUDE.md files
• #5171 — Scoped context during sessions