Cumulative clones · recorded since 2026-10-02 · updated 2026-10-24 UTC. Method and updates

Found TOMC useful? Click ⭐ Star at the top right to support the project.

TOMC Memory

Context compression and task memory for Codex / Claude Code / Cursor / TRAE / WorkBuddy

Compress and compile long histories, and recall saved task notes on CPU.

Use with your API · Install TOMC Memory · Switch assistants · See the demo · Paper explained · Paper results · English | 简体中文

CPU preparation · No training or extra model service · Plain-text output · Research preview

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

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 the 0.2.0 preview. Download 0.2.0 from the release page; earlier packages stay in the MIT-licensed assistant downloads. There is no PyPI package or public marketplace listing.

In the 0.2.0 MCP runtime, successful preparation and recall save the prepared context and task locally by default. Turn off context recording in the TOMC panel to stop future body storage; existing snapshots remain until deleted. The ten tools include four new read-only tools: get_status, list_contexts, get_context and make_handoff. Old statistics containing only numbers cannot reconstruct earlier chat content.

Processing is on by default globally and for newly registered sessions. User-level setup makes tools available across projects; session-specific controls require installed, loaded hooks, with /hooks trust review in Codex. Configuration does not prove a live connection, and lifecycle hooks do not replace native model requests. The panel follows session/prompt events rather than every UI tab switch. Host integration validation.

The context library can provide a self-contained continuation prompt or a portable text package for another Agent or computer. You may add the exported package to Git yourself; TOMC does not automatically commit or push. Current plugin guide.

Desktop companion (beta). A small desktop cat shows the tokens TOMC saved, their value at each model's listed input price and the conversations they came from, with an analysis report and the context library. On Windows it can also process Codex and Claude Code requests automatically through a local gateway. Install the desktop companion (Windows and macOS).

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.

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.

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.2.0 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.

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

Tested on Windows, macOS and Linux, and in Claude Code. Installation and tool checks passed on all three systems; real model calls passed in Codex on Windows with preview.4 and macOS and in Claude Code with Claude Opus 5.5. GUI installation in Claude Desktop, Cursor and the Codex app is still unverified. Platform checks and dates

Usage tips (English) · Chinese usage tips · Windows installation feedback · Full installation guide · Validation record · Claude checksum · Codex checksum.

Save a project brief in Codex, continue from it in Claude Code, then bring the updated notes back. Install TOMC in both clients and make both servers open the same SQLite file. Each save and recall is an explicit tool call. Shared-path setup.

The notebook keeps the original notes and appended updates; recall prepares that history for the next task. This shares saved notes, rather than migrating native chat histories or providing cross-device cloud sync. MCP interoperability and user-guided checks.

Use AutomaticChatSession before your existing synchronous Chat Completions call: a cache-friendly stable prefix by default (the compiled memory stays identical until the request no longer fits), cached model limits, one-shot window-boundary backoff and brief native-compaction cooldown. Only the outgoing old-history view changes; original history, instructions, recent messages and tool protocol stay with the caller. The default lexical packing path now avoids repeated prefix scans. 34-model capacity snapshot. This does not make an installed MCP plugin intercept built-in client requests, and no native-client/model acceptance is asserted.

Install the core package from this checkout with python -m pip install -e .. Prepare the history, inspect prepared.prompt, then send prepared.messages with your existing chat-completions client:

from tomc import prepare_context

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

Here history, task, client and model are your application's existing inputs and client. Replace the original history for this request; appending the prepared context to it adds input. Keep any instructions your application needs. For other text APIs, map the messages to your provider's format. TOMC changes the request text without changing model weights. API guide and token counting.

45/45 answers at each budget. On nine synthetic team-chat histories (three seeds at about 10K, 20K and 40K history tokens), Windows Codex 0.160.0 answered five latest-project-state questions per history. Its original model, ultra effort and installed plugins were retained. TOMC prepared context through the installed MCP tool before each new answering chat.

Input is Codex's reported total, including cached input, host instructions and tool definitions. Reduction is the mean of nine paired history-level ratios, not the ratio of the table's means. These figures cover one answering turn per history and condition; asking the model to prepare or recall within a chat adds turns. All prepared contexts used tomc_raw source selection, without compiled operation records. This tests synthetic latest-state retrieval, rather than general coding quality. English report · Chinese report · Recorded data · Budget tips. Full-history requests used the same profile with TOMC installed and all existing plugins enabled. The table covers a single answering turn per condition in the test harness; a full agent workflow may involve additional turns.

On synthetic team-chat histories of about 10K, 20K and 40K tokens, with dozens to hundreds of state updates and look-alike distractors, Claude Opus 5.5 answered five questions about the latest project state. When TOMC kept 40% of the history, all five answers matched the full-history condition. The answering-request costs were:

Claude Code default-budget check. Without budget, TOMC keeps about 80% of a history's estimated tokens (at least 1,024, so short histories stay intact). Across three different histories at each length, Claude Opus 5.5 answered all 45 questions correctly with about 20% less input; keeping 50%, 60% and 70% also answered all 45 and saved about 49%, 39% and 30%. Smaller budgets started returning outdated values: keeping 10–20% answered three or four of the five questions. Pass a smaller budget only after checking it against the full history on a sample of your own tasks. These are synthetic histories with one model and a separate request workflow from the Codex test. Validation record · Budget tips

The assistant plugin exposes context-preparation tools. It does not intercept every API request or clear messages already in an active chat. To use a smaller request, your application must send the prepared context, or you can hand it to a new chat. Named notebooks are optional; the current runtime saves prepared-context snapshots by default unless context recording is disabled.

After installing, ask your assistant to call TOMC's prepare_context tool. Pass the text below as history, set task to "What are the current framework and backup_framework values?" and budget to 64, then ask the assistant to answer using the returned memory.

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.

This example uses explicit assignments and a snapshot copy. TOMC prepares framework = FastAPI and backup_framework = Flask, with source links. The host controls tool use; your existing model generates the answer.

With the same instructions and task, this example's message text goes from 147 to 108 tokens under cl100k_base. This counts message content, excluding provider chat framing and tools; it is a single example, not billed usage or a fixed saving rate. Run python examples/api_context.py for the offline lexical estimate, or see the API guide for BPE counting.

The MCP prepare_context tool saves the successful prepared result and task by default, unless context recording is disabled. It does not separately copy the entire original history, but short histories may remain intact in the saved result. The standalone Python preparation helper remains stateless. The budget covers memory under the lexical counter; task text and tool framing add overhead.

The demo shows how TOMC prepares context for a task. It does not create notebooks across chats.

The Gradio interface requires Python 3.10–3.13. Clone the repository:

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.

• 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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.