How Memtrace runs
One binary, three moving parts: the MemDB storage sidecar, the workspace runtime on :3030, and the Cortex decision-memory sidecars — plus how a second MCP client attaches instead of duplicating the stack.
Everything ships in a single memtrace binary, but a running workspace is made of a few cooperating processes. Understanding the shape of them explains why a second agent connecting doesn't spawn a second daemon, why the dashboard and the MCP tools see the same graph, and what each process depends on.
One binary, several processes#
memtrace start is the process that owns a workspace. It boots a local MemDB storage engine — by default as a separate memcore-server sidecar process, reached over a loopback gRPC connection on 127.0.0.1:50051 — then serves a REST/WebSocket API and the dashboard UI on 127.0.0.1:3030, bound to loopback only unless you explicitly set MEMTRACE_UI_HOST to expose it. That same :3030 server is also where MCP-over-HTTP lives when a client asks for it.
Alongside the UI server, memtrace start spawns two more sidecars in the background: memcortex-daemon (the Cortex ingest loop) and memcortex-mcp (a tool server exposing Cortex's five decision-memory tools over stdio). Both are fail-safe — if the sidecar binary is missing or the bootstrap doesn't succeed, Cortex simply doesn't appear; it never blocks or crashes the core runtime.
memcortex-mcp is spawned as a plain child process and is not proxied or bridged into memtrace mcp's tools/list, and none of the installer's client transformers (Claude Code, Cursor, Codex, etc.) write a separate config entry for it. In this build there is no supported way for an external agent to attach to it and call the five tools (recall_decision, get_arc, verify_intent, why_is_this_here, governing_contracts) directly — the sidecar exists to feed Cortex's ingest pipeline, not to be reached independently. See Cortex for what those tools do and the state of exposing them through memtrace mcp.
Process topology#
One memtrace start owns a workspace at a time. The MemDB sidecar and the Cortex sidecars sit behind it; MCP clients and the browser dashboard are the two ways in.
The Cortex sidecars are fail-safe by construction: every Cortex bootstrap step is gated and degrades with a warning rather than blocking the rest of memtrace start. If memcortex-daemon or memcortex-mcp never comes up, the workspace runtime, the dashboard, and the core MCP tools all keep working normally.
How memtrace mcp attaches#
memtrace mcp is what your IDE or agent actually launches — it's the process every configured client (Claude Code, Cursor, Codex, and the rest) spawns over stdio. It is headless by default (no UI port bound unless you pass --ui or set MEMTRACE_MCP_UI=1), and in its default local mode it does not boot its own database. Instead, it looks for an already-running workspace owner and attaches to it: same MemDB, same data directories, one shared graph.
Concretely, it reads ~/.memtrace/runtime.json to find a workspace owner whose git root matches the current repo and whose process is still alive, then confirms that owner's daemon-state.json answers on its loopback endpoint within 300ms. If it does, the MCP process prints attaching to existing workspace owner pid <N> and proxies straight to that MemDB instance rather than spawning a second memcore-server and a second index of the same repo.
If no owner is found — or if you set MEMTRACE_OWNER_ATTACH=0 to disable this entirely — memtrace mcp falls back to its own env-derived config and, in local mode, pings MEMTRACE_MEMDB_ENDPOINT (default http://127.0.0.1:50051) directly; if nothing answers there it exits rather than silently starting a fresh, disconnected stack. Attachment is repo-scoped: an MCP session opened in a different repository won't adopt a daemon owning some other workspace.
Run memtrace start once per workspace, then point as many MCP clients at it as you like — each new memtrace mcp invocation attaches to the same owner instead of duplicating the index. See memtrace mcp for the full flag and environment-variable reference.
Data locations#
Each workspace keeps its MemDB data in a .memdb directory at the git root (or cwd) by default. Memtrace's own cross-workspace state — the embedding model cache, persisted watch registrations, the runtime owner file — lives under ~/.memtrace. See data directories for the full layout and the environment variables that override each path.
Next: see how the graph itself is structured in the temporal knowledge graph, or how multiple repos share a workspace in workspaces.