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+
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. 中文版
Metadata
Release files for agent-context-clinic 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_context_clinic-0.1.0.tar.gz | 10.0 kB | Without provenance | Details for agent_context_clinic-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_context_clinic-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agent_context_clinic-0.1.0-py3-none-any.whl |
Total release size: 19.7 kB
Release files / agent_context_clinic-0.1.0.tar.gz
| Download URL | agent_context_clinic-0.1.0.tar.gz |
|---|---|
| Size | 10.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e44b3ff7e13fdb2682a5451f334c9712313a0cdd7b132ad733333fd6962c0211
|
|
BLAKE2b-256 checksum How to use checksums |
3a63eb9a3fa31901f1942f6fe6d7ddad4dbe26c55e030beac7d6b084c57e0ae7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / agent_context_clinic-0.1.0-py3-none-any.whl
| Download URL | agent_context_clinic-0.1.0-py3-none-any.whl |
|---|---|
| Size | 9.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
18ebe6dd551aab9c1cdceecb49a1c468dda48f27c34a0fa8de06ff8ba55819fe
|
|
BLAKE2b-256 checksum How to use checksums |
7817574b465e11392aa42caea582e6850063181505df03c7dc0468e5da1f65ee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for agent-context-clinic 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.