Feature Request: Periodic Directive Refresh Mechanism for Long Sessions

GitHub Issue Draft: Agents Cannot Reliably Follow Persistent/Layered Directives

Repository: anthropics/claude-code
Type: Enhancement Request
Priority: High - Affects long-session reliability

---

Title

Feature Request: Periodic Directive Refresh Mechanism for Long Sessions

---

Problem Statement

AI agents read project directives (CLAUDE.md, etc.) at session start but progressively "forget" to follow them as sessions progress. This "directive drift" causes:

1. Context monitoring failures - Instructions like "check context every 10 tool calls" are followed initially, then forgotten
2. Protocol violations - Approved/denied operations become blurred
3. Behavioral drift - Agents add unnecessary complexity, skip required steps
4. Session data loss - Critical checkpoints missed because context thresholds weren't monitored

Reproduction Steps

1. Create a CLAUDE.md with explicit ongoing instructions:

```markdown
## Context Monitoring (CRITICAL)

• Check context status every 10 tool calls
• Warn user at 65% context
• Auto-checkpoint at 75% context

```

1. Start a Claude Code session and read CLAUDE.md

1. Observe that:

• First 20-30 tool calls: Agent follows instructions
• Tool calls 30-60: Compliance degrades
• Tool calls 60+: Instructions effectively forgotten

1. Session hits context compaction (~85%) without warning because agent stopped checking

Evidence

From real-world usage (CxMS project, 23+ sessions):

• Directive fade rate: ~50% compliance by tool call 40
• Context warnings missed: 4/5 sessions reached 75%+ without checkpoint
• Protocol violations: Agents commit without asking, add features without request

---

Current Workarounds (All Insufficient)

1. User Intervention

User must manually remind agent: "Please check context status" or "Remember to follow CLAUDE.md"

Problem: Defeats the purpose of persistent instructions; user becomes the memory system

2. Explicit Checklist Files

Created SESSION_COMPLIANCE_CHECKLIST.md with periodic self-check instructions

Problem: Agent must remember to read the checklist - same fundamental issue

3. Shorter Sessions

End sessions before directive drift becomes severe

Problem: Fragments work; loses continuity; context waste

4. Repeated Instructions in Prompts

Include critical directives in every user prompt

Problem: Token waste; user fatigue; error-prone

---

Proposed Solutions

Option A: Periodic Directive Refresh (Recommended)

Implement automatic re-reading of key directive files at configurable intervals:

// settings.json or claude_config.json
{
  "directiveRefresh": {
    "enabled": true,
    "interval": 20,  // tool calls
    "files": ["CLAUDE.md", "PROJECT_Approvals.md"],
    "sections": ["## Critical", "## Context Monitoring"]
  }
}

How it works:

• Every N tool calls, agent silently re-reads specified files/sections
• Brings directives back into "active context"
• Configurable to balance compliance vs. token cost

Option B: Background Task System

Allow directives to register background tasks that execute periodically:

<!-- In CLAUDE.md -->
## Background Tasks

```yaml
- task: check_context
  interval: 10  # tool calls
  action: "Read .claude/context-status.json, warn if > 65%"

- task: compliance_check
  interval: 20
  action: "Verify operating within Approvals.md scope"

**Benefits:**
- First-class support for persistent behaviors
- User-configurable without code changes
- Clear execution model

### Option C: Compliance Hooks

Add hooks that fire before/after tool calls to verify compliance:

```json
// hooks.json
{
  "beforeToolCall": [
    {
      "name": "contextCheck",
      "condition": "toolCallCount % 10 === 0",
      "action": "readFile('.claude/context-status.json')",
      "alert": "ctx_pct > 65"
    }
  ]
}

Benefits:

• Integrates with existing hooks system
• Precise control over timing
• Can be conditional

Option D: Directive Priority Tagging

Allow marking certain directives as "high priority" that resist recency bias:

<!-- CLAUDE.md -->
## Context Monitoring <!-- priority: critical -->

Check every 10 tool calls...

Implementation: High-priority sections get elevated weight in attention mechanism or are periodically surfaced.

---

Comparison of Solutions

| Solution | Complexity | Token Cost | Reliability | User Control |
|----------|-----------|------------|-------------|--------------|
| A: Periodic Refresh | Low | Medium | High | High |
| B: Background Tasks | Medium | Low | Very High | Very High |
| C: Compliance Hooks | Medium | Low | High | High |
| D: Priority Tags | High | Low | Medium | Low |

Recommendation: Start with Option A (simplest), evolve to Option B (most powerful)

---

Expected Behavior

After implementation:

1. Agent reads CLAUDE.md at session start
2. Every N tool calls, agent re-reads critical sections
3. Directives remain "fresh" throughout session
4. Context thresholds are reliably monitored
5. User doesn't need to manually remind agent

---

Impact

Current Impact

• Sessions frequently hit context compaction without warning
• Users lose work due to missed checkpoints
• Agents drift from project conventions
• Trust in persistent instructions erodes

After Fix

• Reliable long-session behavior
• Predictable directive compliance
• Reduced user cognitive load
• Enables sophisticated AI workflows

---

Related Issues

• #18027 - Context visibility limitations
• #12070 - Session permissions not persisting (related - permissions drift)
• #21246 - Output verbosity controls (workaround for observability)

---

Technical Notes

Why This Happens

Recency bias in attention: Instructions read early in a session have decreasing influence as the context window fills with recent content. The mathematical attention weight of CLAUDE.md content at token position ~1000 is significantly lower than content at token position ~50000.

No refresh mechanism: Unlike human memory which can be refreshed through repetition, AI context is write-once. Early instructions don't get reinforced.

Why Current Architecture Can't Solve This

• Hooks only fire on tool calls, not internally
• No way to schedule periodic internal actions
• User prompt is the only way to inject new attention

Implementation Considerations

• Must balance token cost vs. compliance benefit
• Should be configurable (some users want fully autonomous, others want control)
• Need metric for "directive staleness" to optimize refresh timing
• Consider partial refresh (just critical sections) vs. full re-read

---

Community Interest

This affects anyone building:

• Long-running AI sessions
• Multi-file codebases with conventions
• Projects with security/permission requirements
• Automated workflows with compliance needs

The CxMS project (Agent Context Management System) has documented this extensively and built workarounds, but the fundamental issue requires platform support.

---

Attachments

• SESSION_COMPLIANCE_CHECKLIST.md - Our current workaround template
• Session logs showing directive drift over time (available on request)

---

Summary

Problem: Agents don't reliably follow persistent directives in long sessions
Impact: Data loss, protocol violations, user trust erosion
Solution: Periodic directive refresh mechanism (configurable)
Benefit: Reliable long-session behavior, sophisticated AI workflows enabled

This is a foundational capability for professional AI-assisted development workflows.

---

Submitted by CxMS Project - https://github.com/RobSB2/CxMS*
Contact: opencxms@proton.me