agent-ctx-guard
压缩是过程,可验证才是结果。
Verifiable context compression for agent sessions — fold, reversible unfold, tamper-evident ledger.
pip install agent-ctx-guard # zero deps, Python 3.9+
agent-ctx-guard folds a long session transcript into small metadata summaries while preserving every original message in a hash-checked archive. The ledger is a tamper-evident JSONL hash chain; the archive is byte-verifiable; summaries are metadata-only, so you can publish what was compressed without leaking raw content. 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-ctx-guard | verifiable context compression (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
Context compression is the hot topic in the agent world. But most compressors are black boxes — you never know what was dropped. This library answers that: compression is a process, and agent-ctx-guard makes it a verifiable result. It is the memory-ledger approach applied to session compression: fold → reversible unfold → prove nothing was lost.
What you get:
fold()— archive the raw message, append a metadata-only summary to a tamper-evident ledger.unfold()— restore the exact raw message from the archive, verified by sha256 (detects archive tampering).verify()/verify_archive()— prove both the ledger chain and the archive are untampered.- Privacy by default — summaries never include raw content (customizable); raw payloads live only in the hash-checked archive.
- Zero dependencies, pure Python 3.9+ stdlib.
Install
pip install agent-ctx-guard
Quick start
from agent_ctx_guard import CtxFolder
folder = CtxFolder(path_prefix="./my_session") # writes .ctxg.ledger.jsonl + .ctxg.archive.jsonl
# Fold every message as it scrolls out of your active window
for msg in transcript:
entry = folder.fold(msg) # entry["summary"] has the metadata
# Later, restore an exact original
restored = folder.unfold(entry["message_id"])
print(restored["content"])
# Prove integrity any time
assert folder.verify() is True # ledger chain untampered
assert folder.verify_archive() is True
Proof of life
$ python -m agent_ctx_guard
=== ledger entries (metadata-only summaries) ===
{'message_id': '8a845d8f', 'summary': {'role': 'user', 'content_length': 35, 'content_sha256': '482635470c5f087c', 'tokens': 0, 'type': ''}, 'payload_hash': 'f0b074c31dbf'}
{'message_id': '5f72f10e', 'summary': {'role': 'assistant', 'content_length': 112, 'content_sha256': 'c84699ba2cd454cf', 'tokens': 0, 'type': ''}, 'payload_hash': '75543233a758'}
ledger verify: True
archive verify: True
=== unfold restored message 2 ===
I see the token refresh cache is stale after expiry. I'll patch auth.py and add unit tests for the refresh path.
Notice: the ledger contains no raw bodies at all — only role / length / digest. The proof lives in the hash chain, the content stays in the verified archive, and unfold() restores the exact original byte-for-byte.
Invariants
| # | Invariant | Enforced by |
|---|---|---|
| 1 | Ledger is a sha256 hash chain | fold() + verify() |
| 2 | Archive payload hash must match on unfold | unfold() |
| 3 | Summaries never carry raw secrets by default | default_summary |
| 4 | Reload from disk preserves chain + archive | CtxFolder.__init__ |
| 5 | Empty folder verifies True (genesis) | verify() |
Roadmap ideas
- CLI (
ctx-guard fold --file ... --ranges ...). - Integration hook for LLM-generated digests via custom
summary_fn. - Batch compression with prefix-cache-aware range selection.
License
MIT. 中文版
Metadata
Release files for agent-ctx-guard 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_ctx_guard-0.1.0.tar.gz | 9.6 kB | With provenance | Details for agent_ctx_guard-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_ctx_guard-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agent_ctx_guard-0.1.0-py3-none-any.whl |
Total release size: 19.6 kB
Release files / agent_ctx_guard-0.1.0.tar.gz
| Download URL | agent_ctx_guard-0.1.0.tar.gz |
|---|---|
| Size | 9.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7a80e31a258d74bcee1fdd8e654aa3471a2f34cbf7ff2ab2b044c9c403fc46fe
|
|
BLAKE2b-256 checksum How to use checksums |
5a4cd977b87cb8d78a2bec169e8958748c4a20bcd4fa216186d2f0b2fb2e5ec3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / agent_ctx_guard-0.1.0-py3-none-any.whl
| Download URL | agent_ctx_guard-0.1.0-py3-none-any.whl |
|---|---|
| Size | 10.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8538d253067f5c7c9b4d0f7e88ac276c88cd7c1a1284f545971b7db690bc17ca
|
|
BLAKE2b-256 checksum How to use checksums |
587cad788d7baa48b94254005195908943fa87dd520993c0e1d535f4508fc614
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logSecurity for agent-ctx-guard 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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agent_ctx_guard-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logA 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.