Context Rot Detection

上下文腐化检测

为 AI Agent 提供认知状态自我感知能力的 MCP 服务。

每个长时间运行的 AI Agent 都会受到上下文腐化的影响——随着上下文窗口逐渐填满，性能会出现可衡量的下降。Chroma、Stanford（“中间遗失”）和 Redis 的研究证实，这是生产环境 Agent 系统中最常见的实际故障模式。

受到上下文腐化影响的 Agent 并不知道自己的表现正在下降——它只是开始做出更差的决策。此工具可让 Agent 实时了解自身的认知健康状况。

功能

• 基于 Token 利用率、检索准确率和会话疲劳度计算的健康评分（0–100）
• 支持 15+ 款精选模型（Claude、GPT、Gemini、o-series）的模型专属性能衰减曲线
• 自动解析任意 HuggingFace 模型——传入 meta-llama/Llama-3.1-70B 之类的仓库 ID，即可自动检测上下文窗口，并将结果缓存到 SQLite
• 基于 Stanford 研究的中间遗失风险评分
• 工具调用负担和会话疲劳度分析
• 可执行的恢复建议——精简上下文、将内容转存到记忆中、创建检查点、拆分为子任务
• 按 Agent 跟踪健康历史（SQLite）
• 服务范围的利用率统计

快速开始

npx（无需安装）

npx context-rot-detection

npm（全局安装）

npm install -g context-rot-detection
context-rot-detection

MCP 客户端配置

Claude Code

在项目根目录的 .mcp.json 中添加：

{
  "mcpServers": {
    "context-rot-detection": {
      "command": "npx",
      "args": ["-y", "context-rot-detection"],
      "env": {
        "HEALTH_HISTORY_DB": "./health.db"
      }
    }
  }
}

Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "context-rot-detection": {
      "command": "npx",
      "args": ["-y", "context-rot-detection"],
      "env": {
        "HEALTH_HISTORY_DB": "/path/to/health.db"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "context-rot-detection": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "context-rot-data:/data",
        "ghcr.io/milos-product-maker/context-rot-detection:latest"
      ]
    }
  }
}

配置

环境变量	描述	默认值
HEALTH_HISTORY_DB	用于保存健康历史的 SQLite 数据库路径。使用 :memory: 表示临时存储。	:memory:
LOG_FILE	用于追加结构化 JSON 日志行的路径。省略此项可禁用文件日志记录。	(无)

工具

check_my_health

分析当前上下文窗口的健康状况。在长时间会话期间定期调用，或在做出关键决策之前调用。

参数：

参数	类型	必填	描述
token_count	integer	是	当前上下文窗口中估算的 Token 数量
model	string	否	大模型标识符——精选模型名称（例如，claude-opus-4、gpt-4o）、HuggingFace 仓库 ID（例如，meta-llama/Llama-3.1-70B），或任意字符串（将回退到保守默认值）
session_duration_minutes	integer	否	此会话已运行的时长
tool_calls_count	integer	否	此会话中已进行的工具调用次数
context_summary	string	否	当前任务和近期操作的简要摘要
agent_id	string	否	用于历史记录跟踪的唯一 Agent 标识符

响应示例：

{
  "health_score": 62,
  "status": "warning",
  "token_utilization": {
    "current": 155000,
    "max_effective": 170000,
    "percentage": 91.2,
    "danger_zone_starts_at": 170000
  },
  "quality_estimate": {
    "retrieval_accuracy": "degrading",
    "middle_content_risk": "high",
    "estimated_hallucination_risk": "moderate"
  },
  "session_fatigue": {
    "tool_call_burden": "moderate",
    "session_length_risk": "low",
    "recommendation": "Consider breaking into sub-tasks if complexity increases."
  },
  "recommendations": [
    {
      "priority": "high",
      "action": "compact_context",
      "reason": "You are approaching the effective quality threshold. Summarize older context and remove completed task details.",
      "estimated_quality_gain": 15
    },
    {
      "priority": "high",
      "action": "offload_to_memory",
      "reason": "High risk of lost-in-the-middle effect. Store critical information to external memory before it is effectively lost.",
      "estimated_quality_gain": 8
    }
  ]
}

get_health_history

检索特定 Agent 的健康检查历史记录。

参数：

参数	类型	必填	描述
agent_id	string	是	唯一 Agent 标识符
limit	integer	否	返回的最大记录数（默认值：20，最大值：100）

get_service_stats

获取服务范围的利用率统计。无需参数。

返回调用总数、唯一 Agent 数量、平均健康评分、模型分布、状态分布和近期活动（过去 1 小时 / 过去 24 小时）。

支持的模型

模型	最大 Token 数	危险区间	中间位置信息丢失风险
claude-opus-4-5	200K	175K	低
claude-opus-4	200K	170K	低
claude-sonnet-4	200K	165K	低
claude-3.7-sonnet	200K	160K	低至中
claude-3.5-sonnet	200K	152K	中
claude-haiku-3.5	200K	130K	中
gpt-4.1	1M	500K	中
gpt-4.1-mini	1M	450K	中
gpt-4o	128K	105K	中
gpt-4o-mini	128K	95K	中至高
o3	200K	160K	低至中
o4-mini	200K	150K	中
gemini-2.5-pro	1M	600K	中
gemini-2.5-flash	1M	520K	中至高
gemini-2.0-flash	1M	500K	高

HuggingFace 自动解析

任何包含 / 的模型字符串都会被视为 HuggingFace 仓库 ID。服务会从仓库获取 config.json，提取上下文窗口大小（max_position_embeddings、n_positions 或 max_seq_len），并生成保守的退化配置：

• 最大 Token 数的 65% → 退化开始
• 最大 Token 数的 80% → 危险区间

结果会缓存到 SQLite 中，后续查询可即时完成。

model: "meta-llama/Llama-3.1-70B"       → 131K context, danger at 105K
model: "mistralai/Mistral-7B-v0.1"      → 32K context, danger at 26K
model: "mosaicml/mpt-7b"                → 65K context, danger at 52K

如果获取失败（网络错误、模型受限或配置缺失），服务会静默回退到保守默认值。

回退

任何不包含 / 的无法识别的模型字符串都会回退到保守默认值（最大值为 128K，危险区间为 100K）。

工作原理

健康评分由四项信号加权计算得出：

信号	权重	来源
Token 使用率质量	40%	特定模型的 sigmoid 退化曲线
检索准确率	25%	基础准确率减去中间位置丢失惩罚
工具调用负担	20%	工具调用达到 10 次以上后的累积质量损失
会话长度	15%	基于时间的疲劳启发式算法

退化曲线根据实证研究得出：

• Chroma：上下文退化 — 200K 模型在约 147K–152K Token 时质量开始退化
• Stanford：中间位置丢失 — 对上下文窗口中间位置的信息，检索准确率会下降
• Redis：上下文退化 — 长时间运行的 Agent 中会出现累积退化效应

开发

git clone https://github.com/milos-product-maker/context-rot-detection.git
cd context-rot-detection
npm install
npm run dev        # Run with tsx (hot reload)
npm test           # Run unit tests
npm run build      # Compile TypeScript

使用 MCP Inspector 进行测试

npx @modelcontextprotocol/inspector node dist/index.js

许可证

MIT