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.
| 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.
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 -qNever let the model choose the MCP process owner. Generate/bind it in host configuration. See Integration, Architecture, Verification, and Changelog.
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 和总配额；仓库内容仍应视为不可信数据。
MIT; third-party projects retain their licenses and copyrights. / MIT；第三方项目保留其许可证与版权。