memtrace cortex

Collect a redacted Cortex support report or reset stale runtime and recall-filter state without wiping durable decision memory.

Usage#

memtrace cortex debug [--output <PATH>] [--json]

memtrace cortex reset --yes

These commands diagnose and recover Cortex decision memory. They are separate from memtrace reset, which clears the MemDB code graph. A Cortex reset never clears .memdb, and a MemDB reset never changes Cortex.

Collect a debug report#

memtrace cortex debug inspects the local Cortex installation and writes a redacted JSON report you can attach to a support issue. The default filename is memtrace-cortex-debug-<timestamp>.json in the current directory; the command prints the exact path when it finishes. It does not stop the runtime, reset a store, or change source files.

Flag	Description
`--output <PATH>`	Write the report to an explicit file instead of the timestamped default path.
`--json`	Print the report itself as JSON on stdout. No default file is created unless `--output` is also supplied.
`--help / -h`	Print Cortex command help without inspecting or changing the store.

The report includes the Memtrace version, operating system and architecture, Cortex process/endpoint health, sidecar metadata, store sizes and modification times, and whether the ingest offset is valid for the captured episode stream. The IPC probe records the failing phase, stable error kind, raw OS error when the operating system supplied one, and transient Windows named-pipe no-data events. The report still completes when Cortex is unavailable.

SAFE TO SHARE WITH MEMTRACE SUPPORT

The report contains metadata, not memory content. It excludes episode lines, decision and document text, governance-file contents, credentials, tokens, and secret environment values. A fixed allowlist of operational settings is reported only as normalized flags, numeric values, or endpoint classes; path overrides are reported by presence, and user-specific paths are redacted.

Reset Cortex runtime state#

memtrace cortex reset --yes writes a redacted report, stops the local Memtrace runtime, and archives only stale socket/start markers plus the learned recall-gate verdicts. It does not wipe the durable Cortex graph or replay cursor. This is the safe recovery path for a stuck sidecar, stale named pipe, or a learned gate that filtered valid decisions.

--YES IS REQUIRED

The command refuses to reset without an explicit --yes. Reset interrupts the local runtime and the Cortex query endpoint stays unavailable until you run memtrace start again.

Phase	What happens
1. Diagnose	Write a redacted pre-reset support report and print its path.
2. Stop	Stop the local Memtrace runtime so macOS, Linux, and Windows release Cortex files safely.
3. Archive	Move only the stale runtime markers, socket artifact, and learned recall-gate verdicts into a timestamped backup.
4. Restart	Run `memtrace start` from the workspace you want to serve, then retry the normal Cortex tools.

Reset does not auto-restart Memtrace because the CLI cannot safely reconstruct every workspace and start flag used by the previous owner. Run it again from the workspace you want to serve, then reconnect or restart the agent's existing memtrace mcp connection.

What reset preserves#

Preserved state	Why it stays
`memcortex/`	The durable decision graph contains lifecycle writes that cannot be reconstructed safely from the episode stream alone.
`.memcortex-governance-inventory.json`	The inventory carries edit, delete, reopen, contract, scope, and logical-clock state for governance decisions.
`ingest.offset`	Reset does not replay an old episode stream over the current graph or change the durable ingest position.
`episodes.ndjson`	Raw capture is retained for audit and normal incremental ingest; reset never edits its contents.
Capture cursors, fingerprints, and ADR hashes	They prevent already-discovered material from being appended to the raw stream again as duplicates.
Governance configuration and source documents	Repo-local `.memtrace/governance.toml`, ADRs, agent rules, and other source files are never changed by the reset.
`.memdb`	The code graph is a separate store and is not part of a Cortex reset.

THIS IS NOT A DESTRUCTIVE FULL REINDEX

The episode stream does not contain every governance edit/delete/reopen or manual-confirmation lifecycle write. Deleting ~/.memtrace/cortex-store can therefore lose or resurrect decisions. The supported reset deliberately preserves the durable graph and lifecycle inventory. If queries are still wrong after restart and reset, attach the generated debug JSON to the issue instead of deleting the store.

Examples#

terminal

$ memtrace cortex debug
# Writes ./memtrace-cortex-debug-<timestamp>.json and prints its path.

$ memtrace cortex debug --output ./cortex-windows-issue.json
# Write the redacted support report to an explicit path.

$ memtrace cortex debug --json
# Print the report as JSON on stdout for a script or CI artifact collector.

$ memtrace cortex reset --yes
# Write a pre-reset report, stop Memtrace, and archive runtime/filter state.

$ memtrace start
# Required after reset: restart Cortex from the workspace you want to serve.

For query setup and the five decision-memory tools, see Cortex decision memory. If the problem is a stale workspace owner, occupied dashboard port, or broken agent registration instead, use memtrace doctor.