Local-first architecture

Indexing, the graph, search, and embeddings all run in-process on your machine. The cloud only handles sign-in, quota sync, and minting a short-lived GitHub token for PR review.

Memtrace is a local-first tool with a small, deliberate cloud surface. Everything that touches your code — indexing, the knowledge graph, search, embeddings — runs in-process on your machine. The cloud is involved in exactly three places, none of which see your code.

What runs locally#

The entire indexing and query path is local: the AST graph lives in MemDB on disk next to your repo, the file watcher re-indexes on save, and every graph algorithm — search, impact analysis, centrality, complexity, temporal history — runs against that local store. Semantic search is backed by an embedding model that runs in-process via ONNX Runtime, not a remote embedding API: the model is downloaded once on first use and cached locally, then every embedding call after that is a local inference call, online or not.

A bring-your-own remote embedding endpoint is also supported (memtrace embed set --remote), and even then a Memtrace auth failure can't interrupt it — local and BYO-remote embedding never depend on the Memtrace session token.

What touches the cloud#

There are exactly three cloud touchpoints, and each is narrow and content-free:

• Device auth. A one-time (per device) browser device-flow sign-in exchanges a license key for a session token, stored locally.
• Heartbeat / quota sync. A background heartbeat syncs graph-size counters and billable query usage against your plan's quota — it never sends code, paths, or query content.
• GitHub App token minting for code review. When you run PR review, the cloud's only role is minting a short-lived GitHub App installation token. Diff analysis, graph lookup, and review ranking all run on your machine — the cloud never sees the diff or the review findings, only issues the token that lets your local process talk to GitHub.

Offline and degraded behavior#

A licensed install is designed to keep working through network trouble. If the cloud is unreachable, or returns a transient error, Memtrace boots in degraded mode: it keeps serving every tool and re-validates in the background roughly every 5 minutes until the connection recovers.

Using the same license key on multiple machines is fine by design — billing is metered by query credits, not by seat, so degraded mode on one machine doesn't interact with any other device's session.

Loopback-only binding#

The dashboard, REST API, and the same-process /mcp endpoint nested inside it bind to 127.0.0.1 by default — nothing on your network can reach them unless you explicitly opt in. The local MemDB gRPC sidecar binds the same way.

$ memtrace start
# UI/API and its same-process /mcp endpoint bind 127.0.0.1:3030 — not reachable from your LAN

$ MEMTRACE_UI_HOST=0.0.0.0 memtrace start
# explicit opt-in to expose beyond loopback

See Telemetry for what the heartbeat and usage streams actually carry, or memtrace code-review for how the GitHub token hand-off works in practice.