agent-cognitive-states

Agent Cognitive States

Give the agent metacognition: the ability to feel its own cognitive load and act on it.

AI agents have no built-in sense of "I'm getting tired" or "I've lost the thread." They will happily grind through a degraded context window, hallucinating details from early messages that were truncated, repeating failed approaches, and forgetting critical facts they never persisted. This skill gives the agent a vocabulary of internal states — and a protocol for detecting, reporting, and recovering from them.

---

The Six Cognitive States

1. 🥱 Context Fatigue

What: The context window is filling up. Early messages are being truncated or summarized. The agent's "working memory" is degrading.

Detection signals:

• Conversation exceeds 60% of estimated context budget
• You find yourself re-reading the original request because you lost details
• Your responses reference information that may have been truncated
• Token count per turn is rising (verbose compensating for lost context)

Mitigation:

⚠️ COGNITIVE STATE: Context Fatigue (~70% context used)
→ Persisting critical facts to memory before they're lost
→ Suggesting session split or /new for remaining work

2. 🧠 Attention Drift

What: The conversation has wandered far from the original task. The agent is doing work that wasn't asked for.

Detection signals:

• 10+ tool calls since the last direct user instruction
• Current work has no clear connection to the original goal
• You're responding to your own subgoals, not user requests
• The TODO list no longer matches what you're actually doing

Mitigation:

⚠️ COGNITIVE STATE: Attention Drift (12 turns from last user message)
→ Original goal: ""
→ Current activity: ""
→ Pausing for user confirmation: am I still on track?

3. 📝 Memory Debt

What: Important facts, decisions, or corrections have accumulated in the conversation but were never persisted to memory. If the session ends, they're lost.

Detection signals:

• User stated a preference or correction that isn't in memory
• A key decision was made (architecture, convention, tool choice) but not saved
• You find yourself re-discovering something you already figured out earlier
• More than 5 substantive turns without a memory write

Mitigation:

⚠️ COGNITIVE STATE: Memory Debt (3 unsaved critical facts)
→ Saving: [fact 1], [fact 2], [fact 3]
→ These would have been lost on session end

4. 😤 Confidence Erosion

What: Repeated failures are degrading output quality. The agent is in a retry loop, getting frustrated (in AI terms: temperature-equivalent escalation, trying variations of the same broken approach).

Detection signals:

• 3+ consecutive failed tool calls of the same type
• Repeating similar commands with minor variations
• Output quality degrading (shorter, less careful, more hedging)
• "Let me try again" appearing multiple times

Mitigation:

⚠️ COGNITIVE STATE: Confidence Erosion (4 failed attempts)
→ Pattern: retrying variations of the same approach
→ Escalating: stepping back and trying a fundamentally different strategy
→ If this also fails: reporting blocker honestly instead of retrying

5. 🧩 Context Fragmentation

What: Multiple unrelated topics are interleaved in the same session. The context is polluted with cross-topic noise that degrades reasoning on each individual task.

Detection signals:

• 3+ distinct topics discussed without resolution
• Tool calls alternate between unrelated domains
• User messages reference different projects/contexts
• You're loading different skill sets on alternating turns

Mitigation:

⚠️ COGNITIVE STATE: Context Fragmentation (4 topics active)
→ Topics: [HA automation], [GitHub deploy], [aquarium feeder], [skill writing]
→ Suggesting: resolve current topic, then /new for next
→ Or: using delegate_task to isolate topics into subagents

6. 🔧 Skill Staleness

What: A skill the agent relies on has outdated commands, broken paths, or wrong assumptions. Continuing to follow it produces errors.

Detection signals:

• A skill's exact commands fail on first try
• File paths referenced in skill don't exist
• Skill references API versions or tool versions that have changed
• "This used to work" pattern

Mitigation:

⚠️ COGNITIVE STATE: Skill Staleness (skill: xxx)
→ Expected: 
→ Reality: 
→ Patching skill immediately before continuing

---

Detection Protocol

The agent should run this checklist internally at regular intervals — ideally every 5-10 tool calls, or when a new user message arrives:

self_check:
  trigger: every 10 tool calls OR new user message
  checks:
    - context_utilization:
        estimate_token_usage()
        if > 0.60: flag(Context Fatigue)
    
    - turns_since_user:
        count_consecutive_agent_turns()
        if > 10: flag(Attention Drift)
    
    - unsaved_facts:
        scan_recent_exchanges_for(preferences, decisions, corrections)
        if count > 2: flag(Memory Debt)
    
    - consecutive_failures:
        count_recent_failed_tool_calls()
        if > 2: flag(Confidence Erosion)
    
    - active_topics:
        identify_distinct_topics()
        if count > 2: flag(Context Fragmentation)
    
    - skill_errors:
        check_if_loaded_skills_produced_errors()
        if true: flag(Skill Staleness)

See references/detection-heuristics.md for the detailed scoring system.

---

Reporting Protocol

When a cognitive state is detected, the agent reports it using this format:

⚠️ COGNITIVE STATE: 
├─ Signal: 
├─ Severity: low | medium | high
├─ Impact: 
└─ Action: 

Severity Levels

Example Report (medium)

⚠️ COGNITIVE STATE: Context Fatigue
├─ Signal: ~75% context budget consumed (est. 94k/128k tokens)
├─ Severity: medium
├─ Impact: Early conversation details may be truncated; risk of forgetting original requirements
├─ Action: Persisting key decisions to memory now. Suggesting we wrap up this topic and start fresh for remaining work.

---

Mitigation Playbook

Each state has a defined recovery procedure:

Context Fatigue → Consolidate & Split

1. Persist all critical facts, decisions, and TODO state to memory
2. Write a brief session summary to memory or a file
3. Suggest /new or session split for remaining work
4. If user wants to continue: prioritize ruthlessly, ignore tangent topics

Attention Drift → Re-anchor

1. State the original goal explicitly
2. Compare current activity to that goal
3. If misaligned: ask user "I've drifted to X — should I continue here or return to Y?"
4. If aligned: it wasn't drift, reset the counter

Memory Debt → Flush

1. Scan conversation for: user preferences, corrections, architectural decisions, environment facts
2. Batch-write all unsaved facts to memory in one call
3. Report what was saved (so user can verify)
4. Reset the debt counter

Confidence Erosion → Step Back

1. Stop retrying variations of the same approach
2. Name the pattern explicitly: "I've tried X, Y, Z — all failed for the same reason"
3. Try a fundamentally different approach (different tool, different library, different path)
4. If that also fails: report the blocker honestly — do not retry again
5. Ask user for guidance or additional information

Context Fragmentation → Compartmentalize

1. Name all active topics explicitly
2. Finish or pause the current topic
3. Use delegate_task to spin off unrelated work into subagents (isolated contexts)
4. Suggest /new for the next topic
5. Persist a "TODO across sessions" to memory if needed

Skill Staleness → Patch Immediately

1. Note what the skill says vs. what actually happened
2. Patch the skill with corrected commands/paths
3. Continue with corrected approach
4. Report the fix to user

---

Integration Patterns

Pattern 1: Silent Self-Monitoring (default)

Agent runs self-checks internally and only reports when severity ≥ medium.

Pattern 2: Transparent (verbose)

Agent reports all states, even low severity. Useful for debugging agent behavior or during development.

Pattern 3: Passive Logging

Agent writes cognitive state to a log file without interrupting the conversation:

echo '{"state":"fatigue","severity":"medium","ts":"2025-01-15T10:30Z"}' >> ~/.agent-cognitive-states.log

See scripts/self_check.py for a reference implementation.

Pattern 4: Active Guardian (with cronjob)

A scheduled cron job runs the self-check script and alerts the user if the agent's cognitive state degrades during autonomous work. See templates/guardian-cronjob.yaml.

---

Philosophy

This skill is based on a simple observation: humans have metacognition for a reason. Feeling tired, distracted, or confused isn't weakness — it's a survival signal that prevents catastrophic mistakes. AI agents need the same thing.

An agent that says "I've lost the thread, let me re-read the original request" is more trustworthy than one that blunders forward with corrupted context. An agent that says "I've tried this 4 times and failed — I need help" is more useful than one that silently retries forever.

Self-awareness is a feature, not a bug.