TOMC on macOS

中文速查 · Assistant installation · Dated validation

Desktop companion beta: macOS

The resident desktop cat and the four-stage animation preview are separate programs. Installing the MCP ZIP does not start a desktop cat or connect a request gateway.

From this beta source checkout, prepare a Python environment with the widget dependency:

uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e '.[widget]'
.venv/bin/python scripts/install_macos_pet.py

The installer needs macOS, a C compiler (clang from Apple's developer tools), and a Python installation with development headers and a shared library. It creates ~/Applications/TOMC.app using the environment that ran the installer. Open TOMC.app in Finder to start the normal cat near the bottom-right corner of the primary screen. It does not appear in the Dock. Click the cat for details, drag it to move it, or right-click and choose Quit TOMC to stop it.

The app embeds Python in its native executable so macOS can identify the running application. Keep the checkout, Python installation and virtual environment in place; this is a local development launcher, not a self-contained distributable app. If the default target already exists, the installer refuses to replace it silently. Use --replace to update a TOMC app; it backs up the old bundle and rejects unrelated apps. --output /path/to/TOMC.app selects a different destination.

No login item is installed, no assistant routing is changed, and no test usage events are generated. The cat uses TOMC_MEMORY_PATH when supplied, otherwise ~/.tomc/memory.sqlite3. Without new preparation events it remains idle; seeing the cat does not establish that a real assistant request was compressed.

For a separate, synthetic four-stage preview:

.venv/bin/python scripts/desktop_pet_stages.py /tmp/tomc-animation-preview

This opens a normal preview window on macOS. Each form is shown at the total saving that unlocks it, and no compression or production statistics are written.

2026-10-23 Mac check: the native Cocoa companion was visible as a single floating cat, and remained visible after switching to another application. The macOS tool-window policy now explicitly preserves visibility when the application loses focus; initial launch reveals the cat, while ordinary polling does not activate it. Four queued synthetic events separately completed all four animations and returned to idle. These checks do not validate real-chat gateway triggering or transfer from another computer.

中文：日常入口是 TOMC.app，显示在桌面右下角；横排四只猫的窗口只是素材预览。 本次修复了 Mac 切换应用后小猫隐藏的问题。安装启动器不等于接通自动压缩， 没有新准备事件时小猫会待机。入口依赖本机源码和 Python 环境，暂不是可直接分发的独立安装包。

Earlier MCP installation checks

On 2026-10-02, the downloaded v0.1.0-assistant-preview.2 installed and enabled as a native Codex plugin on macOS 26.3 (25D125), Apple Silicon arm64, Codex CLI 0.159.2. A real model called prepare_context and correctly answered framework = FastAPI, backup_framework = Flask. The local browser demo also prepared the correct result for a manually entered Chinese task. See the original test report and demo screenshot.

Installation worked after preparing the prerequisites. This Mac initially had no UV on PATH and Python 3.9.6; TOMC requires Python 3.10 or later. The trial used UV 0.12.22 and Python 3.12.14; the Claude bundle's separate managed runtime used Python 3.13.16. These are recorded versions, rather than requirements to install these exact releases. Codex, Claude Desktop and Cursor GUI installation was not tested. Claude Code on macOS has not been tested. Claude's extracted .mcpb passed stdio runtime checks, which do not validate its desktop installation flow.

Install the Codex ZIP

1. Install UV using its official instructions, and use a Codex CLI with plugin support. Check the available executables:

uv --version
codex --version
codex plugin --help

1. Download the ZIP and its checksum from the 0.3.1 release, then extract to a directory you will keep. On macOS, check the downloaded bytes before extracting:

shasum -a 256 -c tomc-memory-codex-0.3.1.zip.sha256
unzip tomc-memory-codex-0.3.1.zip -d tomc-codex
cd tomc-codex

If uv is missing, python3 -m pip install --user uv also works. In mainland China, see the mirror commands in the Codex installation guide.

1. Check prerequisites, then install. A separate trial database keeps test notes apart from existing notebooks:

uv run --no-project --python 3.12 install.py --check
uv run --no-project --python 3.12 install.py \
  --store "$HOME/.tomc/macos-trial.sqlite3"

--check validates package files, executable paths and Codex plugin support without writing configuration or registering anything. UV itself may download Python for this command. Regular installation registers the local marketplace and plugin. TOMC's first startup needs network access for compatible Python and locked dependencies. After installing, the helper starts the server once with a throwaway database and lists its tools (--no-verify skips this). Start a new Codex session and say Try TOMC Memory.

If UV or Codex is outside PATH, replace the placeholders with the actual executables on your computer:

"/absolute/path/to/uv" run --no-project --python 3.12 install.py --check \
  --uv "/absolute/path/to/uv" --codex "/absolute/path/to/codex"
"/absolute/path/to/uv" run --no-project --python 3.12 install.py \
  --uv "/absolute/path/to/uv" --codex "/absolute/path/to/codex" \
  --store "$HOME/.tomc/macos-trial.sqlite3"

This also works with a desktop-bundled Codex CLI that your terminal cannot find as codex. Keep quotes around paths containing spaces or Chinese characters. The installer writes absolute runtime paths; keep the extracted directory and UV executable available, and rerun installation after moving them. --configure-only writes the local launch configuration and prints registration commands; it does not install the plugin.

The installer itself also runs under this Mac's system Python 3.9.6. If UV is installed but not on PATH, you can bootstrap with python3 install.py --check --uv "/absolute/path/to/uv" --codex "/absolute/path/to/codex". UV then provides TOMC's compatible runtime; system Python 3.9 is not used to run TOMC. The updated ZIP passed this system-Python preflight without modifying its existing mcp.json; remove --check when ready to install.

Run the demo without installing a plugin

From the repository checkout:

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

Open http://127.0.0.1:7860, choose Use now, then click Try demo. For the tested Chinese task, enter 当前 framework 和 backup_framework 的值是什么？ and click Prepare. Inspect the source links: framework should be FastAPI, while backup_framework keeps the Flask value copied earlier. The default demo prepares text locally without a reader API call. It does not create cross-chat notebooks.

Use the result effectively

• Replace the history for the next API request. In a Python integration, send prepared.messages to your existing client in place of the original history, keeping required application instructions. Appending both adds input. A plugin tool call inside an existing chat does not clear that host's messages or automatically intercept requests; use the result in a new chat when working manually.
• Give TOMC the next task. Preparation selects evidence for that question. Inspect the returned source links and keep the original history available for omitted details. A small history can remain intact, and extra record labels can add overhead.
• Use explicit syntax for structured state. The reference parser supports forms such as framework = Flask and backup_framework copies framework. The copy is a snapshot, so a later framework = FastAPI leaves the backup as Flask. Implicit updates and paraphrases can miss this parser; ordinary prose may use retrieval and retained source text.
• Measure the request you send. The budget covers memory under a lexical estimate. Task text, tools and provider framing add input. Token counts from a lexical estimate and a model tokenizer are different measurements; the same saving percentage does not apply to every task or model.
• Save notes only when persistence is needed. prepare_context does not save history; since 0.3.0 its prepared result is saved only if you turn on tomc settings --save-mcp-results on. remember_memory appends supplied original text to a local notebook; recall_memory prepares that text for a task without rewriting the stored source. list_memories, forget_memory and erase_all_memory find and delete notebooks. The plugin sees content supplied to these tools rather than capturing all chats. Notes are stored as local plaintext and enter the host's context when recalled.

The measured example used the same instruction and English task on both sides:

Counter and input	Before	After	Scope
tiktoken:cl100k_base, English task	147	108	Message text, a 26.53% reduction
Demo lexical estimate, English task	138	90	Message-text estimate
Demo lexical estimate, Chinese task	140	92	Message-text estimate with the translated task

These counts exclude provider chat framing, tool schemas and hidden tokens. The BPE check made no model request and does not measure billed usage. From the checkout, reproduce its counting with:

uv run --python 3.12 --extra tokenizers python examples/api_context.py \
  --tokenizer tiktoken:cl100k_base

For API integration details and complete-input measurement, see the API guide.

Uninstall after a trial

Use the same Codex executable used for installation; replace codex with its quoted absolute path if needed:

codex plugin remove tomc-memory@tomc-local
codex plugin marketplace remove tomc-local

Stop the demo and TOMC sessions. You can then delete the extracted trial package and, if no longer needed, the isolated database you selected with --store. The default ~/.tomc/memory.sqlite3 persists after uninstall; preserve existing notebooks, delete a specific notebook with forget_memory, or erase everything with tomc erase-all --yes before uninstalling. The macOS trial removed the plugin, marketplace, temporary runtimes, packages, databases and new test caches, and checked that Codex configuration matched its prior state. It did not create the default notebook database.

Chinese quickstart

安装成功，但这台 Mac 需要先补齐运行环境。 2026-10-02 实测的是 preview.2、macOS 26.3 / arm64 和 Codex CLI 0.159.2：通过 ZIP 内安装助手安装并启用原生插件，模型实际调用 prepare_context 并正确回答 FastAPI 当前值与 Flask 复制快照。当时版本的五个 MCP 工具、中文笔记保存、重启后取回、独立记忆本与删除均通过；本地浏览器手动输入中文任务并点击 Prepare 也通过。126 项测试及 Ruff 检查通过。Codex、Claude Desktop、Cursor 的 GUI 安装仍未验收，Claude Code 在 macOS 上也尚未测试。原始实测记录 · Demo 截图。

系统原先没有 UV，Python 为 3.9.6；TOMC 需要 Python 3.10 或更新版本。按 UV 官方说明安装（也可以用 python3 -m pip install --user uv；中国大陆网络加 -i https://pypi.tuna.tsinghua.edu.cn/simple，镜像设置见中文安装指南），在解压目录执行上面的 --check 检查，再执行安装命令。--python 3.12 让 UV 提供兼容 Python；首次安装需要联网。UV/Codex 不在 PATH 中时，通过 --uv 和 --codex 指定实际路径，启动命令也使用 UV 的绝对路径。带空格或中文的路径加引号；保留解压目录，移动后重新运行安装助手。

安装助手本身可由这台 Mac 的系统 Python 3.9.6 启动：python3 install.py --check --uv "/实际路径/uv" --codex "/实际路径/codex"。UV 会为 TOMC 准备兼容运行环境，无需为了启动安装助手先替换系统 Python。新 ZIP 已通过系统 Python 启动的预检查，确认不会改写 mcp.json；正式安装时去掉 --check。

使用技巧：

• 应用中用 prepared.messages 替换原历史，保留必要的应用指令；追加在原历史后面会增加输入。在长聊天中调用工具不会清除旧消息，手动使用时可把准备后的结果交给新聊天。
• 给出具体的下一步任务，并检查来源链接。结构化状态使用 key = value、B copies A 等支持的形式；普通文本可能使用检索。短历史可能不缩短，记录标签也可能增加输入。
• 英文例子按 cl100k_base 得到 147 → 108 token，减少 26.53%；Demo 词法估计是英文 138 → 90、中文任务 140 → 92。它们都是消息文本计数，不含供应商封装、工具 schema 或隐藏 token，也不是账单用量或固定节省率。上面的 --tokenizer tiktoken:cl100k_base 命令可复现 BPE 计数。
• prepare_context 不保存历史；0.3.0 起它的准备结果也默认不保存，运行 tomc settings --save-mcp-results on 后才保存。需要跨聊天时才用 remember_memory 保存原文，再用 recall_memory 按任务取回；取回不会改写原文。用 --store 为试用选择独立数据库，避免混入已有记忆本。
• 试用结束，先执行上面的 codex plugin remove 与 codex plugin marketplace remove 两条命令。停止会话后可删除解压目录，以及确认不再需要的独立测试数据库。默认 ~/.tomc/memory.sqlite3 在卸载后保留，不要为了卸载而删除已有笔记。

更完整的步骤见中文安装指南。