Getting started

June 7, 2026 · View on GitHub

This walks you from "nothing installed" to "your agent is using Memtrace's knowledge graph". Should take ~5 minutes on a typical machine.

What you need

  • Node.js 18 or newer — Memtrace ships as an npm package that bundles a Rust binary for your platform.
  • Git — used by the indexer to read your repo's history.
  • At least 8 GB RAM for small/medium projects, 16 GB if you index something the size of Django or Linux. We auto-tune for 16 GB hosts; tighter machines work but expect to set MEMTRACE_TIER=light.
  • 5 GB free disk for caches and on-disk graph state. Bigger repos push that toward 10–15 GB.
  • macOS, Linux, or Windows. Everything works on macOS and Linux natively. Windows is supported with one caveat — see troubleshooting.md.

Install

npm install -g memtrace

This pulls down the appropriate native binary for your OS+arch (macOS arm64, macOS x64, Linux x64/arm64, Windows x64), installs the agent skills the supported AI tools auto-discover, and wires up the MCP integration for Claude Code, Cursor, and the rest.

After install:

memtrace --version    # confirms the install
memtrace --help       # shows the installed CLI command surface

The public command reference lives in cli-reference.md.

memtrace warmup

The first model.embed() call on Apple Silicon triggers a one-time CoreML graph compile for the ANE that takes 60–300 s. If you skip this step and run memtrace start first, that compile happens during the embedding phase — the wait is the same, but the daemon is already holding open ports and a watcher. Running memtrace warmup once after install gets the cache populated outside the daemon lifecycle so every subsequent memtrace start reaches embedding in single-digit seconds.

Linux and Windows operators can skip this step — the cold-start cost on non-Apple-Silicon hosts is small enough that the v0.3.84 first-run detection covers it transparently.

Cargo (build from source)

If you'd rather build from source — for example to enable a non-default feature flag — see the public repo at syncable-dev/memtrace-public. Most users should not need this path.

Updating

memtrace install      # pulls latest from npm + chains into your prior command

memtrace install start upgrades and starts the daemon. memtrace install index . upgrades and re-indexes the current directory.

First run

Pick a project. From its root:

memtrace start

What happens:

  1. License check. Memtrace is freeware but requires a session token. The first time you run it, you'll be walked through a device-flow login (browser opens, you accept, the token caches to ~/.memtrace/). No code or repo data leaves your machine during this — see privacy-and-telemetry.md.
  2. MemDB starts. Memtrace's embedded knowledge-graph database opens its on-disk store at <project>/.memdb/. First-time it creates the directory; subsequent starts open it in milliseconds.
  3. Models warm up. On a fresh machine, the embedding model (~340 MB ONNX) and the cross-encoder reranker (~75 MB int8) get downloaded to ~/.memtrace/ once. After the first machine warm-up this is a cache hit on every subsequent start.
  4. Auto-indexing kicks off. Memtrace walks your repo, parses every supported source file (Python, TypeScript, JavaScript, Rust, Go, Java, Ruby, C, C++, C#), extracts symbols and relationships, and writes them to MemDB. Progress prints to your terminal.
  5. The dashboard goes live. A local UI at http://localhost:3030 shows you what got indexed, lets you explore the graph, and surfaces the value ledger.

For a small repo (mempalace, ~250 files) this completes in under a second. For Django (~3,300 files) it's around 14 seconds. The numbers in performance-tuning.md cover bigger repos.

How start, index, and mcp fit together

These commands are often confused because they all touch the same local graph. The short version:

CommandWhat it is forKeeps running?
memtrace index .Build or refresh the graph for the current repo.No
memtrace startRun the local UI, watcher, PR command loop, and workspace owner in the foreground.Yes
memtrace mcpThe MCP server your agent launches for tool calls. It attaches to an existing owner or becomes the owner if none is running.Yes, for the agent session

You do not need to run both memtrace start and memtrace mcp. Most agents launch memtrace mcp automatically from their MCP config. Run memtrace start when you want the dashboard at http://localhost:3030, live file watching, or PR comment commands running in a visible terminal.

Owning the workspace is not the same as indexing it. If the repo has never been indexed, memtrace mcp can start successfully but graph tools will have little or no project context until you run memtrace index ., run memtrace start and let auto-index finish, or ask an MCP-enabled agent to call index_directory.

If you want Memtrace available without an open browser tab (Orbit, CI, headless servers), start the workspace runtime in headless mode:

memtrace start --headless
# or: MEMTRACE_HEADLESS=1 memtrace start

The HTTP API stays on http://localhost:3030; only the browser auto-open is skipped. For a long-lived background owner without a visible terminal, run memtrace start --headless inside tmux, screen, or your process supervisor of choice.

Note (0.6.10): memtrace service / memtrace daemon install was removed. Most agent workflows only need memtrace mcp, which attaches to an existing owner or becomes the owner for that session.

Working across several related repos (frontend + backend, a monorepo, a service mesh)? Index them under one workspace so they share a single graph and cross-repo questions resolve — see workspaces.md.

Tell your agent to use Memtrace

If you installed via npm, the integrations for the major AI tools are already wired:

  • Claude Code — the MCP server registers automatically. Open a Claude Code session in your project root and the tools are there.
  • Cursor — the per-project MCP config is generated on first run.
  • Codex / Gemini CLI / Windsurf / others — see mcp-and-transports.md for per-tool setup.

To prove it's working, ask the agent something like:

"Where is the function that handles user login?"

A Memtrace-aware agent answers in one round-trip with file:line locations, not by spelunking through 20 file reads. If you see a flurry of Read/Grep/Glob calls instead, the MCP isn't wired — troubleshooting.md.

Verify the install

memtrace status

Prints something like:

  ◆  Memtrace v0.3.32
  ◆  MemDB embedded · data dir = /your/project/.memdb
  ◆  Indexed: 1,234 files · 8,920 symbols · 21,505 edges
  ◆  Models: jina-embeddings-v2-base-code (768d, int8), bge-reranker-base
  ◆  UI: http://localhost:3030

If the file/symbol counts are zero on a non-empty repo, indexing silently failed somewhere — the troubleshooting doc has a checklist.

What gets created on disk

After your first index:

PathWhat it isSurvives reboot?
<project>/.memdb/Knowledge graph + vectors for THIS projectYes
<project>/.memtrace/Job state for the indexer (transient)Yes (small)
~/.memtrace/embed-cache/Embedding cache, keyed by symbol AST hashYes
~/.memtrace/fastembed_cache/Downloaded embedding model filesYes
~/.memtrace/rerank-models/Downloaded cross-encoder reranker filesYes
~/.memtrace/telemetry/Product-telemetry buffer (default on; set MEMTRACE_TELEMETRY=off to disable)Yes

data-directories.md explains each in detail.

Stopping and resetting

memtrace stop                  # stop the running workspace runtime
memtrace reset                 # wipe the local MemDB (ALL repos)
memtrace reset <repoId>        # wipe one repo's data only
memtrace start --clear         # wipe and re-index in one go

Wiping is non-destructive to your source code — reset only deletes graph data and caches, not files in your repo.

Where to next