memtrace status

A one-shot snapshot of the local runtime: MemDB mode, running daemon, auth health, and graph totals — human-readable on stderr, or structured JSON on stdout.

Usage#

memtrace status [--json] [--workspace <PATH|NAME>] [--debug]

memtrace status prints a snapshot of the local Memtrace runtime: MemDB mode (embedded/local/external), the data directory or endpoint, database name, the running daemon (owner PID + dashboard URL) if one is up, auth-session health, and graph totals — nodes, edges, episodes. If a daemon already owns the workspace, status attaches to it read-only. If none is running, it briefly boots the local backend stack itself just to read the counts, then tears that down again on exit.

NOTE

Human output goes entirely to stderr. Only --json writes to stdout. Piping memtrace status > file without --json captures nothing.

Reading the human output#

Default output is a short block of lines. Here's what each one means:

Line	Meaning
`Mode: local / embedded / external`	Which backend status is inspecting, resolved from MEMTRACE_MEMDB_MODE (or implied by a non-loopback MEMTRACE_MEMDB_ENDPOINT).
`Data dir: … (or MemDB endpoint: …)`	The workspace .memdb directory in local/embedded mode, or the remote gRPC endpoint in external mode.
`Database: memtrace`	MemDB database name (MEMTRACE_MEMDB_DB).
`Owner PID: … / UI: http://localhost:<port>`	Only printed when status successfully attaches to a live daemon for this workspace — the adopted owner PID and its dashboard URL.
`Auth: DEGRADED — <hint>`	Only printed when the auth session is degraded. With a live daemon this comes from GET /api/system/auth-session; otherwise from the local in-process session.
`Connection: … (external mode only)`	The MemDB connection state — prefers the running daemon's own supervisor state (where a Reconnecting{attempts} status lives) over a fresh one-shot probe.
`N nodes - N edges - N episodes`	Three backend count_records calls; a failed count degrades to 0 rather than erroring the whole command.
`Skipped by … (noise filter)`	Only printed when the sum is > 0. Breaks down .memtraceignore and built-in noise-filter skips. Process-lifetime counters on the running daemon — a fresh one-shot status run typically shows zero even if the live daemon skipped plenty during indexing.
No data indexed yet. Run `memtrace index <path>`…	Printed instead of the usual closing hint when the node count is 0.

--json#

--json prints a structured payload to stdout instead of the stderr summary — meant for CI and jq. Shape:

terminal

{
  "memdb": { "mode": "local", "endpoint": "...", "database": "memtrace" },
  "graph": { "nodes": 0, "edges": 0, "episodes": 0 },
  "auth_session": { "degraded": false, "hint": null, "banner": null },
  "phase2": { "per_repo": {} },
  "noise_filter": {
    "walker_skipped_by_default_ignore": 0,
    "walker_skipped_by_user_memtraceignore": 0,
    "scanner_skipped_by_gate": 0
  },
  "recovery": { "...": "static guidance mapping symptoms to fix commands" }
}

In external mode the payload also gains memdb.seat_principal, memdb.user_org_id, memdb.connection, and memdb.connection_source ("daemon" or "status-probe"). On a failure to reach MemDB, JSON mode prints { error, auth_session, recovery } (plus a connection object in external mode) instead of the full payload — but the process still exits 0.

The noise_filter object counts files skipped by the walker's ignore layers — see .memtraceignore for what each field means and how to tune what gets indexed.

The recovery object is static guidance cross-referenced with memtrace doctor: it maps symptoms to memtrace auth login, memtrace doctor --fix, memtrace doctor --fix --repair-install, and memtrace doctor --fix --purge-legacy.

Flags#

Flag	Description
`--json`	Print the structured JSON payload to stdout instead of the human summary on stderr. Detected anywhere in argv.
`--workspace <PATH\|NAME>`	Global flag status honors: hard-overrides which workspace's `.memdb` it reports on. The PATH form creates the directory if missing and writes a workspace marker file there (a real side effect); the NAME form resolves a Named Workspace from the `~/.memtrace/workspaces` registry.
`--debug`	Raises CLI log verbosity for this run. Equivalent to MEMTRACE_DEBUG=1.
`--help, -h`	Print the status usage text and exit before any dispatch or side effect.

Environment variables#

Variable	Default	Description
`MEMTRACE_MEMDB_MODE`	`local`	Which backend status inspects: `embedded` (in-process engine), `local` (memcore-server sidecar), or `external` (remote MemDB gRPC client). Changes both the printed lines and which extra sections (seat, connection) appear. An explicit value always wins; a non-loopback `MEMTRACE_MEMDB_ENDPOINT` otherwise implies external.
`MEMTRACE_MEMDB_ENDPOINT`	`loopback memcore-server endpoint`	MemDB gRPC endpoint. A non-loopback value flips the resolved mode to external unless MEMTRACE_MEMDB_MODE overrides.
`MEMTRACE_MEMDB_DB`	`memtrace`	Database name shown on the Database line and in JSON memdb.database.
`MEMTRACE_MEMDB_DATA_DIR`	`<git-root>/.memdb (or <cwd>/.memdb outside a repo)`	Workspace-local MemDB data directory. Status reads `daemon.pid` and `daemon-state.json` from here to find a running daemon, and prints it as the Data dir in local/embedded mode.
`MEMTRACE_OWNER_ATTACH`	`enabled`	Set to `0`/`false`/`off` to skip attaching to a running daemon — status then boots its own backend view instead of adopting the owner's endpoint/UI port.
`MEMTRACE_MEMDB_LOOPBACK_PORT`	`50051`	Loopback port for the memcore-server sidecar when status has to boot the local stack itself (no running daemon, local mode).
`MEMTRACE_MEMDB_SIDECAR_STARTUP_SECS`	`60`	How long the temporary sidecar boot waits for memcore-server to become ready before failing.
`MEMTRACE_OWNER_TAKEOVER_SECS`	`12`	Grace window status waits for a contended daemon.pid flock to settle before reporting a 'wedged daemon' error.
`MEMTRACE_DEBUG`	`off`	Truthy value raises CLI log verbosity for the status run (same as --debug).

Gotchas#

NOT A ZERO-SIDE-EFFECT PROBE

When no daemon is running in local mode (the default), status may briefly start a temporary loopback MemDB probe, create the .memdb dir if missing, and write short-lived owner state while it checks health. The temporary process is torn down on exit, but filesystem side effects can happen in between.

EXIT CODE IS ALWAYS 0

Even when MemDB is unreachable, status exits 0. Scripts must inspect the output — the error key in JSON, or the "Cannot reach MemDB" line on stderr — not the exit status.

EMBEDDING STATUS IS JSON-ONLY, AND OFTEN EMPTY

Phase 2 embedding detail appears in --json's phase2.per_repo. In a one-shot CLI run that map is often empty; it is most useful when the long-running daemon is the process rendering status. For quick checks, auth_session.degraded is usually the more useful health signal.

EXTERNAL VS. LOCAL NEVER MIXES

A status run configured for external mode ignores a local-mode daemon's state file, and vice versa — the attach-compatible gate keeps the two worlds separate even if both happen to be running.

A foreign memcore-server already listening on the loopback port gets silently adopted for the counts in a no-daemon status run, and is never killed on exit. A wedged process holding the daemon.pid flock without serving blocks status for the takeover grace window (default 12s, MEMTRACE_OWNER_TAKEOVER_SECS) before it reports failure.

Examples#

terminal

$ memtrace status
Mode: local
Data dir: /Users/you/code/myrepo/.memdb
Database: memtrace
Owner PID: 41213
UI: http://localhost:3030
128 nodes - 342 edges - 19 episodes

$ memtrace status --json
# Structured JSON on stdout for CI: {memdb, graph, auth_session, phase2, noise_filter, recovery}

$ memtrace status --json | jq '.graph'
# Extract node/edge/episode counts.

$ memtrace status --json | jq '.auth_session.degraded'
# true = needs `memtrace auth login`.

$ memtrace status --workspace ~/code/monorepo
# Report on a specific workspace's .memdb instead of the cwd-resolved one.