Token optimiser

Long tool output is the most expensive thing in an agent turn, and most of it is output the model has already been shown. The optional token optimiser folds that away before it is inserted into the conversation, and keeps a handle so the agent can read the full text if it needs to.

It is off by default.

What it touches

Two tools, and only two: bash (its stdout) and read_file (its content). Output under 1,000 characters is passed through untouched.

That narrowness is measured, not cautious. Replayed against real sessions, the shell path cuts 37.6%, and every point of it comes from folding output already shown earlier in the same conversation. The write and edit paths decline by design, and web_fetch is already bounded by its own content cap, so wiring them in would add surface without adding savings.

The optimiser runs in process. It is not an MCP server, deliberately: that server publishes 26 tools and 8,241 bytes of definitions that ride on every single request, which costs more than the folding saves and makes tool selection worse at the same time.

Turning it on

Integrations → Context savings carries the toggle and the numbers. Switching it on is an org-admin action, because it changes what every session in the org does.

NAKAMA_OMNI=1 sets the server-wide default for orgs that have not chosen. An explicit org setting wins in both directions, so an admin who switched it off in the dashboard is not overridden by the environment, and the reverse holds too.

Reading the panel

The panel shows two arms, not one number.

• Optimized: bytes that went in, bytes that came out, per tool and per day.
• Control: what went in when nothing shortened it, recorded with equal bytes in and out.

One arm alone would not be a measurement. "6 KB removed" against a blank is a restatement of the fact that the feature is switched on. The control arm is what makes the comparison mean something.

Two honest limits on the figures:

• They are bytes at insertion, not tokens. A real token figure needs the provider's own input-token count split by arm, which is separate work.
• Turn-level input tokens are shown alongside, and turns whose count came from an estimate rather than the provider are labelled as estimated.

The panel also reports whether the binary is actually present. That signal exists because the optimiser fails open: with it missing, an org that switched it on and an org with an idle day produce identical numbers, and an operator deserves to be told which one they are looking at.

Expanding what was folded

Folded content is archived, and the marker left in its place carries a handle:

[OMNI: 3f9a2c ...]

The agent gets one extra tool, omni_retrieve, that takes a handle and returns the full text. That tool is the reason folding is allowed at all. Without it, the agent would be told content existed and given no way to read it, which is worse than an honest truncation.

Handles are per org. The ledger lives at omni.db under the org memory directory, and is scoped per conversation: a chat session by session id, and an automation run by its run id. Scoping any wider would let the ledger claim a run had already seen output that went somewhere else.

Installing the binary

The optimiser is a separate binary, pinned to a single version rather than resolved to latest, so an install does not change under a restart.

• In the image. The Docker build carries it by default. Override with docker build --build-arg OMNI_VERSION=....
• At runtime. An instance already deployed cannot be talked into a rebuild, so switching the toggle on fetches the binary and reports the reason when it cannot. Set NAKAMA_OMNI_AUTO_INSTALL=0 to refuse that and rely on the image alone.

The download is checked against the SHA256SUMS published with the same release. Stated plainly: that catches a truncated or corrupted download. It is not a defence against a compromised release, since whoever can replace the archive can replace the sums. Operators who need more than that disable auto-install and build the binary into the image.

Only Linux and macOS targets are published. Windows is reported unsupported rather than half-handled.

Limits

• Bytes, not tokens, as above.
• bash and read_file only.
• Nothing is deleted. Folded text is archived and retrievable for the life of the org ledger.