# Agent Context Token Optimizer v2

[English](#english) | [中文](#中文)

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

```bash
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](docs/INTEGRATION.md), [Architecture](docs/ARCHITECTURE.md), [Verification](docs/VERIFICATION.md), and [Changelog](CHANGELOG.md).

### 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；第三方项目保留其许可证与版权。