TOMC Memory

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

觉得 TOMC 实用？点击右上角的 ⭐ Star 来支持这个项目。

TOMC Memory

为 Codex / Claude Code / Cursor / TRAE / WorkBuddy 提供上下文压缩和任务记忆

在 CPU 上压缩并整理长历史记录，回忆已保存的任务笔记。

与 API 搭配使用 · 安装 TOMC Memory · 切换助手 · 查看演示 · 论文解读 · 论文结果 · English | 简体中文

CPU 预处理 · 无需训练或额外模型服务 · 纯文本输出 · 研究预览版

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

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

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

第 1 部分 · 使用 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.1.0。从 采用 MIT 许可证的助手预览版下载插件。目前没有 PyPI 软件包或公开市场条目。

视频概览

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

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

测量结果列出了 Codex 和 Claude Code 的测试协议及其源记录。

首次运行指南 · Python API · 完整结果和限制。

TOMC 是研究预览版。欢迎提供反馈、报告问题、提交拉取请求以及开展研究合作。设备选择与助手选择相互独立；跨设备传输笔记本需手动使用 Git。

在助手中安装

选择适合你客户端的配置。TOMC 会在本地使用 CPU 准备上下文；由你的助手生成答案。该插件本身不需要额外的模型 API 密钥或 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.1.2 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 示例 · 参考文档。

其他客户端集成

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

python -m pip install -e '.[mcp]'
python -m tomc setup --client cursor --link

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

**已在 Windows、macOS 和 Linux 上测试，并在 Claude Code 中通过测试。**三个系统上的安装和工具检查均已通过；真实模型调用已在 Codex 的 Windows preview.4 版本、macOS 以及使用 Claude Opus 5.5 的 Claude Code 中通过验证。Claude Desktop、Cursor 和 Codex 应用中的图形界面安装仍未经验证。平台检查和日期

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

切换助手，保留项目笔记

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

笔记本会保留原始笔记和追加的更新；回忆会为下一项任务整理这段历史。这是共享已保存的笔记，而不是迁移原生聊天历史，也不提供跨设备云同步。MCP 互操作性和用户引导的检查。

自动 API 请求循环

在现有的同步 Chat Completions 调用前使用 AutomaticChatSession：默认采用便于缓存的稳定前缀（直到请求不再适配，编译后的记忆都保持不变）、缓存的模型限制、一次性的窗口边界回退，以及简短的原生压缩冷却时间。只有发出的旧历史视图会改变；原始历史、指令、近期消息和工具协议仍由调用方保留。默认的词汇打包路径现在可避免重复扫描前缀。34 个模型的容量快照。这不会让已安装的 MCP 插件拦截内置客户端请求，也不声称已通过原生客户端或模型验收。

在 API 调用前使用

使用 python -m pip install -e . 从此检出版本安装核心包。准备历史记录，检查 prepared.prompt，然后通过现有的聊天补全客户端发送 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 指南和令牌计数。

经测量的节省

Windows Codex · gpt-6.1-sol

每种预算下均为 45/45 个答案正确。 在九段合成团队聊天记录（三个种子，历史记录约为 10K、20K 和 40K 个 token）中，Windows Codex 0.160.0 针对每段历史记录回答了五个关于最新项目状态的问题。保留了原始模型、ultra 努力度和已安装的插件。每次开始新的回答聊天前，TOMC 都通过已安装的 MCP 工具准备上下文。

输入量是 Codex 报告的总量，包括缓存输入、宿主指令和工具定义。降幅是九个配对历史记录级比率的平均值，而不是表中平均值之比。这些数据针对每段历史记录和每种条件下的一个回答轮次；如果要求模型在聊天中准备或回忆信息，则会增加轮次。所有准备好的上下文都使用 tomc_raw 源选择，未使用编译后的操作记录。这项测试评估的是合成最新状态检索，而非一般编码质量。英文报告 · 中文报告 · 记录数据 · 预算提示。完整历史记录请求使用了安装 TOMC 且启用所有现有插件的同一配置文件。表格涵盖测试框架中每种条件下的单个回答轮次；完整的 Agent 工作流可能涉及额外轮次。

Claude Code · Claude Opus 5.5

在约为 10K、20K 和 40K 个 token 的合成团队聊天记录中，这些记录包含数十到数百次状态更新以及相似的干扰信息，Claude Opus 5.5 回答了五个关于最新项目状态的问题。TOMC 保留 40% 的历史记录时，五个答案均与完整历史记录条件下的答案一致。回答请求的成本如下：

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 测试不同。验证记录 · 预算提示

助手插件提供上下文准备工具。它不会拦截每个 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 可进行离线词法估算，或参阅 API 指南 了解 BPE 计数。

prepare_context 不会保存此历史。已经符合预算的历史会保持原样；对于较长的文本，可以使用检索，而不是类型化记录。budget 限制的是词法计数器下的记忆；任务文本和工具封装还会带来额外开销。

试用演示

此演示展示 TOMC 如何为任务准备上下文。它不会在不同聊天之间创建笔记本。

本地运行

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

在 macOS 上，先检查 python3 --version：系统自带的 Python 3.9 无法运行 TOMC。安装 UV 后，可以让它提供 Python 3.12 并直接启动演示：

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

或者，使用已有的兼容 Python，并按照下面的步骤设置环境。macOS 指南。

在 Linux/macOS 上，使用 UV 管理 Python，避免系统缺少 venv/ensurepip 模块。以下命令已通过 Linux 检查：

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

如果你更愿意使用系统 Python，可运行 python3 -m venv .venv 并按上文所述激活环境。Debian/Ubuntu 系统需要安装对应的 python3-venv 软件包。如果失败的命令已创建不完整的环境，可运行 uv venv --python 3.12 --allow-existing --seed .venv 恢复。

或者，在已安装 Python 3.12 的 Windows PowerShell 中运行：

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

然后安装并启动演示：

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

1. 打开 http://127.0.0.1:7860 并选择 立即使用。
2. 点击 试用演示以准备示例，或粘贴你的历史记录、输入下一个任务并点击 准备。
3. 使用复制图标复制准备好的提示词，并将其粘贴到你常用的模型中。

支持文本、Markdown、消息 JSON 和 JSONL。安装后，本地准备过程可离线运行。使用准备好的提示词时，由你的模型生成答案；默认演示不会调用读取器 API。托管预览会在 Space 服务端处理输入。

使用 30 秒导览查看引导示例，使用 工作台比较策略，或使用 研究证据浏览已存档的论文结果。桌面视图 · 移动视图。

在 Ubuntu 24.04.5 和 Python 3.12.13 上，全新下载通过了 Linux 安装和浏览器检查。报告包含截图、插件检查和安装反馈。

实用技巧

• 从 试用演示及其 小型请求示例开始。对于普通文本，可尝试 均衡或 更多细节，并在降低预算前检查保留的来源。
• 在下一次 API 请求中发送准备好的消息，而不是原始历史记录。手动使用时，将提示词粘贴到新聊天中；若将其添加到已有的长聊天中，该聊天此前的输入仍会保留。
• 让任务问题具体明确。检查状态记录和来源文本，尤其是在更改历史记录或记忆大小后。Token 显示的是消息内容估算值，并非服务提供商的计费信息。
• 使用插件时，请保持安装目录和 Python 环境不变。每个客户端只注册一个 TOMC；共享原始软件包，而不要共享包含本地路径的配置。Linux 报告介绍了验证和恢复方法。

第 2 部分 · 论文解读

论文题为 Task-Oriented Memory Compilation: Executable State Representations for Long-Context Language Models。arXiv 链接即将添加。本节介绍其方法和已存档的结果。

在论文中，GPT-5.1、Rednote preview 和 DeepSeek V4.1 Flash 是 API 读取器模型。每组配对的基线与 TOMC 对比都使用同一个读取器。Codex 和 Claude Code 是插件试验中的助手宿主，分别使用 gpt-6.1-sol 和 Claude Opus 5.5；这些试验与论文基准测试相互独立。读取器模型与助手宿主

TOMC 的计算内容

长对话中，变化的事实、较早的副本和证据散落在各条消息中。调用 LLM 前，TOMC 会针对当前问题准备记忆。它会计算状态、关系或计数记录，并在 token 预算内将这些记录与选定的源文本结合。

基于 CPU 构建 · 无需训练或辅助神经模型 · 纯文本输出 · 研究预览版

论文中的方法概述。演示使用小型参考解析器；方法文档说明了它与基准实现的区别。

假设一段历史包含以下更新：

drink = tea
backup_drink copies drink
drink = decaf tea

当前值为 drink = decaf tea，而 backup_drink = tea 保留了复制时的值。TOMC 按顺序执行这些操作，并将结果记录关联到对应的源行。

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

运行 python examples/snapshot.py 可查看完整示例，其中还会追踪 seat。此示例演示复制语义。源标签会增加 token 数；此示例不衡量回答质量。

关系和计数也遵循同样的思路：在将记忆交给读取器之前，先计算问题所需的操作。对于询问原因、引述或状态记录无法表达的其他细节的问题，应保留源文本的措辞。

同一读取器：基线记忆与 TOMC 记忆

BEAM 研究使用 GPT-5.1、Rednote preview 和 DeepSeek 4.1 Flash，在 100K、500K、1M 和 10M token 的历史记录上回答问题。每个读取器使用 TOMC 记忆或六种基线记忆配置之一作答。

• **质量：**在 500K、1M 和 10M 下的全部 54 组读取器 × 基线 × 长度比较中，以及全部 18 组整体比较中，TOMC 的平均分均更高。
• **读取器输入：**在 100K–10M 范围内，整体输入量比 LIGHT 低 36.57%，比分层 LLMLingua-2 低 37.38%；计算平均值时，各读取器的变化权重相同。其他一些基线的输入量低于 TOMC。
• **基于 CPU 构建：**在六次重放中，测得的 TOMC 阶段平均耗时为 4.21 s/次调用，CUDA 分配量为 0 GiB，进程 RSS 峰值为 3.75 GiB。在记录的阶段中，每次调用的构建时间比 BRIEF-Pro 短 11.4 倍，比 LongLLMLingua 短 17.1 倍。这些是阶段耗时比，不包括读取器推理。

在每一组配对中，同一读取器会使用由指定基线或 TOMC 构建的记忆回答匹配的问题，并在配对内采用匹配的评分方式。

D/H 分别表示直接式/分层式 LLMLingua-2。总体结果汇总了每个阅读器在所有长度下的有效配对；各行的配对集合和评分协议各不相同，因此请在每个单元格内进行比较。平均分较高并不能证明差异显著。输入变化是相对于基线的 TOMC：负值表示 token 更少。直接式 LLMLingua-2 的 1M 运行产生了 200 条空记忆；这些分数予以保留，但输入量减少不视为成功压缩。

10M 数据于 2026-10-10 添加：来自 10 个会话的 200 个 BEAM 问题，3,600 对中有 3,596 对有效，使用匿名且位置平衡的成对评分标准进行评分。LLMLingua-2 的两个 10M 行均使用了修复后的批次，其中记忆非空。无编译行涵盖 100K–1M；10M 消融实验仍在运行。10M 数据和评分。

顶部的比较按阅读器汇总有效的 500K/1M 问题，然后计算各阅读器相对变化的平均值。能力图使用共同的有效问题，并对各长度进行等权平均。所有长度、配对数和协议。

编译后的记录带来了什么？ 一项单独的 BEAM 消融实验移除了记录及其附带指令，同时保留源文本和上游路由。三种阅读器的时间推理分数在启用编译时均较高，但编译的总体影响因阅读器而异。这项比较针对启用和未启用编译的情况，与上表的基线比较相互独立。

基于 RULER 的诊断检查状态跟踪，以及 NIAH 和 QA2 所需的源文本。修复后的 NIAH 源移除配对得分为 87.28 / 82.26 平均 F1，移除后输入减少约 43%–44%。该结果来自单独的配对重跑；其分数不会与历史 Query 结果合并。任务结果和局限。

论文中的图 3。面板 a、b 以 Query 选择作为输入参照；面板 c、d 使用完整 TOMC/状态路由，并以 † 标记修复后的 NIAH 配对。VT 是状态路由诊断。更大的 2×2 审阅版式 · 数值结果。

论文的构建成本表 3保留了实测的阶段耗时以及 CPU/GPU/RAM 的统计范围；不包括阅读器推理。图表来源。

证据快照已与 2026-09-28 的手稿提交 7399657 同步。上述分数由基准适配器生成。演示版使用更精简的解析器和逐行 BM25；其中的 rag 与 BEAM-RAG 不同，其 hybrid 路由器也不同于历史 Hybrid-RAG 对照。

选择策略

字符串匹配和输入限制

参考解析器可识别 key = value、B copies A 和 x -[rel]-> y 等格式。证据选择和路由也使用固定的词法规则。改述、含糊的名称、隐式更新和不熟悉的格式，可能导致证据遗漏或路由不合适。

对于结构化状态，请使用文档所述语法并检查源链接。对于普通文本，请使用检索或保留源文本的路由。这些选项能保留有用证据，但不能保证预算内包含所有相关细节。支持的操作 · 已知限制。

Token 数量

默认情况下，演示会报告词法估算值。其记忆计数不包含任务、聊天框架、读取器输出和检查器。可选的 tiktoken:cl100k_base 会按该编码计数；服务商的计费结果可能不同。retention_ratio 表示输出/输入，compression_ratio 表示输入/输出。任何显示的价格均来自用户提供的费率。默认演示不会调用读取器 API。

在 Python 中使用

对于 Python 应用，请在现有读取器调用前调用 prepare_context(history, task)。

你的读取器模型保持不变。 TOMC 会返回文本，你可以将其用于任何基于文本的大模型 API，或复制到聊天界面中。内置连接器支持兼容 chat-completions 的 API；其他服务商则使用你自己的客户端和消息格式。构建记忆不需要模型权重或 API 密钥。答案生成仍照常使用你选择的模型。

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

核心包要求 Python 3.10+，且没有运行时依赖。在已激活的环境中，从检出目录运行 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.

检查结果并扩展演示

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

当前结果脚本会验证快照哈希和汇总算术。历史结果脚本会根据对话汇总重建较早的四读取器统计数据。可复现性介绍了各批次可用的内容。

若要运行你自己的读取器，请将 result.reader_messages(query) 传递给你的客户端，或使用可选的 API 连接器。LLMLingua 适配器需单独安装。CONTRIBUTING.md介绍了检查方法，以及如何报告编译器错误处理的输入。

引用与许可

TOMC 的源代码和原创合成示例可在 MIT License 下免费使用，包括商业使用、修改、再分发以及集成到其他项目中。软件副本或其重要部分必须保留版权和许可声明。欢迎反馈、贡献和合作。

如果 TOMC 对您的研究有所帮助，请引用这篇论文。我们鼓励引用，但引用并非额外的许可条件。该论文是 Zipeng Wu、Yanjun Zhao、Fabian Spill 和 James Andrews 撰写的预印本；arXiv 编号将在可用时补充。CITATION.cff 为 GitHub 的 Cite this repository 按钮提供相同的条目。如需反馈和合作，请联系 Zipeng Wu（[email protected]）。

@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 载荷。数据来源 · 数据与许可。