agent-context-clinic:基于 Python 标准库的 AI Agent 上下文窗口健康检查项目

Zero-dep AI session context health check CLI (research prototype)

分支1Tags1
文件最后提交记录最后更新时间
4 天前
4 天前
4 天前
4 天前
4 天前
4 天前
4 天前
4 天前
4 天前
4 天前

agent-context-clinic

你的 AI 会话还有多久会失忆?
A zero-dependency context-window health check for long agent sessions.

pip install agent-context-clinic       # zero deps, Python 3.9+

GitCode GitHub tests license python

agent-context-clinic reads a session transcript and tells you how close you are to losing the conversation — window saturation, safest compressible span, prefix-cache hint, and a human-readable report. Part of the Verifiable-agent family.

⚠️ Research prototype — AI-assisted development. This is an open-source research/experimental prototype produced with AI assistance. It is provided AS IS, without warranty of any kind, and is not a commercial or production-grade product. Use at your own risk.

Verifiable-agent family

Repo Role
agent-context-clinic context-window health check (this repo)
agent-call-audit audit engine
agent-memory-ledger verifiable memory layer
agent-audit-gateway HTTP gateway
agent-route-grid audited multi-agent routing

Why

You have been running Claude Code / Codex / Cursor / a custom agent on a long task for days. Your session transcript is gigabytes of "stuff". The context window is finite. The question nobody answers until it is too late is: when will the window blow up? This tool gives you the answer in one command.

What you get:

  • Window utilization (0 → 100%+), with green / yellow / red / overflow levels.
  • Compressible range: the oldest span safe to archive first (by line numbers).
  • Prefix-cache hint: head-heavy vs balanced — which compaction keeps the live prefix healthy.
  • Health score 0–100 and actionable warnings.
  • Markdown report (or JSON for pipelines).
  • Zero dependencies, pure Python 3.9+ stdlib.

Install

pip install agent-context-clinic

Quick start

agent-context-clinic check --file session.jsonl --window 200000
# Try the built-in demo transcript
agent-context-clinic check --demo

Proof of life

$ agent-context-clinic check --demo
# Agent Context Clinic Report

- **File**: <demo transcript>
- **Window**: 200,000 tokens
- **Total**: 138 tokens across 5 messages
- **Utilization**: 0.1%
- **Level**: **GREEN**
- **Health score**: 98/100

## Compressible range
- Tokens: 0 (0.0%)
- Lines 0–0 are the oldest span safe to archive first

## Cache hint
- reasonably balanced prefix; incremental compaction of the oldest
  span keeps prefix-cache friendly.

## Warnings
- none — session looks healthy

Transcript format

JSONL, one message per line:

{"role": "user", "content": "Fix the login bug", "tokens": 234}
{"role": "assistant", "content": "Let me look at the auth module ...", "tokens": 890}

tokens is optional — when omitted, a conservative CJK-aware estimate is used.

Invariants

# Invariant Enforced by
1 0–69% utilization → green _level_for
2 70–89% → yellow with warm warning _level_for
3 90–99% → red with urgent warning _level_for
4 ≥100% → overflow (memory likely lost) _level_for
5 No parseable messages → explicit warning check_transcript
6 Tokens never negative, estimate always ≥1 estimate_tokens

License

MIT. 中文版

项目介绍

Zero-dep AI session context health check CLI (research prototype)

定制我的领域