FAQ

Short answers to the questions people actually ask after installing Memtrace — consent-gated setup, Cortex pricing, first-run downloads, workspace sharing, offline behavior, and uninstalling cleanly.

For deeper symptom-by-symptom fixes, see Troubleshooting.

npm install finished but my agents weren't configured — is that a bug?#

No. Touching user config — MCP registration, skills, hooks — is consent-gated. A plain npm install -g memtrace with no consent signal defers setup; nothing is touched, and npm usually hides the postinstall log. Run memtrace setup to review the plan, run memtrace setup --yes to complete setup, or set MEMTRACE_INSTALL_YES=1 before installing to pre-approve it in one pass.

$ memtrace setup --yes
# Completes the consent-gated part of install.
# Run memtrace setup without --yes first if you want to review the plan.

Does memtrace mcp start a second daemon if memtrace start is already running?#

No. It detects the running workspace owner, prints "attaching to existing workspace owner pid N", and connects to the same loopback MemDB instead of spawning a second stack. It also stays headless — no UI port — unless you pass --ui or set MEMTRACE_MCP_UI=1.

Is Cortex (decision memory) a paid feature?#

No — the memcortex capability defaults to active for every plan, universally. The sidecars boot automatically with memtrace start; opt out with MEMTRACE_CORTEX=off. Retrieval is credit-metered the same way other insight tools are.

First start seems stuck after "downloading embedding model" — is it hung?#

No. The first embed call downloads the default jina-code model into ~/.memtrace/fastembed_cache and then runs one-time ONNX Runtime initialization. The terminal prints an explicit first-run notice specifically so this silent stretch isn't mistaken for a hang; subsequent starts skip it entirely and boot warm.

I ran memtrace start in a folder containing several repos — will they share one index?#

Only with your confirmation. A workspace shape — two or more sibling git repos, no .git at the root — triggers a prompt. Sharing one index requires an interactive yes, --bless-workspace, or MEMTRACE_BLESS_WORKSPACE=1, which writes a .memtrace-workspace marker file. Decline and each repo keeps its own database instead. Undo sharing any time with memtrace workspace unbless — no index data is deleted by undoing it.

My machine can't reach memtrace.io right now — will my tools stop working?#

If you're already licensed, no: the server boots in degraded mode, keeps serving tools, and re-validates in the background every 5 minutes. Only a definitive server-side rejection — revoked, invalid, or suspended license, an HTTP 401/403 — refuses to start. Using the same license key on multiple machines is fine too; billing is per query credit, not per seat.

How do I cleanly uninstall?#

Run memtrace uninstall before npm uninstall -g memtrace — npm v7+ never fires preuninstall for global packages, so the shim has to run first. Install wrote a backup manifest of every user-global file it touched, so uninstall can restore or surgically strip exactly what it added: files untouched since install are restored byte-exact, files you've since edited get only their memtrace-owned blocks removed (your edits are kept), and files install created from scratch are deleted.

$ memtrace uninstall
$ npm uninstall -g memtrace

ONNX Runtime failed to load at start — what now?#

That's a host-config issue — a missing libonnxruntime — not a crash. memtrace start fails fast with a platform hint and exits 75. Either install the dylib, or run without embeddings for a structural-only graph (semantic search off, everything else works):

$ MEMTRACE_SKIP_EMBED=1 memtrace start

See Troubleshooting for the full symptom breakdown, including the pre-AVX2 CPU case this error often masks.