context-rot-detection

MCP service that gives AI agents self-awareness about their cognitive state.
Every long-running AI agent suffers from **context rot** — measurable performance degradation as the context window fills up. Research from Chroma, Stanford ("lost-in-the-middle"), and Redis confirms this is the #1 practical failure mode in production agent systems.
An agent experiencing context rot doesn't *know* it's degrading — it just starts making worse decisions. This tool gives agents **real-time visibility into their own cognitive health**.
Features
- **Health score (0–100)** based on token utilization, retrieval accuracy, and session fatigue
- **Model-specific degradation curves** for 15+ curated models (Claude, GPT, Gemini, o-series)
- **Auto-resolves any HuggingFace model** — pass a repo ID like meta-llama/Llama-3.1-70B and the context window is detected automatically, with results cached in SQLite
- **Lost-in-the-middle risk scoring** based on Stanford research
- **Tool-call burden** and **session fatigue** analysis
- **Actionable recovery recommendations** — compact context, offload to memory, checkpoint, break into subtasks
- **Per-agent health history** tracking (SQLite)
- **Service-wide utilization statistics**
Quick Start
npx (zero install)
npm (global install)
MCP Client Configuration
Claude Code
Add to .mcp.json in your project root:
Claude Desktop
Add to claude_desktop_config.json:
Docker
Configuration
| Environment Variable | Description | Default |
|---|---|---|
| HEALTH_HISTORY_DB | Path to SQLite database for health history. Use :memory: for ephemeral storage. | :memory: |
| LOG_FILE | Path to append structured JSON log lines. Omit to disable file logging. | *(none)* |
Tools
check_my_health
Analyze the current context window health. Call this periodically during long sessions or before critical decisions.
**Parameters:**
| Parameter | Type | Required | Description |
|---|---|---|---|
| token_count | integer | Yes | Current estimated token count in context window |
| model | string | No | LLM model identifier — a curated name (e.g., claude-opus-4, gpt-4o), a HuggingFace repo ID (e.g., meta-llama/Llama-3.1-70B), or any string (falls back to conservative defaults) |
| session_duration_minutes | integer | No | How long this session has been running |
| tool_calls_count | integer | No | Number of tool calls made in this session |
| context_summary | string | No | Brief summary of current task and recent actions |
| agent_id | string | No | Unique agent identifier for history tracking |
**Example response:**
get_health_history
Retrieve health check history for a specific agent.
**Parameters:**
| Parameter | Type | Required | Description |
|---|---|---|---|
| agent_id | string | Yes | Unique agent identifier |
| limit | integer | No | Max records to return (default: 20, max: 100) |
get_service_stats
Get service-wide utilization statistics. No parameters required.
Returns total calls, unique agents, average health score, model distribution, status distribution, and recent activity (last hour / last 24h).
Supported Models