Agent Context Token Optimizer v2

English

A local-first, dependency-free core for replacement-history compaction and an owner-bound secure tool-output vault, with honest adapters for multiple agent ecosystems.

Capability matrix

Target	History	Vault	Mode / boundary
Hermes Agent	policy helper / explicit host patch point	automatic allowlisted transform hook + retrieval tool	History: integration helper; Vault: Native plugin
OpenAI-compatible/custom	Python message helper	explicit middleware helper	Native helper when the application controls messages/tool results
LangChain / LangGraph	duck-typed conversion + state helper	compose the core helper in a tool wrapper	Native helper; this package does not patch framework internals
AutoGen	message-list helper	compose a tool wrapper	Native helper only at application-owned hooks
CrewAI	task-context handoff	compose a tool wrapper	Wrapper; no claim of private transcript mutation
Claude Code	new/resumed-session JSON handoff	explicit MCP tools	Wrapper + MCP-only; cannot rewrite existing history or automatically intercept output
Codex CLI	new/resumed-session JSON handoff	explicit MCP tools	Wrapper + MCP-only; cannot rewrite existing history or automatically intercept output
OpenCode	new/resumed-session JSON handoff	explicit MCP tools	Wrapper + MCP-only; cannot rewrite existing history or automatically intercept output

MCP caveat: text passed explicitly to store_tool_result normally already entered the host/model context. MCP provides owner-bound retention and retrieval, not retroactive token savings or automatic interception.

Install and run

python3 -m pip install .
context-token-optimizer install-hermes-plugin
python3 -m token_optimizer.cli compact --agent claude-code < handoff.json
TOKEN_OPTIMIZER_OWNER='<host-generated-opaque-id>' \
  python3 -m token_optimizer.mcp_server --store ~/.context-token-optimizer/vault
python3 -m pytest -q

Never let the model choose the MCP process owner. Generate/bind it in host configuration. See Integration, Architecture, Verification, and Changelog.

Safety contract

Latest real user intent remains last; summaries are reference-only. Vault artifacts use hashed owner binding, strict IDs/types, sensitive-content rejection, SHA-256 integrity, 0700 directories, 0600 files, atomic writes, TTL checks on read and cleanup, and a total quota. These controls reduce risk but do not make retained untrusted content safe to execute.

中文

v2 提供本地优先、无第三方运行时依赖的替换历史压缩核心和绑定 owner 的安全工具输出仓库，并为多种 Agent 生态提供不夸大能力的适配器。

能力矩阵

目标	历史压缩	输出仓库	模式 / 边界
Hermes Agent	策略 helper / 显式宿主补丁点	白名单自动 transform hook + 取回工具	历史：集成 helper；Vault：Native 插件
OpenAI-compatible/custom	Python 消息 helper	显式 middleware helper	应用控制消息和工具结果时为 Native helper
LangChain / LangGraph	鸭子类型转换 + state helper	在工具 wrapper 中组合 core	Native helper；不修改框架内部
AutoGen	消息列表 helper	组合工具 wrapper	仅限应用可控 hook 的 Native helper
CrewAI	task-context handoff	组合工具 wrapper	Wrapper；不声称修改私有历史
Claude Code	新建/恢复会话 JSON 交接	显式 MCP 工具	Wrapper + MCP-only；不能原地改历史或自动截获输出
Codex CLI	新建/恢复会话 JSON 交接	显式 MCP 工具	Wrapper + MCP-only；不能原地改历史或自动截获输出
OpenCode	新建/恢复会话 JSON 交接	显式 MCP 工具	Wrapper + MCP-only；不能原地改历史或自动截获输出

**MCP 限制：**显式传给 store_tool_result 的正文通常已经进入宿主/模型上下文。MCP 只提供绑定 owner 的保存和取回，不代表自动拦截或追溯性节省 Token。

安装与命令同上。MCP owner 必须由宿主生成并通过进程参数/环境绑定，不能让模型传入。安全措施包括 owner 哈希绑定、严格类型与 ID、敏感内容拒绝、SHA-256、原子写、0700/0600 权限、读取时 TTL 和总配额；仓库内容仍应视为不可信数据。

License / 许可证

MIT; third-party projects retain their licenses and copyrights. / MIT；第三方项目保留其许可证与版权。