agent-cognitive-states

Agent self-awareness of cognitive states — context fatigue, attention drift, memory debt, confidence erosion, and skill staleness. Detect, report, and mitigate degrading conditions before they cause failures.

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:

text

⚠️ 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:

text

⚠️ COGNITIVE STATE: Attention Drift (12 turns from last user message)
→ Original goal: "<original request>"
→ Current activity: "<what I'm actually doing>"
→ 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:

text

⚠️ 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:

text

⚠️ 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:

text

⚠️ 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:

text

⚠️ COGNITIVE STATE: Skill Staleness (skill: xxx)
→ Expected: <what skill says>
→ Reality: <what actually happened>
→ 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:

yaml

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:

text

⚠️ COGNITIVE STATE: <State Name>
├─ Signal: <what triggered detection>
├─ Severity: low | medium | high
├─ Impact: <what could go wrong if ignored>
└─ Action: <what the agent is doing about it>

Severity Levels

Level	Meaning	Agent Behavior
low	Early warning. No impact yet.	Note internally. Continue normally.
medium	Starting to degrade. Quality at risk.	Report to user. Suggest mitigation.
high	Actively degrading. Failures likely.	Report immediately. Execute mitigation. Pause if needed.

Example Report (medium)

text

⚠️ 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:

text

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.