Add a deployment sizing calculator under tools/sizing (port of #1553 to main) - #1680

Port of #1553 from speedkick to main.

Cherry-pick of ac353c0ab7de88c105b055635cb7ad773afff680, the squash commit #1553 merged as on
speedkick. It applied to main with no conflicts, and the diff is
byte-identical to the one reviewed on #1553 (checked with git patch-id), so the
review there still stands.

Re-checked on this branch, based on main:

• The calculator's own suite: 476 tests, all pass (python -m unittest from
  tools/sizing, standard library only).
• ruff check and ruff format --check clean repo-wide. Note [tool.ruff] exclude
  in pyproject.toml lists tools, so CI does not lint this directory.
• Server unit suite unchanged from main (1869 passed): this PR is additive and
  touches nothing under packages/.

The body below is #1553's, unchanged.

What this is

A sizing calculator for MemMachine deployments, under tools/sizing/. Give it a design peak in
operations per second and it returns the hardware a deployment needs: API servers, vector-store
machines and their memory size, a PostgreSQL server, embedding and agent-model GPU cards, hot vector
memory and disk for a chosen retention period, the max_connections PostgreSQL will need, the
network peaks, and how many callers that capacity holds.

Why it exists

Capacity questions about MemMachine were being answered in prose, and prose cannot be re-run. When
someone asks "what if we keep episodes for a year instead of ninety days", or "what if a tenth of
searches use agent mode instead of one in a hundred", the honest answer is a different hardware
order, not a paragraph. This puts the model in one file so the answer can be recomputed instead of
re-argued, and so every assumption behind it is visible.

Three properties matter more than the arithmetic:

• Every number is labelled measured, derived, estimate or assumption. A reader can see at a
  glance which figures rest on a benchmark and which rest on a guess that has never been tested.
• Every input is a knob, on the command line and on the web form, so nobody has to edit code to
  ask a different question.
• It states what it does not know. The embedding-card rate has never been benchmarked. The
  traffic mix is a planning assumption nobody has measured. The tool says so where it uses them,
  rather than presenting a confident total.

Usage

It needs no dependencies — Python standard library only.

cd tools/sizing
uv run --no-project python memmachine_sizing.py --help

Re-price an order against a different traffic mix:

uv run --no-project python memmachine_sizing.py tier target --agent 2 --plain 53

Size for a mixed population, where each kind of caller sends a different mix:

uv run --no-project python memmachine_sizing.py users --humans 2500 --automated 75 \
  --human-mix 90/9/1 --automated-mix 10/20/70

Two things that sound alike and are not

The README leads with this, because confusing them sizes a deployment wrongly.

Agent-mode search is a property of a request — the agent_mode flag on a MemMachine search.
A search sent with it fans out into a multi-hop retrieval of roughly 22 embedding calls, 22 vector
searches, 44 database reads and one or two language-model calls. It is the third share of the
traffic mix, set with --agent. It is a cost multiplier: how expensive one request is.

An automated client is a property of a caller — a program sending requests in a loop rather than
a person typing. One in a five-second tool loop is assumed to send about 0.4 operations per second,
where a human chat session sends 0.011 to 0.028. It is a population count on users, set with
--automated. It is a rate multiplier: how fast requests arrive.

They are independent, so each population carries its own traffic mix and the calculator blends them.

Where the numbers come from

The one measured anchor is 180 searches per second per 16-vCPU AMD EPYC server at 8 worker
processes, from a benchmark on 30 August 2026 with a real OpenAI embedder, a 12,000-episode corpus
and the rrf-hybrid reranker enabled — so the reranker's cost is already inside every derived server
count. Everything else is derived from it, estimated, or an assumption, and the README lists all of
them with their defaults.

What it deliberately does not do

It does not price high-availability additions — a second copy of every vector, a PostgreSQL standby
or a second gateway are a separate decision, and it says so rather than guessing.

Testing

382 tests, standard-library unittest, run with uv run --no-project python -m unittest from
tools/sizing. They cover the arithmetic at exact machine boundaries, every command-line
subcommand, the web form driven end to end, and rejection of bad input on every path. ruff check tools/sizing is clean.