 |
 |
  |
累计克隆 · 自 2026-10-02 起记录 · 更新于 2026-10-26 UTC。 统计口径与更新
TOMC 帮上忙了？点一下右上角 ⭐ Star，支持我们继续更新。
在 CPU 上压缩编译长历史，取回已保存的任务笔记。
接入 API · 安装 TOMC Memory · 换助手继续 · 查看 Demo · 论文详解 · 论文结果 · English | 简体中文
CPU 准备上下文 · 无需训练或额外模型服务 · 输出普通文本 · 研究预览
当前是 **v0.2.1 预览版**。安装包见[发布页](https://github.com/ZipengWu365/TOMC/releases/tag/v0.2.1-preview.1)；早期安装包仍在[MIT 许可助手插件预览包](https://github.com/ZipengWu365/TOMC/tree/main/plugins/downloads)。尚无 PyPI 发布版或公开插件市场条目。
**桌面小猫（测试版）。** 桌面上的小猫显示 TOMC 节省的 token、按各模型输入价值多少钱、来自哪些对话，并提供分析报告和上下文库。Windows 上还可以通过本机网关自动处理 Codex 和 Claude Code 的请求。[安装桌面小猫](docs/desktop_companion.md#chinese-quickstart)（Windows 和 macOS）。
### 视频介绍
[](launch/media/v13/videos/TOMC_Overview_ZH.mp4)
[完整视频（1 分 28 秒，有声）](launch/media/v13/videos/TOMC_Overview_ZH.mp4) · [English video](launch/media/v13/videos/TOMC_Overview_EN.mp4) · [素材与测试范围](launch/media/v13/README.md)
API 接入方在请求前调用 TOMC，发送准备好的上下文。Codex 和 Claude Code 通过工具保存或召回任务笔记。视频中的数字来自各自的测试条件，不代表模型提供商背书。
[实测结果](#实测节省)保留了 Codex、Claude Code 各自的实验条件和原始记录。
[首次使用指南](#first-run-tomc) · [Python API](#接在你的-api-调用之前) · [完整实验结果和局限](#实测节省)。
TOMC 目前是研究预览。欢迎试用、反馈、提交 Issue 和 PR，以及交流与研究合作。换设备与换助手可以独立选择；跨设备笔记传递采用手动 Git。
### 接入常用助手
选择你所用客户端的接入方式。TOMC 在本地 CPU 上准备上下文，回答由助手生成；插件本身不需要额外的大模型 API key 或 GPU。
**当前聊天由宿主管理。** Codex、Claude Code 等宿主负责上下文压缩时，TOMC 不主动再次压缩同一聊天；无法确认宿主状态时也默认由宿主负责。TOMC 用于另外提供的外部历史和明确保存的任务笔记。这是工具调用规则，不是自动压缩状态检测器。[上下文归属说明](docs/context_ownership_zh.md)。插件包 0.1.1 包含此规则，编译核心仍为 0.1.0。
#### 首次试用
**Claude Code：保存一条任务笔记，再在新聊天中取回。** 先安装 [UV](https://docs.astral.sh/uv/getting-started/installation/)，然后在 Claude Code 内执行：
```text
/plugin marketplace add ZipengWu365/TOMC
/plugin install tomc-memory@tomc
```
新开会话或重新加载 VS Code，使用 `/mcp` 检查 `plugin:tomc-memory:tomc`，再明确要求调用工具：
```text
请调用 TOMC 的 remember_memory，将下面的笔记保存为 api-refactor：
公共 API 路由不得改变；分页测试尚未编写。
请展示工具结果。
```
在**使用同一本地记忆数据库的新聊天**中，要求：
```text
请调用 TOMC 的 recall_memory，取回 api-refactor。
报告之前的约束和未完成工作，并展示工具结果。
```
笔记需要主动保存和召回，插件不会自动记录全部聊天。[Claude Code 安装指南](docs/assistant_plugin_zh.md#claude-code) · [笔记共用排查](docs/usage_tips_zh.md#reuse-notebooks)。
**Codex CLI：安装插件并检查工具是否可用。** [下载 0.2.1 版 Codex ZIP](https://github.com/ZipengWu365/TOMC/releases/download/v0.2.1-preview.1/tomc-memory-codex-0.2.1.zip)，解压到准备保留的目录，使用 UV 与兼容的 Codex CLI 执行：
```bash
uv run --no-project --python 3.12 install.py --check
uv run --no-project --python 3.12 install.py
```
第一条命令只检查前提条件，不修改 Codex 配置；安装后需要**新开 Codex 会话**，并明确要求调用 TOMC 保存或召回命名笔记。[完整 Codex 说明](docs/assistant_plugin_zh.md#codex) · [平台验证范围](docs/platform_checks.md)。
**Python API：先离线检查上下文，再接入大模型。** 需要 Python 3.10 或更新版本：
```bash
git clone https://github.com/ZipengWu365/TOMC.git && printf '\n%s\n%s\n' \
'如果 TOMC 对你有帮助，欢迎 Star 支持（自愿）：' 'https://github.com/ZipengWu365/TOMC'
cd TOMC
python -m pip install -e .
python examples/api_context.py
```
上面的 Bash / Git Bash 命令会在克隆成功后显示一次自愿 Star 邀请。直接使用普通 `git clone` 不会显示；克隆完成不代表已经安装。
这个示例仅在本地准备并统计上下文，**不调用模型**。实际使用时，`prepared.messages` 应当**替换**原历史，并保留应用需要的指令和工具协议。[API 接入示例](#接在你的-api-调用之前) · [参考文档](docs/api_reference.md)。
#### 其他客户端接入
| 客户端 | 从哪里开始 | 前提条件 |
|---|---|---|
| Codex CLI | [下载插件 ZIP](https://github.com/ZipengWu365/TOMC/releases/download/v0.2.1-preview.1/tomc-memory-codex-0.2.1.zip) | 支持插件命令的新版 Codex CLI，且 [`uv`](https://docs.astral.sh/uv/getting-started/installation/) 在 PATH 中或通过 `--uv` 指定 |
| Codex IDE extension | [配置本地 MCP 服务](docs/assistant_setup.md) | 本地 TOMC 环境已安装 `.[mcp]` |
| Cursor | 生成安装链接，或[添加 MCP 配置](docs/cursor_trae_zh.md) | 本地 TOMC 运行环境；客户端工具调用尚未验证 |
| TRAE（国际版 / 国内版） | [添加 TOMC 本地 MCP 服务](docs/cursor_trae_zh.md#trae) | 本地 TOMC 运行环境；客户端工具调用尚未验证 |
| 腾讯 WorkBuddy | [配置 TOMC 本地 MCP 服务](docs/workbuddy_zh.md) | 本地 TOMC 运行环境；客户端工具调用尚未验证 |
| Claude Desktop | [下载 `.mcpb` 扩展](https://github.com/ZipengWu365/TOMC/releases/download/v0.2.1-preview.1/tomc-memory-0.2.1.mcpb) | 支持 UV 扩展的新版 Claude Desktop；首次安装需要联网 |
| Claude Code | `/plugin marketplace add ZipengWu365/TOMC`，再运行 `/plugin install tomc-memory@tomc`（[说明](docs/assistant_plugin_zh.md#claude-code)） | [`uv`](https://docs.astral.sh/uv/getting-started/installation/)；已在 Claude Code 的 VS Code 扩展中测试 |
CPU 构建 · 无需训练或辅助神经模型 · 输出普通文本 · 研究预览
*方法图来自论文。Demo 使用较小的参考解析器，与实验适配器的差异见[方法说明](docs/method.md)。*
例如，历史中有三条操作：
```text
drink = tea
backup_drink copies drink
drink = decaf tea
```
当前 `drink` 是 `decaf tea`，但 `backup_drink` 保留复制时的 `tea`。TOMC 按顺序执行操作，并把结果连接到原始语句。
*顶部比较先在各模型内合并 500K/1M 的有效问题，再等权平均相对变化。能力图使用共同有效问题，两档长度的均值等权平均。[全部长度、配对数与协议](benchmarks/RESULTS.md)。*
**编译记录带来了什么？** 独立的 BEAM 消融移除记录及配套指令，保留原文和上游路由。三个模型的时间推理分数都在保留编译时更高，但整体效果因模型而异。这是有无编译的比较，与上面的外部基线比较分开。
RULER 衍生诊断检验状态跟踪，以及 NIAH/QA2 对原文的需求。修复后的 NIAH 配对实验，有/无额外原文的平均 F1 为 **87.28 / 82.26**；移除后输入减少约 **43%–44%**。这是独立重跑的批次，不与历史 Query 分数组合。[任务结果与局限](docs/claims_and_limitations.md)。
*论文原版 Figure 3。a,b 的输入参照是 Query selection；c,d 的参照是完整 TOMC/state route，† 标记修复后的 NIAH 配对。VT 是 state-route 诊断。[更大的 2×2 阅图布局](assets/paper_ruler_review.png) · [对应数值](docs/paper_results.md#ruler-derived-mechanisms-and-component-ablations)。*
论文的[构建成本 Table 3](docs/paper_results.md#construction-efficiency-and-resources)保留各阶段计时及 CPU/GPU/RAM 测量范围，不包含 Reader 推理。[图像来源记录](docs/PAPER_FIGURE_USAGE.json)。
证据快照于 **2026-09-28** 从论文提交 **`7399657`** 同步。分数来自实验适配器。Demo 使用较小的解析器和行级 BM25；其 `rag` 不等于 BEAM-RAG，`hybrid` 也不等于[历史 Hybrid-RAG 对照](benchmarks/HISTORICAL_BEAM.md)。
### 选择策略
| 策略 | 交给模型的记忆 | 适用场景 |
|---|---|---|
| `raw` | 完整输入，可能超过预算 | 未压缩对照 |
| `head` / `tail` | 开头或结尾的文本 | 位置选择对照 |
| `rag` | BM25 排序后的原文行 | 关键词查找 |
| `tomc` | 仅编译记录；没有记录时使用检索 | 检查支持的状态、关系或计数操作 |
| `tomc_raw`（编译 API 默认） | 记录与选中的原文 | 同时需要计算结果和原始措辞 |
| `hybrid` | 按固定任务规则选择表示 | 混合任务、引用问题 |
#### 字符串匹配的局限
参考解析器识别 `key = value`、`B copies A` 和 `x -[rel]-> y` 等形式。证据选择和任务路由也使用固定词法规则。换一种说法、名称含义不清、隐含更新或陌生格式，都可能导致证据遗漏或路由错误。
结构化状态应使用支持的语法，并核对来源。普通文本可以使用检索或保留原文的策略；这些策略也受到预算限制，不能保证保留所有相关细节。[支持的操作](docs/method.md) · [已知局限](docs/claims_and_limitations.md)。
#### Token 如何计算
Demo 默认显示**词法估算值**。记忆计数不包含当前任务、消息框架、模型输出和检查界面。可选 `tiktoken:cl100k_base` 测量该编码，实际计费以提供商为准。`retention_ratio` 表示输出/输入，`compression_ratio` 表示输入/输出。显示的价格由用户输入的单价计算。默认 Demo 不调用回答模型。
### Python 接口
在 Python 程序中，可先调用 `prepare_context(history, task)`，再执行现有模型调用。
**模型和 API 可以继续用原来的。** TOMC 输出普通文本，可以交给接受文本的大模型 API，也可以复制到聊天界面。内置连接器支持 chat-completions 兼容接口；其他 API 通过你自己的客户端转换消息格式。构建记忆不需要模型权重或 API key，生成回答仍由你选定的模型完成。
```text
历史 + 当前任务 → TOMC 在 CPU 上准备上下文 → 你现有的大模型 API
```
核心包需要 Python 3.10+，没有第三方运行依赖。在仓库中激活环境后，执行 `python -m pip install -e .`：
```python
from tomc import prepare_context
context = prepare_context(
"研讨会人数现为 28 人，B 会议室有空，但还没有预订。",
"接下来需要安排什么？",
)
print(context.prompt) # 复制到聊天界面
# 或将 context.messages 交给现有的 chat-completions 客户端。
# 其他 API 可以使用 context.prompt，或按其接口转换消息。
```
### 核对结果与扩展
```bash
python -m pip install -e '.[demo,dev,mcp]'
python -m pytest -q
python benchmarks/reproduce/current.py
python benchmarks/reproduce/results.py
python -m mkdocs build --strict
```
当前结果脚本检查快照哈希和聚合计算；历史结果脚本从对话聚合数据重建旧版四模型统计。[复现说明](docs/reproducibility.md) 列出了各批次可核对的内容。
接入模型时，将 `result.reader_messages(query)` 交给自己的客户端，或使用可选 [API 连接器](docs/api_reference.md)。[LLMLingua 适配器](docs/comparison_with_llmlingua.md) 单独安装。开发检查和错误案例提交方式见 [CONTRIBUTING.md](CONTRIBUTING.md)。
### 引用与许可
TOMC 的源码和原创合成示例采用 [MIT 许可证](LICENSE)，可免费用于研究、教学、个人及商业用途，允许修改、二次开发、再发布和集成到其他项目。复制或分发软件的全部或实质性部分时，须保留版权声明和许可证。欢迎试用、反馈、贡献与合作。
如果 TOMC 支持了你的研究，欢迎引用论文；引用是推荐做法，不是额外的许可条件。论文为预印本，作者依次为 Zipeng Wu、Yanjun Zhao、Fabian Spill 和 James Andrews，arXiv 编号公布后会补充。[CITATION.cff](CITATION.cff) 提供同一条目，供 GitHub 的 *Cite this repository* 按钮使用。反馈与合作可联系 Zipeng Wu（zxw365@student.bham.ac.uk）。
```bibtex
@misc{wu2026tomc,
title = {Task-Oriented Memory Compilation: Executable State Representations for Long-Context Language Models},
author = {Wu, Zipeng and Zhao, Yanjun and Spill, Fabian and Andrews, James},
year = {2026},
note = {Preprint},
url = {https://github.com/ZipengWu365/TOMC}
}
```
案例均为合成输入。仓库提供数值聚合，不分发基准题目、模型答案或私有 API payload。[数据来源](DATA_PROVENANCE.md) · [数据与许可](docs/data_and_license.md)。