TOMC Memory MCP server
Commit Nov 15, 2026Prepares task-specific context and manages local project notes to ensure AI assistants always receive the latest version of changing facts.
Also known as ZipengWu365/TOMC, tomc
- Stars
- 264
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- 0.1.1
- Last commit
- Nov 15, 2026
- License
- MIT
What is TOMC Memory MCP?
TOMC Memory prepares task-specific context and manages local project notes to ensure AI assistants always receive the latest version of changing facts. It exposes 5 tools, such as prepare_context, remember_memory, recall_memory.
Summary generated from the project's README
About TOMC Memory MCP server
Managing evolving project facts and technical decisions is what TOMC Memory enables for developers using AI assistants. It prevents the common issue of an AI providing outdated information by ensuring only the most recent version of a changing fact is included in the context. This tool works locally on your machine, storing notes in a SQLite database at ~/.tomc/memory.sqlite3.
Developers can integrate this server with various clients including Claude Code, Codex, Cursor, and Claude Desktop. It uses specific tools like prepare_context to manage history and recall_memory to retrieve stored information. Users can also save specific project notes using remember_memory. The system is designed to reduce input token usage by filtering history, though it focuses on matching words rather than semantic meaning to maintain accuracy.
Setup requires Python 3.10 or newer and can be managed via the tomc command line. Users can customize how results are saved with tomc settings and manage their local notebook data using forget_memory or erase-all commands.
What you can do with it
- 1Update project framework decisionsEnsure your AI assistant knows you switched from Flask to FastAPI without re-explaining the change.
- 2Reduce token costs in long chatsDecrease the amount of history sent to the model to save on input costs.
- 3Maintain persistent project notesSave important project details that persist across different AI chat sessions.
- 4Verify uncertain state changesIdentify when a fact might have changed so you can manually verify the latest value.
Written from the project's README. Every use case is checked against a quote from it.
TOMC Memory MCP tools 5
Read from the server with tools/listprepare_contextRead-onlyPrepare separately supplied external history or documents for the next task without saving. Do not call this to proactively recompact the active host-managed chat; unknown host compaction state also leaves chat ownership with the host. Omit budget to keep about 80% of estimated history tokens (at least 1,024). Budget excludes task/tool framing; host history is unchanged.
remember_memoryActionOptionally save user-authorized history as text or message JSON to a named notebook. Appends; preserves earlier entries. Use one name per topic.
recall_memoryRead-onlyPrepare an optional notebook's history for the next task. Omit budget to keep about 80% of the notebook (at least 1,024 estimated tokens). Budget covers estimated memory tokens. Reports and old failures are not proof of current success.
list_memoriesRead-onlyFind saved notebook names. Returns names, entry counts and update times, without content.
forget_memoryActionDelete one exact named notebook when the user asks to forget it. Cannot be undone through this tool.
Configuration
UV_DEFAULT_INDEXUV_PYTHON_INSTALL_MIRROR
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablezipengwu365/tomc is public and reachablegithub.com/zipengwu365/tomc ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-15github.com/zipengwu365/tomc ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubI got tired of re-explaining my project to every new AI chat, and then getting the old version of a decision back.
When a fact changes, only the latest version comes back.
Say your project chat moved from Flask to Django, then FastAPI, then Litestar. TOMC Memory hands your assistant framework = Litestar, plus the line it came from.
After installing, say to your assistant: "Try TOMC Memory". In a terminal: tomc try.
- Latest value, offline check (v0.3.0): 144 questions per budget, each about a fact that changed 3 to 5 times. At the default budget the prepared context held the latest value every time (v0.2.1: 58%). At a 10% budget: 85% (v0.2.1: 51%). Synthetic notes and chats, no model call. We wrote these questions alongside the fixes, so treat them as our regression test, not an independent evaluation.
- Smaller requests in Codex (0.1.0 preview, not re-run since): 9 synthetic project chats of about 10K to 40K tokens, 5 questions each,
gpt-6.1-sol. Keeping 40% of the history cut request input by 29.7% on average, and all 45 answers stayed right. One run per condition. - BEAM long-history benchmark (paper experiments): same reader model on both sides, 3 readers, 6 other memory methods. TOMC had the higher mean score in 54 of 54 comparisons at 500K to 10M tokens, and 17 of 18 at 100K. Mean scores only; not comparable with other projects' BEAM numbers.
Every number, with its conditions and failures · Before you use it · Install
Before you use it
- It does not shrink the chat your assistant is already having. Claude Code and Codex manage their own chat. TOMC Memory works on history you hand it and notes you saved. Context ownership
- Short histories gain little. Under about 10K tokens there is not much to cut. With the default budget, our earlier tests saved roughly 10–20% of input (Codex 9.2%, Claude API-style 19.8%; 0.1.0 previews). Smaller budgets save more but can drop the latest value. Check them on your own tasks first. The default keeps 80% of a history up to 10K tokens, sliding to 60% at 1M, and never less than 1,024 tokens.
- It matches words, not meaning. A reworded update such as "scratch that, go with Django" can be missed, mostly at small budgets. When a later line may have changed a value, the value is marked
STATE?and that line is attached so you or your assistant can check it. - What gets stored, and how to erase it. Results of
prepare_contextandrecall_memoryare not saved unless you turn it on (tomc settings --save-mcp-results on). Notes you save withremember_memorystay on your computer in~/.tomc/memory.sqlite3. Delete one notebook withforget_memory, or everything withtomc erase-all --yes. Security and privacy - Not every client is checked. Codex and Claude Code passed real model calls with earlier previews. For Cursor, TRAE and WorkBuddy the setup is written, but their tool calls have not been checked on real machines. Claude Desktop installation has not been checked in the app.
- The paper is not public yet. The benchmark numbers come from our own runs and setup. The evidence page lists sources, sample sizes and what can be rechecked offline (
make reproduce).
Install
Each path ends the same way: say "Try TOMC Memory" in a new chat, and run tomc doctor if something looks wrong. The Claude Code and Codex plugins need uv. Running from source needs Python 3.10 or newer (python3 --version; the macOS system Python 3.9 is too old).
Claude Code
/plugin marketplace add ZipengWu365/TOMC
/plugin install tomc-memory@tomc
Start a new session, check /mcp for plugin:tomc-memory:tomc, then say "Try TOMC Memory" or run /tomc-memory:try. More Claude Code notes
Codex
Download tomc-memory-codex-0.3.1.zip, unzip it into a folder you will keep, and run there:
uv run --no-project --python 3.12 install.py --check
uv run --no-project --python 3.12 install.py
The installer starts the server once to check it. Open a new Codex session and say "Try TOMC Memory". Full Codex steps
Any MCP client (Cursor, Claude Desktop, WorkBuddy, TRAE …)
git clone https://github.com/ZipengWu365/TOMC.git && cd TOMC
python3 -m venv .venv && .venv/bin/python -m pip install -e '.[mcp]'
.venv/bin/tomc setup --client cursor --write # or claude-desktop, claude-code, codex, workbuddy
.venv/bin/tomc doctor
--write backs up the client's config file first and keeps your other servers. For TRAE or a project file, add --config path/to/mcp.json. Restart the client and say "Try TOMC Memory". On Windows use py -3.12 -m venv .venv and .venv\Scripts\. Per-client guides
Python API
from tomc import prepare_context # pip install -e . from a clone; no dependencies
prepared = prepare_context(history, task)
response = client.chat.completions.create(model=model, messages=prepared.messages)
Send prepared.messages in place of the old history; appending it adds input. .venv/bin/tomc try shows a worked example offline. API guide
Mainland China network
If GitHub or PyPI downloads stall, use a mirror for pip and uv:
python3 -m pip install --user uv -i https://pypi.tuna.tsinghua.edu.cn/simple
export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
export UV_PYTHON_INSTALL_MIRROR=https://registry.npmmirror.com/-/binary/python-build-standalone
python3 -m uv run --no-project --python 3.12 install.py # Codex installer, run in the unzipped folder
For a source install, add -i https://pypi.tuna.tsinghua.edu.cn/simple to the pip install line. In PowerShell, set the variables with $env:UV_DEFAULT_INDEX="…".
Go deeper
- Evidence and claims ledger: every number, its source file, model, sample size and version, plus the negative results.
- What changed in 0.3.1 · in 0.3.0 · Reproduce the offline checks · Independent replications
- Switch assistants and keep your notes: save in Codex, continue in Claude Code, on one computer.
- Desktop companion (beta): a small cat that shows today's estimated context reduction and makes a weekly report card you can share; Windows and macOS. The optional request gateway is Windows only. Linux has the plugins and MCP server only.
- Local demo · How it works · Automatic API request loop · Usage tips · Validation record
- Video overview (1:37). One Codex number in the video has no protocol in this repository; see media notes.
Community, citation and license
Try, compare, contribute: First-run reports · Context-compression evaluation note · Contribution guide
Follow Zipeng Wu for work across time-series research software and AI task memory. Star this repository to save TOMC; use Watch settings for project notifications. Following or starring is optional and is never required for help.
MIT License: free to use, change and ship, including commercially; keep the copyright and license notice. If TOMC Memory helps your research, please cite it with CITATION.cff (GitHub's "Cite this repository" button). Examples are synthetic; the repository holds numeric benchmark aggregates only, without question text, answers or API payloads. Data provenance · Data and licensing
TOMC Memory MCP questions
What tools does TOMC Memory MCP provide?
It exposes 5 tools, including prepare_context, remember_memory, recall_memory, list_memories, forget_memory.
Does it reduce the existing chat history in my assistant?
No, it does not shrink the chat your assistant is already having; it works on history you hand it and notes you saved.
Where are my saved notes stored?
Notes saved with the remember_memory command are stored locally on your computer in a SQLite database.
How can I delete my saved memory?
You can delete a single notebook using forget_memory or wipe everything using the erase-all command.
Does it understand the meaning of reworded updates?
No, it matches words rather than meaning, so reworded updates might be missed at small budgets.