Getting started

Install Memtrace, boot the workspace runtime, connect your coding agent, sign in, and get your first real answer from your codebase — start to finish in one pass.

Memtrace is a local knowledge graph of your codebase that your coding agent queries over MCP instead of grepping. This page is the whole path: install, first run, connect an agent, sign in, and get a real answer back — in that order, with nothing skipped.

The five-minute path#

1. 1
   Install the npm package

   Memtrace ships as a single npm package, memtrace, with prebuilt platform binaries. Install it globally.

   terminalCOPY

   $ npm install -g memtrace
   

   Postinstall always does the safe local setup: it selects the right platform package, prepares the bundled runtime, and (on Windows NVIDIA hosts) can fetch the CUDA execution provider. npm hides lifecycle output by default, so a normal install may only show npm's package summary. It does not touch your agent configuration yet — see the callout below.

   CONSENT GATE

   A plain npm install -g memtrace never edits your agent config, skills, or hooks on its own, and it usually does not print the deferred setup plan because npm suppresses postinstall logs. Run memtrace setup to review the planned changes interactively, run memtrace setup --yes to apply them, or set MEMTRACE_INSTALL_YES=1 before installing to pre-approve setup during install. Every consent-approved setup snapshots the files it's about to mutate first, so memtrace uninstall can restore them byte-for-byte.

2. 2
   First run: memtrace start

   From your repository root, boot the runtime.

   terminalCOPY

   $ cd <your-repo>
   $ memtrace start
   

   On a clean machine this single command signs you in, boots the local database, opens the dashboard, and starts indexing — see the boot order below for exactly what happens and when. The first embed download can take a while; the terminal prints an explicit "downloading embedding model" notice so the quiet stretch doesn't look like a hang. On RAM-constrained or CI hosts you can skip local ONNX entirely — point at OpenAI, Voyage, or a self-hosted Ollama server with remote embedding.

3. 3
   Connect your coding agent

   memtrace start hints at this automatically if it can't find an MCP config for your workspace. To wire up an agent explicitly, run one of the following — not both:

   terminalCOPY

   $ memtrace setup --yes
   

   This registers Memtrace globally, with nine agent clients — Claude Code, Cursor, Codex, Gemini CLI, Windsurf, VS Code, Hermes, OpenCode, and Kiro — all with the same shape: command: memtrace, args: ["mcp"], no environment variables required. Interactive terminals show an agent picker; pass --only <agent> to target one client instead of all nine.

   If you'd rather scope config to just the current project instead of your home directory, use the bundled installer's --local flag directly:

   terminalCOPY

   $ npx -y memtrace-skills@latest install --local
   

   If memtrace start already owns your workspace, an agent launching memtrace mcp attaches to that running owner instead of starting a second daemon — it prints "attaching to existing workspace owner pid N" and shares the same local database.

   

4. 4
   Sign in

   The first memtrace start runs a browser device-flow sign-in inline, automatically — you don't need to run this yourself unless you're setting up a second machine or a headless box.

   terminalCOPY

   $ memtrace auth login
   $ memtrace auth logout
   

   The CLI prints an always-visible Claim URL and opens your browser; a waiting-room screen keeps that URL in its own block the whole time (press o to reopen it). On a headless shell with no display, it falls back to plain polling with a copy-paste URL. Once claimed, your license key is exchanged for a session and saved to ~/.config/memtrace/credentials.json.

   An account is required — Memtrace refuses to run fully anonymous — but once you're licensed, network blips don't lock you out: a transient failure to reach memtrace.io boots the server in degraded mode, still serving every tool, and re-validates in the background every five minutes. Only a definitive revoked/invalid/suspended response stops it. The same license key works on every machine you use — billing is by query credit, not by seat.

   

5. 5
   Get first value

   Indexing is automatic — memtrace start runs a two-phase bootstrap for every repo it finds (structural index first, embeddings and history second) — but you can also drive it directly, and check in on it:

   terminalCOPY

   $ memtrace index .
   $ memtrace status
   $ memtrace insight-card
   

   After the first successful index of a repo, a Codebase Insight Card prints in the terminal: a curated three-line summary built from Memtrace's own graph algorithms — the hottest central symbol (with its caller count and when it was last edited), likely dead code, and a critical bridge symbol. (If the graph doesn't have enough data for those three, it falls back to a "modules detected" line instead.) Re-render it any time with memtrace insight-card. From here the file watcher keeps the graph live on every save, and your agent can ask for a same-day summary through the daily briefing tool.

   

What start actually boots#

memtrace start does a lot in one command. Here's the condensed order, gate by gate — useful when something looks stuck and you want to know which stage it's in.

A few things worth knowing about this order: the browser only auto-opens on a fresh boot — if a healthy daemon already owns the workspace, memtrace start just prints the existing URL and returns, no second daemon and no new tab (--force replaces the owner). Cortex decision memory is universal on every plan now, so its sidecars bootstrap in the background by default; any Cortex failure degrades with a warning and never blocks the rest of the stack. And if you run memtrace start from a folder containing several sibling repos, sharing one index across them is confirmation-gated — you'll get an interactive prompt (or set MEMTRACE_BLESS_WORKSPACE=1) before anything is combined.

Where to go next#