Architecture
Performance
Vyre runs all day on your own machines, so idle must cost almost nothing. The budgets are principle 8 of the Specification ("Light by default"). A change that breaks one is a bug, like a failing test. This page lists the budgets, how to check them, and what was measured.
The budgets
| What | Budget |
|---|---|
| vyred idle | under 0.9% of one core (p95) and under 1.8% sustained; under 60 MB of heap after a full GC; no polling faster than once a minute when nothing is happening. Resident size is reported, and gates (150 MB settled, 200 MB at startup) only on the Node the box ships |
| Lumen hidden | under 0.2% CPU, no GPU use, under 250 MB resident for all its processes |
| Lumen shown and idle | under 2% CPU; wakes in under 100 ms |
| Vyre app web build in a background tab | no timers faster than a minute; the event stream only |
| Heavy work (indexing, embedding, curation) | low priority, yields, pauses on battery and when you are active, never blocks a hook or Lumen |
| Memory that grows with the corpus | bounded and measured |
Check vyred with scripts/perf-check
npm run perf-check # or: node scripts/perf-check
It takes about 65 seconds and exits 0 when every budget holds, 1 when one breaks. CI runs it
after npm test (.github/workflows/test.yml), and scripts/release-check.sh runs it unless you
pass --skip-perf.
What it does:
- Makes a throwaway
VYRE_HOME(never your real~/.vyre) and seeds it with the fixture corpus plus a synthetic corpus of about 20,000 turns, so Recall has real work. - Starts a real vyred as a child process at lower priority (
os.setPriority, best effort), with a timer hook (scripts/lib/timer-hook.mjs) that records everysetIntervalandsetTimeoutthe process registers, including inside modules. - Waits for the startup indexing pass to finish, then samples CPU and resident memory every 1.5 seconds for 60 seconds of true idle: no requests.
- Deletes the temp home and stops vyred, pass or fail.
What it gates on:
| Check | Budget |
|---|---|
| CPU, p95 of the samples | under 0.9% |
| CPU, sustained: the highest mean over any 5 consecutive samples (7.5 s) | under 1.8% |
Heap used after a full GC at the end of the idle window (scripts/lib/gc-hook.mjs, on every Node) | under 60 MB |
| RSS, settled: the highest of the last 8 samples, once they sit within 3 MB (the window runs on to 120 s until they do), on the Node the box ships | under 150 MB |
| RSS, startup peak: the highest in the first 30 s from spawn, indexing included, on the Node the box ships | under 200 MB |
Fastest recurring timer (a setInterval, or a setTimeout seen 3 or more times) | 60 s or slower |
Mean and max CPU, mean and max RSS, and RSS after the GC are printed but do not gate. After the
startup indexing pass V8 keeps its heap (about 160 MB on the synthetic corpus) for some 20 s before
it gives it back and settles near 90 MB, so the idle budget reads the settled size and the startup
peak has its own budget. That holds on Node 22, the Node in box/Dockerfile. Node 24 does not give
the heap back while idle: the same commit settles at 186 to 260 MB with 74 to 111 MB of heap in
use that a GC would free, and only about 20 MB live. So the RSS budgets gate on the Node major the
box image ships and print as informational on any other, and the heap after a forced GC gates
everywhere, so a real leak still fails on every Node. The output also prints the host's load average,
so you can tell contention from a regression.
Why Why p95 and a sustained window, not the maximum?
One noisy ps sample on a busy machine should not fail the run. An earlier version gated on
the maximum and failed on a single sample out of 40 while the mean was under 0.25%. The
sustained check still catches a loop that costs 1 to 2% the whole minute, which p95 alone
could miss.
The check turns off recall.vectors in its temp config. The embedding model downloads weights
on first use and then works in the background for minutes on a large backlog, which does not fit
a one-minute idle check and needs the network. Embedding cost is not covered by perf-check.
Measured
All numbers are from the first audit, 26 Sep 2026, on a shared macOS development machine.
vyred idle (perf-check)
On a host with load average 23.6 to 26.2 (other test suites running):
| Metric | Result | Budget then |
|---|---|---|
| CPU p95 | 0.00% | under 0.5% |
| CPU sustained | 0.13% | under 1% |
| RSS mean | 55.6 MB | under 150 MB |
| RSS max | 100.8 MB | under 150 MB |
| Fastest recurring timer | none under 60 s | 60 s or slower |
An earlier run gated on raw max CPU and failed on a single sample out of 40 (0.7 to 2.7%, and 8.58% at load average 22 to 26) while the mean was 0.08 to 0.23%. That was host contention.
What the audit changed
| Where | Found | Now |
|---|---|---|
core/watchers/index.js | the scheduler ticked every 15 s | TICK_MS is 60 s |
core/recall/dense.js | the vector index had no cap: 1,553 bytes a chunk, about 57 to 59 MB at 37,000 to 40,000 chunks | maxChunks, default 50,000 (about 78 MB), evicting the oldest sessions first |
core/recall/index.js | a transcript scan every 5 minutes | kept: a stat-only pass over 600 sessions costs 8 to 70 ms |
core/memory/index.js | suspected re-derive on every event | already debounced (SETTLE_MS 250 ms) and coalesced; about 2 s per 100,000 turns |
core/computers/index.js | a sweep every 5 s whether or not a computer was in use | sweeps every sweepMs (5 s) only while something is checked out or waiting to freeze, else every idleSweepMs (60 s) |
The switchboard, gate, vault, learn and system modules and the Harness are driven by events
and hooks. The event stream's 15-second heartbeat runs only while a client is connected.
Since the audit, Recall also indexes one session about 1.5 s after a turn ends
(turn.completed or thread.started), so Chat can follow a terminal session. That work is
driven by events and does nothing while no session is running. The numbers above predate
it.
Lumen
These numbers are for the Electron Lumen, since retired. The native Lumen
(local/capsule/native) is measured in CI by scripts/capsule-native-check.mjs, against
budgets of under 60 MB resident and under 0.1% CPU while hidden, and a wake under 50 ms.
| Measure | Result | Budget |
|---|---|---|
| Hidden RSS, all processes | 212 to 233 MB (238 MB with the hotkey helper) | under 250 MB |
| Hidden CPU, main process, vyred up | 0.061% | under 0.2% |
| Hidden CPU, main process, vyred down | 0.210% overall, settling near 0.18% after about 90 s | under 0.2% |
Warm wake, show() to painted frame | mean 38.0 ms (34.5 to 39.6 ms, 5 samples) | under 100 ms |
| Warm open, end to end | 18 to 50 ms | under 100 ms |
Before the fixes, hidden RSS was 301 to 324 MB (the network service and GPU now run in the main process, with no spare renderer), and hidden CPU with vyred down was 0.791% (a health check every 3 s and a stream reconnect every 1.5 s, now backed off to 60 s and 30 s while hidden). The clipboard watcher (a Swift helper, polling the pasteboard every 750 ms) measured 0.016%.
Wake timing leaves out the hotkey's own double-tap window (about 450 ms, by design) and the first show after launch (about 721 ms).
The app and Glass
apps/app/screens/glass/state.tslets go of the screen when the tab is hidden, keeping the last frame, and asks for a fresh ticket when the tab is visible again.core/glass/has no timers.core/computers/glass.jssends a 30-second keepalive per open viewer, which exists only while someone is watching.apps/app/screens/onboarding/SetupScreen.tsxpolls every 3 s while you wait on a step. That is a foreground wizard you are looking at, so it is outside the background-tab budget.
Not measured yet
- Embedding and curation CPU, and pausing on battery.
- A quiet, dedicated CI runner baseline for perf-check.
- Lumen's hidden CPU budget covers all its processes together; the numbers above are per process.
Where to go next
- Specification: principle 8 and the rest of the rules.
- Testing: the test suite perf-check runs beside.