任务记忆压缩 ZipengWu365/TOMC

累计克隆量 · 自 2026-10-02 起记录 · 2026-10-31 UTC 更新。统计方法与更新

觉得 TOMC 有用？点右上角 ⭐ Star 支持这个项目。
TOMC Memory
为 Codex / Claude Code / Cursor / TRAE / WorkBuddy 提供上下文压缩与任务记忆在 CPU 上压缩并编译长历史，召回已保存的任务笔记。
配合你的 API 使用 · 安装 TOMC Memory · 切换助手 · 看演示 · 论文解读 · 论文结果 · English | 简体中文 CPU 预处理 · 无需训练，也无需额外模型服务 · 纯文本输出 · 研究预览版

GitHub 官方主页 · 插件下载 · 安装指南

试用、对比、贡献： 首次运行报告 · 上下文压缩评测说明 · 贡献指南

关注 Zipeng Wu，了解时序研究软件与 AI 任务记忆方面的工作。Star 这个仓库即可收藏 TOMC；项目通知请用 Watch 设置。关注或 Star 都是可选的，求助时从不要求你这么做。

这里是 TOMC Memory 的官方仓库，包含源码、插件下载和安装指南。

查看已记录的示例 · API、共享记忆与评测指南

第一部分 · 使用 TOMC Memory

TOMC Memory 是开源工具，基于 Task-Oriented Memory Compilation（TOMC）构建。它为 AI 助手压缩并编译上下文，并通过显式保存的笔记提供任务记忆。你可以通过 MCP 服务器和 Python API 使用它。给它一段历史、下一个任务和记忆预算，它会挑选源文本，计算有依据的状态、关系或计数记录，让你的应用可以发送准备好的上下文，替代完整历史。准备工作在 CPU 上运行，无需训练，也不需要额外的模型服务。

做视频、整理材料、处理文件或开发代码时都可以用任务记忆：用 remember_memory 保存任务简报、决策、约束、已完成步骤和剩余工作，再用 recall_memory 把这些笔记准备给下一个任务。这些只是使用已保存笔记的示例。下面的实测数据覆盖合成项目历史和论文基准，各自有自己的任务与协议；它们不能说明这些工作流里每个任务都能达到同样效果。

把 Python API 加进你自己的应用，在 Codex 或 Claude Code 里安装插件，或者通过本地 MCP 连接 Cursor、TRAE、Tencent WorkBuddy 和 Claude Desktop。节省多少取决于历史和任务；短历史可以保持原样。默认保留长历史约 80%。需要更小的请求时，在你自己的任务上对比 40% 或 60% 预算；见单独的 Codex 和 Claude 结果。

在同一个助手或另一个助手的新对话里复用已保存的任务笔记。两个客户端在同一台电脑上使用同一个 TOMC 数据库，就能复用已保存的决策、约束和后续步骤。试试 Codex → Claude Code → Codex 交接。

这是 0.2.1 预览版。从发布页下载 0.2.1；更早的包仍在 MIT 许可的助手下载目录。没有 PyPI 包，也没有公开市场上架。

自 0.2.0 MCP 运行时起，准备和召回成功时默认把准备好的上下文和任务保存在本地。 在 TOMC 面板里关闭上下文记录，可停止后续的正文存储；已有快照会保留，直到你删除。十个工具里有四个新的只读工具：get_status、list_contexts、get_context 和 make_handoff。只含数字的旧统计数据无法重建此前的对话内容。
处理默认全局开启，新注册的会话也默认开启。用户级设置让工具在所有项目中可用；会话级控制需要已安装、已加载的钩子，在 Codex 中还要经过 /hooks 信任审查。配置本身不能证明连接已生效，生命周期钩子也不能替代模型原生请求。面板跟随会话/提示词事件，而不是每次 UI 标签页切换。宿主集成验证。

上下文库可以生成一份自包含的续接提示词，或一个可移植的文本包，交给另一个智能体或另一台电脑。导出的包你可以自己加进 Git；TOMC 不会自动提交或推送。当前插件指南。

桌面伴侣（beta）。 一只桌面小猫会显示 TOMC 省下的 token、这些 token 按各模型标价折算的输入费用，以及它们来自哪些对话，还附带分析报告和上下文库。在 Windows 上，它还能通过本地网关自动处理 Codex 和 Claude Code 的请求。安装桌面伴侣（Windows 和 macOS）。

视频概览

TOMC 概览：更小的输入、切换助手、把笔记带到另一台电脑，以及 BEAM 结果

完整视频（1:37，带声音） · 中文视频 · 媒体与测试范围

API 集成会在下一次请求之前调用 TOMC，并发送准备好的上下文。Codex 和 Claude Code 用工具保存或调取任务笔记。视频里的数字来自特定测试，各有自己的协议，不代表任何服务商背书。

实测结果给出 Codex 和 Claude Code 的协议及其源记录。

首次运行指南 · Python API · 完整结果与局限。

TOMC 是研究预览版。欢迎反馈、issue、pull request 和研究合作。设备选择和助手选择相互独立；跨设备转移笔记需要手动使用 Git。

在你的助手中安装

按你的客户端选择安装方式。TOMC 在本地用 CPU 准备上下文；答案由你的助手生成。插件本身不需要额外的模型 API key 或 GPU。

宿主管理当前对话。 当 Codex、Claude Code 或其他宿主负责对话压缩时，TOMC 不会主动重新压缩该对话。宿主状态未知时也默认归宿主所有。请把 TOMC 用于另外提供的外部历史，或显式保存的笔记。这是工具使用策略，不是自动压缩检测器。上下文归属。插件包 0.1.1 包含此策略；编译器核心仍为 0.1.0。

首次运行

Claude Code：保存一条笔记，然后在新对话里召回。 先安装 UV。在 Claude Code 里运行：

/plugin marketplace add ZipengWu365/TOMC
/plugin install tomc-memory@tomc

开一个新会话，或重载 VS Code，然后在 /mcp 里确认出现 plugin:tomc-memory:tomc。明确要求助手运行工具：

Use TOMC's remember_memory to save a note named api-refactor:
keep public API routes unchanged; pagination tests have not been written.
Show the tool result.

在使用同一个本地笔记数据库的新对话里，问：

Use TOMC's recall_memory on api-refactor.
Report the saved constraints and unfinished work. Show the tool result.

保存和召回都是显式的工具调用。插件不会自动记录整段对话。Claude Code 详细配置 · 共享笔记检查。

Codex CLI：安装插件并验证工具可用。 下载 0.2.1 Codex ZIP，解压到一个你会长期保留的目录，在该目录下用 UV 和兼容的 Codex CLI 运行：

uv run --no-project --python 3.12 install.py --check
uv run --no-project --python 3.12 install.py

第一条命令只检查前置条件，不改动 Codex 配置。安装后开一个新的 Codex 会话，明确要求它保存/召回一条命名笔记。Codex 完整说明 · 平台验证。

Python API：调用模型之前，先看一个离线上下文示例。 需要 Python 3.10+：

git clone https://github.com/ZipengWu365/TOMC.git && printf '\n%s\n%s\n' \
'If TOMC helps with your work, consider a Star on GitHub (optional):' 'https://github.com/ZipengWu365/TOMC'
cd TOMC
python -m pip install -e .
python examples/api_context.py

上面这条 Bash / Git Bash 命令会在克隆成功后打印一条可选的 Star 邀请。单纯的 git clone 不会显示它；只克隆也不会安装 TOMC。

这个示例在本地准备并统计上下文，不调用模型。要接入 TOMC，把 prepared.messages 代替原始历史发送，同时保留你应用的指令和协议。API 示例 · 参考文档。

其他客户端集成

| 客户端 | 从这里开始 | 前置条件 |
| Codex CLI | 下载插件 ZIP | 支持插件命令的当前 Codex CLI，以及 PATH 上的 uv，或用 --uv 指定 |
| Codex IDE 扩展 | 配置本地 MCP 服务器 | 本地 TOMC 环境，已安装 .[mcp] |
| Cursor | 生成安装链接，或添加 MCP 配置 | 本地 TOMC 运行时；客户端工具调用尚未验证 |
| TRAE（国际版 / 国内版） | 把 TOMC 添加为本地 MCP 服务器 | 本地 TOMC 运行时；客户端工具调用尚未验证 |
| 腾讯 WorkBuddy | 通过本地 MCP 配置 TOMC | 本地 TOMC 运行时；客户端工具调用尚未验证 |
| DeepSeek Harness | 本地 MCP 安装与双会话演示 | 装有 .[mcp] 的 Python、Node.js，以及配置好的 DSH 模型；非官方社区集成 |
| Claude Desktop | 下载 .mcpb 扩展 | 已更新且支持 UV 扩展的 Claude Desktop；首次安装需要联网 |
| Claude Code | /plugin marketplace add ZipengWu365/TOMC，然后 /plugin install tomc-memory@tomc（详情） | uv；已在 Claude Code VS Code 扩展上测试 |

Codex 安装步骤

Codex 命令行

下载上面的 ZIP，解压到一个你会长期保留的目录，然后在该目录中打开终端。运行：

uv run --no-project --python 3.12 install.py --check
uv run --no-project --python 3.12 install.py

第一条命令只检查前置条件，不注册插件，也不写入配置。第二条命令为你的电脑准备路径，注册本地市场并安装 TOMC。启动新的 Codex 会话即可使用。需要时 UV 会下载 Python 和依赖。如果某个可执行文件不在 PATH 中，传入 --uv /absolute/path/to/uv 或 --codex /absolute/path/to/codex；如果 UV 本身不在 PATH 中，就用 UV 可执行文件的路径启动命令。解压后的目录要保留在原位；移动后请重新运行安装程序。把原始 ZIP 分享给别人，不要分享包含你路径的已配置副本。

Codex IDE 扩展请从已安装 .[mcp] 的环境运行 python -m tomc setup --client codex，再把打印出的 MCP 条目加到设置里。安装指南包含直接注册命令。在客户端里，原生插件和独立的 TOMC MCP 注册二选一，避免工具重复。

Cursor 安装步骤

Cursor

克隆仓库，并按助手安装指南激活本地环境。在该环境中运行：

python -m pip install -e '.[mcp]'
python -m tomc setup --client cursor --link
打开打印出来的链接，确认 Add to Cursor。新建一个聊天，检查 TOMC 是否已启用。链接会登记你已安装的环境；保持该环境不动，如果移动了位置就重新生成链接。在一台电脑上生成的链接不能当作另一台电脑的安装包。

TRAE 安装步骤

TRAE

参照 Cursor / TRAE 指南 及其可直接编辑的 JSON 模板。在 Settings → MCP → Add → Create Manually 中添加，选择本地环境。也可以启用项目级 MCP，使用 .trae/mcp.json。如果当前源码检出已安装 .[mcp]，运行 python -m tomc setup --client trae 会打印适合你环境的配置。TRAE 要求命令路径不含空格；指南里还提供了锁定版本的 UV 运行时。setup 命令只打印配置，不会改动客户端设置。

TRAE 和 Cursor 的客户端工具发现与模型调用尚未验证。这是手动 MCP 集成预览；报告连接错误时请附上客户端版本和操作系统。

腾讯 WorkBuddy 安装步骤

腾讯 WorkBuddy

参照 WorkBuddy 指南，按本地运行时修改其中的 JSON 模板。打开 Plugins → MCP Servers → Configure MCP。把 tomc 条目合并进用户级 ~/.workbuddy/mcp.json 或项目级 .workbuddy/mcp.json，保留已有的服务器。当前源码环境如果已安装 .[mcp]，也可以用 python -m tomc setup --client workbuddy 生成配置。该命令只打印配置。

这是手动本地 MCP 集成预览。WorkBuddy 客户端的工具发现与模型调用仍未验证；腾讯的应用市场里没有列出 TOMC。

Claude Desktop 安装步骤

Claude Desktop

1. 下载上面的 .mcpb 文件。
2. 打开 Settings → Extensions → Advanced settings → Install Extension…，选中该文件。
3. 按安装提示操作，然后新建一个聊天，检查 TOMC 工具。当前 0.2.1 运行时提供十个工具；较早的下载产物保留各自原有的工具集。

受支持的主机会通过 UV 运行时安装 Python 和锁定依赖；用这个包时，你不需要克隆仓库，也不需要手动配置 Python。

Claude Code 安装步骤

Claude Code

Claude Code 以本地 MCP 服务器的方式运行同一套锁定运行时。把上面的 .mcpb 文件（ZIP 压缩包）解压到一个你会长期保留的目录，然后用实际解压路径运行以下命令：

uv sync --locked --directory "/absolute/path/to/extracted"
claude mcp add tomc-memory --scope user -- uv run --locked --directory "/absolute/path/to/extracted" src/server.py
启动新的 Claude Code 会话，运行 /mcp 查看工具（0.2.1 运行时里有十个）。在请求里点名工具，例如 “Use tomc-memory prepare_context on this history with task … and budget 200”。如果 claude 不在 PATH 里，就用 VS Code 扩展 resources/native-binary 文件夹里自带的命令行（Windows 上是 claude.exe）。步骤、VS Code 说明和用法提示

在 VS Code 扩展试用中，用 Claude Opus 5.5、budget 8,192，回忆一个笔记本正确回答了五个问题，成本比把 20K 和 40K token 的历史粘贴进提示词分别低 38% 和 65%；到约 10K token 时成本不变。budget 1,024 更便宜，但漏掉了一些最新值。长历史要在对话之外导入。

已在 Windows、macOS 和 Linux 以及 Claude Code 中测试。 三个系统上的安装和工具检查都通过；真实模型调用在 Codex 中通过（Windows 上的 preview.4 和 macOS），在 Claude Code 中用 Claude Opus 5.5 通过。Claude Desktop、Cursor 和 Codex 应用里的 GUI 安装仍未验证。平台检查与日期

用法提示（英文） · 中文用法提示 · Windows 安装反馈 · 完整安装指南 · 验证记录 · Claude 校验和 · Codex 校验和。

切换助手，保留项目笔记

在 Codex 里保存项目简报，到 Claude Code 里接着用，再把更新后的笔记带回来。在两个客户端里都安装 TOMC，让两个服务端打开同一个 SQLite 文件。每次保存和回忆都是一次显式的工具调用。共享路径设置。

用三条提示词试试交接

这个例子保存的是一条规划笔记，不代表测试已经跑过。

| 位置 | 对助手说 |
| Codex | Use TOMC's remember_memory to save this as api-refactor: keep public API routes and response fields unchanged. Pagination tests have not been written or run. |
| 新建 Claude Code 会话 | 用 TOMC 的 recall_memory 处理 api-refactor，task 填：plan the pagination tests，budget 填：1024。再用 remember_memory 追加：test plan — cover empty results, the last page and invalid page parameters。测试仍未运行。展示两个工具的结果。 |
| 新建 Codex 会话 | 用 TOMC 的 recall_memory 处理 api-refactor，task 填：summarize the API constraints, latest test plan and unfinished work，budget 填：1024。回答前先展示返回的记忆。 |

笔记本保留原始笔记和追加的更新；recall 会为下一个任务准备好这段历史。它共享的是已保存的笔记，不迁移原生会话历史，也不提供跨设备云同步。MCP 互操作与用户引导的检查。

自动 API 请求循环

在你现有的同步 Chat Completions 调用之前，先用 AutomaticChatSession：默认给出对缓存友好的稳定前缀（编译后的记忆保持不变，直到请求不再放得下），缓存模型上限，一次性窗口边界退避，以及短暂的 native-compaction 冷却。只有发出的旧历史视图会变；原始历史、指令、最近消息和工具协议仍留在调用方。默认的词法打包路径现在会避免重复的前缀扫描。34 个模型的容量快照。这不会让已安装的 MCP 插件拦截客户端内置请求，也不断言原生客户端或模型层面的验收。

在你的 API 调用之前使用

用 python -m pip install -e . 从当前检出安装核心包。准备好历史，检查 prepared.prompt，然后用你现有的 chat-completions 客户端发送 prepared.messages：

from tomc import prepare_context

prepared = prepare_context(history, task)
response = client.chat.completions.create(
model=model,
messages=prepared.messages,
)

这里的 history、task、client 和 model 都是你应用已有的输入和客户端。本次请求要替换掉原始历史；把准备好的上下文追加到原始历史后面，只会增加输入。 应用需要的指令要保留。对接其他文本 API 时，把消息映射成你的服务商格式。TOMC 只改请求文本，不改模型权重。API 指南与 token 计数。

实测节省

Windows Codex · gpt-6.1-sol

每个预算下都是 45/45 个回答。 在九段合成的团队聊天历史上（三个种子，历史 token 分别约 10K、20K、40K），Windows Codex 0.160.0 针对每段历史回答了五个最新项目状态问题。它原本的模型、ultra effort 和已安装插件都保留。每次新建回答会话前，TOMC 通过已安装的 MCP 工具准备上下文。

Windows Codex：四个预算全部得分 45/45。平均请求输入与配对降幅。

精确数值（可复制文本）

| 发送的上下文 | 平均请求输入 token | 平均配对输入缩减 | 正确回答 |
| 完整历史 | 42,191 | 基准 | 45/45 |
| TOMC · 40% 历史预算 | 28,713 | 29.7% | 45/45 |
| TOMC · 60% 历史预算 | 33,344 | 19.5% | 45/45 |
| TOMC · 默认 80% 历史预算 | 38,035 | 9.2% | 45/45 |

输入量取 Codex 上报的总量，含缓存输入、宿主指令和工具定义。缩减比例是九组配对历史级比例的平均值，不是表中各均值的比值。这些数字只覆盖每条历史、每种条件下的一轮回答；在对话里让模型准备或回忆，会多出若干轮。所有准备好的上下文都用 tomc_raw 源选择，不含编译后的操作记录。这里测的是合成的最新状态检索，不是通用编码质量。英文报告 · 中文报告 · 记录数据 · 预算建议。完整历史请求用的是同一配置档，装了 TOMC，并启用全部现有插件。表中只覆盖测试框架里每种条件下的一轮回答；完整的智能体工作流可能还要多跑几轮。

Claude Code · Claude Opus 5.5

在约 10K、20K、40K token 的合成团队聊天历史上，夹杂几十到几百条状态更新和形近干扰项，Claude Opus 5.5 回答了五个关于项目最新状态的问题。TOMC 保留 40% 历史时，五个答案全部与完整历史条件一致。回答请求的开销如下：

Claude Code：10K、20K、40K 历史下的开销；图中所有条件均为 5/5。

精确数值（可复制文本）

| 历史 | 完整历史 | TOMC 保留 40% | TOMC 保留 60% |
| ~10K token | US$0.169 · 5/5 | US$0.075 · 5/5（−56%） | US$0.103 · 5/5（−39%） |
| ~20K token | US$0.334 · 5/5 | US$0.141 · 5/5（−58%） | US$0.195 · 5/5（−42%） |
| ~40K token | US$0.628 · 5/5 | US$0.255 · 5/5（−59%） | US$0.369 · 5/5（−41%） |

Claude Code 默认预算检查。 不传 budget 时，TOMC 会保留一段历史估算 token 的约 80%（至少 1,024，所以短历史保持完整）。在每种长度各取三段不同历史，Claude Opus 5.5 把 45 个问题全部答对，输入还少了约 20%；保留 50%、60%、70% 同样答对全部 45 题，分别省下约 49%、39%、30%。预算再小就开始返回过时的值：保留 10–20% 时，五个问题只答对三到四个。想传更小的 budget，先拿你自己的任务样本对照完整历史验证一遍。这些是合成历史，只用一个模型，请求工作流也与 Codex 测试不同。验证记录 · 预算建议

assistant 插件提供上下文准备工具。它不会拦截每个 API 请求，也不会清空活跃聊天里已有的消息。想用更小的请求，你的应用必须发送准备好的上下文，或者把它交给新聊天。命名笔记本是可选的；除非关闭上下文记录，当前运行时默认保存准备好的上下文快照。

准备上下文

安装完成后，让你的助手调用 TOMC 的 prepare_context 工具。把下面的文本作为 history 传入，task 设为 "What are the current framework and backup_framework values?"，budget 设为 64，然后让助手用返回的记忆作答。

framework = Flask
backup_framework copies framework
framework = FastAPI
Monday notes: the team reviewed the project backlog, discussed deployment windows and agreed to keep the public API routes and response fields unchanged during the refactor.
Tuesday notes: the migration plan still needs a review from the database owner, and the pagination tests have not yet been written or run.
Wednesday notes: the team checked the release checklist, added a rollback task, and postponed the documentation update until after the test results are available.

这个例子用了显式赋值和快照拷贝。TOMC 会准备好 framework = FastAPI 和 backup_framework = Flask，并附上来源链接。工具调用由宿主控制；答案仍由你现有的模型生成。

指令和任务相同，这个例子的消息文本在 cl100k_base 下从 147 token 降到 108 token。这里只统计消息内容，不含服务商的聊天框架和工具；这只是单个例子，不代表计费用量，也不是固定的节省比例。运行 python examples/api_context.py 可得到离线词法估算，BPE 计数见 API 指南。
MCP 的 prepare_context 工具默认会保存成功准备好的结果和任务，除非关闭了上下文记录。它不会单独复制完整的原始历史，但短历史可能原样留在保存的结果里。独立的 Python 准备辅助工具仍然是无状态的。budget 覆盖词法计数器下的内存；任务文本和工具框架会带来额外开销。

可选：跨聊天保留历史

notebook 按原始形式存储传入的文本。recall_memory 会为请求的任务准备这段历史；直接调用 prepare_context 不需要 notebook。开启上下文记录后，两条 MCP 准备路径都会把成功的结果和任务分别保存为快照。

在两个聊天或助手中试用记忆

在第一个聊天里，比如在 Codex 中：

Use TOMC to remember this as api-refactor: keep the public API routes and response fields unchanged. Pagination tests still need to be written.

在新聊天里，比如在 Claude Code 中使用同一个数据库：

Recall api-refactor from TOMC. Before we continue, remind me of the constraints and unfinished work.

默认数据库是 ~/.tomc/memory.sqlite3。两个服务器必须解析到同一个文件；自定义 --store 或 TOMC_MEMORY_PATH 可以让客户端彼此隔离。检查路径并试用交接。TOMC 只能看到传给其工具的笔记；安装它并不会自动捕获每个聊天。助手会在其权限设置下决定调用哪些工具。

试用演示

演示展示 TOMC 如何为任务准备上下文。它不会跨聊天创建 notebook。

本地运行

Gradio 界面需要 Python 3.10–3.13。克隆仓库：

git clone https://github.com/ZipengWu365/TOMC.git && printf '\n%s\n%s\n' \
'If TOMC helps with your work, consider a Star on GitHub (optional):' 'https://github.com/ZipengWu365/TOMC'
cd TOMC

On macOS, check python3 --version first: a system Python 3.9 cannot run TOMC. With UV installed, you can let it provide Python 3.12 and start the demo directly:

uv run --python 3.12 --extra demo python -m demo.app

Alternatively, use an existing compatible Python with the environment steps below. macOS guide.

On Linux/macOS, use UV to manage Python and avoid missing system venv/ensurepip modules. These commands passed the Linux check:

uv venv --python 3.12 --seed .venv
source .venv/bin/activate

If you prefer system Python, use python3 -m venv .venv and activate it as above. Debian/Ubuntu installations need the matching python3-venv package. If a failed command already created a partial environment, recover with uv venv --python 3.12 --allow-existing --seed .venv.

Or in Windows PowerShell with Python 3.12 installed:

py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1

Then install and start the demo:

python -m pip install -e '.[demo]'
python -m demo.app

1. Open http://127.0.0.1:7860 and select Use now.
2. Click Try demo to prepare an example, or paste your history, enter the next task and click Prepare.
3. Copy the prepared prompt using the copy icon and paste it into your usual model.

Text, Markdown, message JSON and JSONL are supported. Local preparation works offline after installation. Your model generates the answer when you use the prepared prompt; the default demo makes no reader API call. The hosted preview processes input on the Space server.

Use 30-second tour for a guided example, Workbench to compare strategies, or Research evidence to explore the archived paper results. Desktop view · Mobile view.

Fresh downloads passed Linux installation and browser checks on Ubuntu 24.04.5 with Python 3.12.13. The report includes screenshots, plugin checks and installation feedback.

Practical tips

- Start with Try demo and its Small request example. For ordinary prose, try Balanced or More detail and inspect the retained sources before lowering the budget.
- Send the prepared messages instead of the original history in your next API request. For manual use, paste the prompt into a new chat; adding it to a long existing chat keeps that chat's earlier input.
- Keep task questions specific. Inspect state records and source text, especially after changing the history or memory size. The token display is an estimate of message content, not provider billing.
- For plugins, keep the installation directory and Python environment in place. Use one TOMC registration per client; share the original package, not configuration containing your local paths. The Linux report explains verification and recovery.

Part 2 · The paper explained

The paper is Task-Oriented Memory Compilation: Executable State Representations for Long-Context Language Models. An arXiv link will be added soon. This section explains its method and archived results.

In the paper, GPT-5.1, Rednote preview and DeepSeek V4.1 Flash are API reader models. Each paired baseline and TOMC comparison keeps the same reader. Codex and Claude Code are assistant hosts for the plugin trials, using gpt-6.1-sol and Claude Opus 5.5 respectively; those trials are separate from the paper benchmark. Reader models and assistant hosts

What TOMC computes

Long conversations contain changed facts, earlier copies, and evidence scattered across messages. TOMC prepares memory for the current question before you call the LLM. It computes state, relation, or count records and combines them with selected source text under a token budget.

CPU construction · No training or auxiliary neural model · Plain-text output · Research preview

Method overview from the manuscript. The demo uses a small reference parser; the method documentation explains how it differs from the benchmark implementations.

Suppose a history contains these updates:

drink = tea
backup_drink copies drink
drink = decaf tea

The current value is drink = decaf tea, while backup_drink = tea keeps the value at the time of the copy. TOMC executes these operations in order and links the resulting records to their source lines.

Run this example in Python

from tomc import compile_memory

result = compile_memory(
messages="drink = tea\nbackup_drink copies drink\ndrink = decaf tea",
query="What are the current drink and backup_drink values?",
token_budget=128,
strategy="tomc",
)
print(result.compiled_memory)
print(result.ledger) # records and their sources

Run python examples/snapshot.py for the full example, which also tracks seat. This example demonstrates copy semantics. Its source labels add tokens; it does not measure answer quality.

Relations and counts follow the same idea: compute the operation needed for the question before handing memory to the reader. Keep source wording for questions about reasons, quotations, or other details that a state record cannot express.

Same reader, baseline memory vs TOMC memory

The BEAM study uses GPT-5.1, Rednote preview, and DeepSeek 4.1 Flash to answer questions over 100K, 500K, 1M and 10M-token histories. Each reader answers with either TOMC memory or one of six baseline memory configurations.

- Quality: TOMC has higher mean scores in all 54 reader × baseline × length comparisons at 500K, 1M and 10M, and all 18 overall comparisons.
- Reader input: across 100K–10M, overall input is 36.57% lower than LIGHT and 37.38% lower than hierarchical LLMLingua-2, averaging reader-wise changes equally. Some other baselines use less input than TOMC.
- CPU construction: the measured TOMC stage averages 4.21 s/call across six replays, with 0 GiB CUDA allocation and 3.75 GiB peak process RSS. Per-call construction was 11.4× shorter than BRIEF-Pro and 17.1× shorter than LongLLMLingua in the recorded stages. These are stage-time ratios, with reader inference excluded.

In each pair, the same reader answers matched questions using memory built by the named baseline or by TOMC, with matched scoring within the pair.

Tables as text

| Baseline | GPT-5.1 | Δ (%) | Rednote preview | Δ (%) | DeepSeek 4.1 Flash | Δ (%) | Mean Δ (%) |
| Overall (all lengths) | | | | | | | |
| LLMLingua-2-D (2024) | 34.60 / 55.75 | ↑ 61.1 | 31.23 / 50.75 | ↑ 62.5 | 29.90 / 53.48 | ↑ 78.8 | ↑ 67.5 |
| LongLLMLingua (2024) | 32.77 / 51.68 | ↑ 57.7 | 32.75 / 47.73 | ↑ 45.7 | 36.32 / 53.45 | ↑ 47.2 | ↑ 50.2 |
| BRIEF-Pro (2026) | 34.85 / 51.41 | ↑ 47.5 | 33.87 / 48.04 | ↑ 41.9 | 37.51 / 53.29 | ↑ 42.1 | ↑ 43.8 |
| LLMLingua-2-H (2024) | 40.98 / 56.25 | ↑ 37.3 | 36.50 / 51.76 | ↑ 41.8 | 33.36 / 53.08 | ↑ 59.1 | ↑ 46.1 |
| BEAM-RAG (2026) | 47.94 / 54.90 | ↑ 14.5 | 48.10 / 51.90 | ↑ 7.9 | 47.48 / 53.26 | ↑ 12.2 | ↑ 11.5 |
| LIGHT (2026) | 48.65 / 55.32 | ↑ 13.7 | 47.32 / 51.63 | ↑ 9.1 | 51.44 / 53.16 | ↑ 3.3 | ↑ 8.7 |
| TOMC w/o compilation | 55.00 / 56.20 | ↑ 2.2 | 51.25 / 50.34 | ↓ 1.8 | 49.74 / 52.74 | ↑ 6.0 | ↑ 2.1 |
| 100K tokens | | | | | | | |
| LLMLingua-2-D (2024) | 51.70 / 62.78 | ↑ 21.4 | 45.03 / 56.24 | ↑ 24.9 | 44.73 / 58.22 | ↑ 30.1 | ↑ 25.5 |
| LongLLMLingua (2024) | 39.23 / 57.29 | ↑ 46.0 | 35.36 / 50.53 | ↑ 42.9 | 43.55 / 57.63 | ↑ 32.3 | ↑ 40.4 |
| BRIEF-Pro (2026) | 36.67 / 55.90 | ↑ 52.5 | 34.54 / 52.18 | ↑ 51.1 | 44.43 / 57.63 | ↑ 29.7 | ↑ 44.4 |
| LLMLingua-2-H (2024) | 53.37 / 63.58 | ↑ 19.1 | 45.19 / 58.53 | ↑ 29.5 | 45.05 / 56.65 | ↑ 25.7 | ↑ 24.8 |
| BEAM-RAG (2026) | 53.58 / 62.26 | ↑ 16.2 | 53.48 / 58.25 | ↑ 8.9 | 51.57 / 58.21 | ↑ 12.9 | ↑ 12.7 |
| LIGHT (2026) | 60.50 / 62.26 | ↑ 2.9 | 57.05 / 58.25 | ↑ 2.1 | 61.01 / 58.21 | ↓ 4.6 | ↑ 0.1 |
| TOMC w/o compilation | 57.89 / 58.45 | ↑ 1.0 | 55.78 / 52.78 | ↓ 5.4 | 53.05 / 53.19 | ↑ 0.3 | ↓ 1.4 |
| 500K tokens | | | | | | | |
| LLMLingua-2-D (2024) | 36.68 / 58.99 | ↑ 60.8 | 33.96 / 56.71 | ↑ 67.0 | 30.49 / 59.22 | ↑ 94.3 | ↑ 74.0 |
| LongLLMLingua (2024) | 34.36 / 56.82 | ↑ 65.4 | 34.86 / 54.54 | ↑ 56.5 | 36.54 / 59.43 | ↑ 62.6 | ↑ 61.5 |
| BRIEF-Pro (2026) | 37.42 / 55.18 | ↑ 47.5 | 35.71 / 54.00 | ↑ 51.2 | 39.49 / 59.43 | ↑ 50.5 | ↑ 49.7 |
| LLMLingua-2-H (2024) | 37.31 / 59.00 | ↑ 58.1 | 37.13 / 57.94 | ↑ 56.0 | 33.53 / 59.58 | ↑ 77.7 | ↑ 63.9 |
| BEAM-RAG (2026) | 53.09 / 59.10 | ↑ 11.3 | 52.88 / 56.04 | ↑ 6.0 | 53.08 / 59.46 | ↑ 12.0 | ↑ 9.8 |
| LIGHT (2026) | 49.48 / 59.60 | ↑ 20.4 | 52.38 / 56.04 | ↑ 7.0 | 54.78 / 59.46 | ↑ 8.5 | ↑ 12.0 |
| TOMC w/o compilation | 56.13 / 57.47 | ↑ 2.4 | 50.99 / 50.85 | ↓ 0.3 | 50.25 / 56.02 | ↑ 11.5 | ↑ 4.5 |
| 1M tokens | | | | | | | |
| LLMLingua-2-D (2024) | 24.67 / 58.69 | ↑ 137.9 | 23.90 / 50.54 | ↑ 111.5 | 24.56 / 54.47 | ↑ 121.7 | ↑ 123.7 |
| LongLLMLingua (2024) | 32.66 / 50.91 | ↑ 55.9 | 32.81 / 45.75 | ↑ 39.4 | 36.94 / 54.47 | ↑ 47.5 | ↑ 47.6 |
| BRIEF-Pro (2026) | 35.10 / 53.03 | ↑ 51.1 | 35.66 / 46.88 | ↑ 31.5 | 36.58 / 54.47 | ↑ 48.9 | ↑ 43.8 |
| LLMLingua-2-H (2024) | 43.34 / 58.78 | ↑ 35.6 | 36.01 / 51.97 | ↑ 44.3 | 32.74 / 55.10 | ↑ 68.3 | ↑ 49.4 |
| BEAM-RAG (2026) | 50.75 / 56.38 | ↑ 11.1 | 48.51 / 53.40 | ↑ 10.1 | 50.05 / 53.06 | ↑ 6.0 | ↑ 9.1 |
| LIGHT (2026) | 51.25 / 56.59 | ↑ 10.4 | 45.83 / 53.40 | ↑ 16.5 | 51.15 / 53.06 | ↑ 3.7 | ↑ 10.2 |
| TOMC w/o compilation | 50.96 / 52.68 | ↑ 3.4 | 46.92 / 47.34 | ↑ 0.9 | 45.90 / 49.02 | ↑ 6.8 | ↑ 3.7 |
| 10M tokens | | | | | | | |
| LLMLingua-2-D (2024) | 25.36 / 42.57 | ↑ 67.8 | 22.05 / 39.54 | ↑ 79.3 | 20.35 / 42.20 | ↑ 107.4 | ↑ 84.8 |
| LongLLMLingua (2024) | 24.86 / 41.74 | ↑ 67.9 | 27.97 / 40.10 | ↑ 43.4 | 28.25 / 42.28 | ↑ 49.7 | ↑ 53.7 |
| BRIEF-Pro (2026) | 30.25 / 41.59 | ↑ 37.5 | 29.60 / 39.13 | ↑ 32.2 | 29.52 / 41.63 | ↑ 41.0 | ↑ 36.9 |
| LLMLingua-2-H (2024) | 29.88 / 43.65 | ↑ 46.1 | 27.66 / 38.66 | ↑ 39.8 | 22.56 / 41.58 | ↑ 84.3 | ↑ 56.7 |
| BEAM-RAG (2026) | 34.39 / 41.89 | ↑ 21.8 | 37.46 / 39.83 | ↑ 6.3 | 35.20 / 42.29 | ↑ 20.1 | ↑ 16.1 |
| LIGHT (2026) | 33.38 / 42.87 | ↑ 28.4 | 34.02 / 38.81 | ↑ 14.1 | 38.76 / 41.86 | ↑ 8.0 | ↑ 16.8 |

| Baseline | Overall input change | 10M input change |
| LLMLingua-2-D (2024) | -10.95% | -43.81% |
| LongLLMLingua (2024) | -11.75% | -19.03% |
| BRIEF-Pro (2026) | +280.37% | +297.87% |
| LLMLingua-2-H (2024) | -37.38% | -45.65% |
| BEAM-RAG (2026) | +8.79% | -3.27% |
| LIGHT (2026) | -36.57% | -41.99% |

D/H denote direct/hierarchical LLMLingua-2. Overall pools each reader's valid pairs across all lengths; paired sets and scoring protocols vary across rows, so compare within each cell. Higher mean scores do not establish significance. Input change is TOMC relative to the baseline: negative means fewer tokens. The direct LLMLingua-2 1M run produced 200 empty memories; its scores are retained, and that input reduction is not treated as successful compression.

10M was added on 2026-10-10: 200 BEAM questions from 10 sessions, 3,596 of 3,600 pairs valid, scored with an anonymous position-balanced pairwise rubric. Both LLMLingua-2 10M rows use a repaired batch with non-empty memories. The w/o compilation rows cover 100K–1M; the 10M ablation is still running. 10M data and scoring.

The top comparison pools valid 500K/1M questions within each reader, then averages relative changes across readers. Ability panels use common valid questions and equal length means. All lengths, pair counts, and protocols.

What do the compiled records add? A separate BEAM ablation removes the records and accompanying instructions, retaining source text and upstream routing. Temporal reasoning scores are higher with compilation for all three readers, while its overall effect varies by reader. This is a comparison with and without compilation, separate from the baseline table above.

RULER-derived diagnostics examine state tracking and the source text needed for NIAH and QA2. The repaired NIAH source-removal pair scores 87.28 / 82.26 mean F1, with about 43%–44% less input after removal. It uses a separate paired rerun; its scores are not combined with historical Query results. Task results and limits.

Figure 3 from the manuscript. Panels a,b use Query selection as the input reference; c,d use full TOMC/state route, with the repaired NIAH pair marked †. VT is a state-route diagnostic. Larger 2×2 review layout · Numerical results.

The paper's construction-cost Table 3 retains the measured stage times and CPU/GPU/RAM scope; reader inference is excluded. Figure sources.

The evidence snapshot was synced from manuscript commit 7399657 on 2026-09-28. Benchmark adapters produced these scores. The demo uses a smaller parser and line-level BM25; its rag is different from BEAM-RAG, and its hybrid router is different from the historical Hybrid-RAG control.

Choose a strategy

| Strategy | Memory sent to the reader | Useful for |
| raw | Complete input, even if it exceeds the budget | An uncompressed reference |
| head / tail | Text from the beginning or end | Position-based controls |
| rag | BM25-ranked source lines | Lexical lookup |
| tomc | Records-only mechanism; retrieval when no records are found | Inspecting supported state, relation, or count operations |
| tomc_raw (compiler default) | Records plus selected source text | Tasks that need computed records and original wording |
| hybrid | A representation chosen by fixed task rules | Mixed tasks and quotation requests |

String matching and input limits

The reference parser recognizes forms such as key = value, B copies A, and x -[rel]-> y. Evidence selection and routing also use fixed lexical rules. Paraphrases, ambiguous names, implicit updates, and unfamiliar formats can lead to missed evidence or an unsuitable route.

For structured state, use the documented syntax and inspect the source links. For ordinary prose, use retrieval or a route that retains source text. These options preserve useful evidence but do not guarantee that every relevant detail fits the budget. Supported operations · Known limitations.

Token counts

The demo reports a lexical estimate by default. Its memory count excludes the task, chat framing, reader output, and inspector. Optional tiktoken:cl100k_base counts that encoding; provider billing may differ. retention_ratio means output/input, and compression_ratio means input/output. Any displayed prices come from user-supplied rates. The default demo makes no reader API call.

Use from Python

For a Python application, call prepare_context(history, task) before your existing reader call.

Your reader model stays the same. TOMC returns text you can use with any text-based LLM API, or copy into a chat interface. The built-in connector supports chat-completions-compatible APIs; other providers use your own client and message format. No model weights or API key are needed to construct memory. Answer generation uses your chosen model as usual.

History + current task → TOMC on CPU → prepared context → your existing LLM API

The core package requires Python 3.10+ and has no runtime dependencies. From an activated environment in the checkout, install python -m pip install -e .:

from tomc import prepare_context

context = prepare_context(
"The workshop now has 28 attendees. Room B is available but not booked.",
"What should we do next?",
)
print(context.prompt) # paste into a chat interface
Or pass context.messages to your existing chat-completions client.
For other APIs, use context.prompt or map the messages to their input format.

Check the results and extend the demo

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

The current-results script verifies snapshot hashes and aggregate arithmetic. The historical-results script reconstructs the older four-reader statistics from conversation aggregates. Reproducibility describes what is available for each batch.

To run your own reader, pass result.reader_messages(query) to your client or use the optional API connector. The LLMLingua adapter is installed separately. CONTRIBUTING.md covers checks and how to report an input the compiler handles incorrectly.

Citation and license

TOMC's source code and original synthetic examples are freely available under the MIT License, including for commercial use, modification, redistribution and integration into other projects. Copies or substantial portions of the software must retain the copyright and license notice. Feedback, contributions and collaboration are welcome.

If TOMC supports your research, please cite the paper. Citation is encouraged, not an additional license condition. The paper is a preprint by Zipeng Wu, Yanjun Zhao, Fabian Spill and James Andrews; the arXiv identifier will be added when available. CITATION.cff provides the same entry for GitHub's Cite this repository button. Contact Zipeng Wu (zxw365@student.bham.ac.uk) for feedback and collaboration.

@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}
}

Examples are synthetic. The repository distributes numeric benchmark aggregates without question text, reader answers, or private API payloads. Data provenance · Data and licensing.

For maintainers

Maintainer drafts: launch copy · launch plan · release checklist.

Hugging Face deployment settings.

Context reduction statistics (0.1.2)

Preparation and recall return a per-call estimated context reduction for the assistant to display. Ask for get_usage_stats with period="all", "today", or "7d" (UTC) to view cumulative totals. These are context-text estimates, not actual API or billing savings. Repeated preparations count separately; empty outputs are excluded and negative reductions retained. Numeric statistics contain no history, task text or notebook names. Since 0.1.5, prepared-context bodies and tasks are saved separately by default, unless context recording is disabled. No telemetry is uploaded. Statistics survive notebook deletion; old numeric-only records cannot restore historical content. Existing clients need the new runtime and a new session or supported reload; desktop rendering depends on the host.