TOMC

Official GitHub home · Plugin downloads · Installation guide

This is the official repository for TOMC Memory, with source code, plugin downloads and installation guides.

Inspect recorded examples · API, shared-memory and evaluation guides

Part 1 · Use TOMC Memory

TOMC Memory is an open-source tool built on Task-Oriented Memory Compilation (TOMC). It compresses and compiles context for AI assistants and provides task memory through explicitly saved notes. It is available through an MCP server and a Python API. Give it a history, the next task and a memory budget. It selects source text and computes supported state, relation or count records, so your application can send the prepared context in place of the full history. Preparation runs on CPU, with no training or extra model service.

Use task memory while making videos, organizing materials, handling files or developing code: save the brief, decisions, constraints, completed steps and remaining work with remember_memory, then use recall_memory to prepare those notes for the next task. These are examples of how to use saved notes. The recorded measurements below cover synthetic project histories and the paper benchmarks, with their own tasks and protocols; they do not establish performance for every task in these workflows.

Add the Python API to your own application, install the plugin in Codex or Claude Code, or connect Cursor, TRAE, Tencent WorkBuddy and Claude Desktop through local MCP. Savings depend on the history and task; short histories can stay intact. The default keeps about 80% of a long history. Compare 40% or 60% budgets on your own tasks when you need smaller requests; see the separate Codex and Claude results.

Reuse saved task notes in a new chat with the same assistant or another assistant. With both clients using the same TOMC database on one computer, you can reuse saved decisions, constraints and next steps. Try the Codex → Claude Code → Codex handoff.

This is a preview, version 0.1.0. Download the plugins from the MIT-licensed assistant preview. There is no PyPI package or public marketplace listing.

Video overview

Full video (1:37, with sound) · Chinese video · Media and test scope

API integrations call TOMC before the next request and send the prepared context. Codex and Claude Code use tools to save or recall task notes. The numbers in the video come from specific tests with their own protocols and imply no provider endorsement.

The measured results give the Codex and Claude Code protocols and their source records.

First-run guide · Python API · Full results and limitations.

TOMC is a research preview. Feedback, issues, pull requests and research collaboration are welcome. Device choice and assistant choice are independent; cross-device notebook transfer uses manual Git.

Install in your assistant

Choose the setup for your client. TOMC prepares context locally on CPU; your assistant generates the answer. The plugin itself needs no additional model API key or GPU.

The host manages the active chat. When Codex, Claude Code or another host owns conversation compaction, TOMC does not proactively recompact that chat. Unknown host state also defaults to host ownership. Use TOMC for separately supplied external history or explicitly saved notes. This is a tool-use policy, not an automatic compaction detector. Context ownership. Plugin packages 0.1.1 include this policy; the compiler core remains 0.1.0.

First run

Claude Code: save one note, then recall it in a new chat. Install UV first. In Claude Code, run:

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

Start a new session or reload VS Code and check /mcp for plugin:tomc-memory:tomc. Ask the assistant explicitly to run the tool:

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.

In a new chat using the same local notebook database, ask:

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

Save and recall are explicit tool calls. The plugin does not record the whole chat automatically. Detailed Claude Code setup · Shared-notebook checks.

Codex CLI: install the plugin and verify tool availability. Download the 0.1.2 Codex ZIP, extract it into a directory you will keep, and run there with UV and a compatible Codex CLI:

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

The first command checks prerequisites without changing Codex configuration. Start a new Codex session after installing and explicitly ask it to save/recall a named note. Full Codex instructions · Platform validation.

Python API: inspect an offline context example before calling a model. With 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

The Bash / Git Bash command above prints an optional Star invitation after a successful clone. Plain git clone does not show it; cloning alone does not install TOMC.

This example prepares and counts context locally; it makes no model call. To integrate TOMC, send prepared.messages in place of the original history, preserving your application's instructions and protocol. API example · Reference.

Other client integrations