Skip to main content

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. 中文版

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)

Source distribution for agent-context-clinic 0.1.0
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)

Table of built distributions (wheels) for agent-context-clinic 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page