Skip to main content

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+

GitCode GitHub tests license python

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)

Source distribution for agent-ctx-guard 0.1.0
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)

Table of built distributions (wheels) for agent-ctx-guard 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

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 Full 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