Cortex decision memory
Cortex remembers WHY: decisions, bans, and contracts, recalled and verified through five tools served by an independent sidecar — active by default on every plan.
Cortex is Memtrace's decision memory: it remembers why code looks the way it does — the decisions, bans, and conventions behind it — separately from the code graph that tracks what the code is. It's active on every plan by default; there's no dev flag or cloud grant standing between you and it.
Overview#
Where the main graph answers "what calls this?" or "what changed?", Cortex answers "was this decided on purpose?", "did that decision hold?", and "what governs this symbol?". It surfaces decisions captured from your episode history, not from re-reading source at query time — so recall is fast and the provenance trail is explicit.
The five decision-memory tools#
| Tool | Purpose |
|---|---|
recall_decision | Free-text ranked decision recall over the Decision/Conversation lanes. An empty or unknown query returns an honest CannotProve rather than a fabricated answer. |
verify_intent | Did a decision hold across its arc? Returns Held, ViolatedAt, or CannotProve. |
get_arc | The episodic arc implementing a decision — the episodes reachable by Produced/DerivedFrom edges, or CannotProve when there is no visible implementing episode. |
why_is_this_here | The governing decision/conversation lineage of a symbol — its Governs/Produced provenance. |
governing_contracts | The Contract nodes that constrain a symbol, or an honest CannotProve when none apply. |
verify_intent and get_arc both take a decision_id — the id returned by recall_decision — not a symbol name. Recall a decision first, then verify or trace its arc using the id it gives back. Passing a symbol name where a decision_id is expected is a common misuse.
Recall is scoped to your current workspace root, so decisions from an unrelated repository never bleed into results.
Sidecar architecture#
When Cortex is active, memtrace start spawns two independent sidecar processes as part of its boot sequence, after the dashboard's UI server is up: memcortex-daemon, which runs the ingest loop that captures decisions as they happen, and memcortex-mcp, which runs its own stdio MCP server exposing the five tools above. memtrace mcp does not spawn these sidecars itself — it only reaches Cortex's tools when it attaches to an already-running memtrace start daemon that spawned them. Running memtrace mcp standalone, with no memtrace start daemon already running, does not start Cortex.
The five Cortex tools are not registered inside memtrace's own MCP tool router — they are served by the memcortex-mcp sidecar's independent MCP server, which gets wired up alongside memtrace's when Cortex is active. An agent connects to it as a separate MCP server, not as an extension of memtrace's tools/list. If the sidecar binary is missing, the five tools simply don't appear anywhere — the rest of Memtrace keeps working normally.
This split is deliberate: a sidecar crash or missing binary degrades gracefully to a warning instead of taking down the core MCP server, and the ingest loop can capture decisions independently of whatever an agent happens to be querying at the time.
Aletheia: the decision-quality gate#
Distinguishing a real engineering decision from ordinary conversational noise is the hard part of decision memory — and it's the part Cortex doesn't outsource to a prompt. Aletheia is Memtrace's own fine-tuned classifier: a small encoder model trained specifically to score whether a captured candidate is a decision worth remembering, run entirely on your machine.
Capture is deliberately generous — the ingest loop favors recall over precision, so it captures more candidates than are really decisions. Aletheia is what cleans that up. During memcortex-daemon's idle consolidation pass (the dashboard's dreaming panel shows this running), it scores every freshly-captured candidate and demotes the ones that don't clear the bar — before they're ever visible to recall_decision or any other tool. It never touches the five decision-memory tools' ranking directly; it only decides what makes it into the store in the first place.
| Spec | Detail |
|---|---|
| Architecture | Fine-tuned microsoft/deberta-v3-large (435M params), full fine-tune |
| Runs | Fully on-device — no network call, no cloud inference |
| Footprint | INT8 ONNX, ~642 MB on disk, ~1.2 GB resident in memory |
| Ships to | ~/.memtrace/models/aletheia-1.5/ |
| Trained on | 24,895 multi-judge-labeled examples — commit subjects and real turns from AI-coding sessions |
| Held-out accuracy | 0.933 conversational AUC |
Governance-sourced decisions — anything ingested via memtrace govern from an ADR or standing rule — skip this gate entirely. Those were deliberately authored as rules, not organic conversation; they're not the kind of noise Aletheia exists to catch.
If the model can't load for any reason, Cortex doesn't silently drop the candidate — it keeps it. A missing or failed classifier degrades to more permissive behavior, never to data loss.
Universal by default#
Cortex defaults to active on every plan — community included. There's no dev flag, no cloud entitlement grant, and no paywall bit standing in front of it; a cloud heartbeat can still adjust an optional decision-count cap (uncapped when unset), and usage is metered per retrieval, but the capability itself is not gated.
| Variable | Default | Description |
|---|---|---|
MEMTRACE_CORTEX | — | Local opt-out. Set to off to disable Cortex entirely for this machine — the sidecars won't spawn and the five tools won't appear. This is the only lever that turns Cortex off; the persisted opt-out also survives in ~/.memtrace/cortex.json. |
Governance intake#
Governance intake is in beta.
Governance intake points Memtrace at ADRs, standing rules, and agent-rule files so Cortex can classify and ingest them as governing decisions. The non-interactive entry point is memtrace govern:
$ memtrace govern docs/adr # sweep a directory recursively for *.md/*.mdc plus .cursorrules/.windsurfrules $ memtrace govern docs/adr/0007-use-postgres.md # classify a single file $ memtrace govern 'docs/**/*.md' --exclude drafts,archive # classify a glob, dropping any path containing "drafts" or "archive"
memtrace govern is read-only and non-interactive — safe to run in CI. It classifies through Cortex's real classification oracle over its Unix socket, so the preview it prints never diverges from what would actually be ingested. This sweep form never writes a confirmation on its own; the interactive review and confirm step lives in the dashboard's Cortex tab, Governance sub-view (open localhost:3030 and switch to the Cortex tab). There is no separate standalone governance server or UI — the review screen lives inside the main dashboard.
memtrace govern requires the Cortex sidecar to be running — start it with memtrace start first. Without it, the command reports that it cannot classify accurately rather than falling back to a lower-quality local guess.
For a doc the classifier misses, gets wrong, or that lives outside the zero-config sweep entirely, memtrace govern add/edit bypasses classification altogether and directly asserts a doc's governance category, guidance, and scope — see the govern CLI reference for the full flag set. The Governance sub-view mirrors this: above its review/confirm table is a collapsible "+ Add or edit a governance doc manually" form with the same fields (path, category, guidance, scope, ban), for making the same manual assertion without leaving the dashboard.
From episode to recall#
Cortex tab (dashboard)#
The Cortex tab in the :3030 dashboard is a dedicated decision-memory workspace, distinct from the Explorer's code/git graph. It renders a decision stream, a decision detail view, a timeline, a dedicated Cortex graph, a diff view, a dreaming panel, and a cap banner, backed by its own 3D scene — plus the Governance sub-view described above.
Cortex vs. Graph
The dashboard's topbar has a Cortex toggle that's separate from the Graph/Explorer view: Graph is code and git history; Cortex is decision memory. They're two different lenses over the same underlying work.