agent-ctx-guard:基于 Python 的 AI Agent 会话上下文可验证压缩项目

Verifiable context compression for agent sessions (research prototype)

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

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

项目介绍

Verifiable context compression for agent sessions (research prototype)

定制我的领域