Decision Memory First

The Iron Law

BEFORE you assume why code exists, contradict a convention, re-pick a settled
choice, or delete code that "looks unused/weird" → CHECK DECISION MEMORY.

recall_decision(free-text)  →  what did we decide / ban about X?
why_is_this_here(symbol_id) →  what decision put this here?
verify_intent(decision_id)  →  did that decision still hold, or was it violated?
get_arc(decision_id)        →  what episodes implemented it?
governing_contracts(sym_id) →  what constraints bind this symbol?

This is the rationale layer of the codebase. memtrace-first answers what the code is and how it's wired (symbols, calls, git, blast radius). Decision memory answers why it is the way it is, what we already decided, and whether that decision still holds — extracted from real coding conversations and decisions, not the AST.

The graph can tell you a function exists and who calls it. Only decision memory can tell you that three weeks ago you banned the approach you're about to reintroduce.

Full parameter spec for every Memtrace tool: references/mcp-parameters.md (bundled at the memtrace-skills plugin root).

The honesty contract — read this first

These five tools are deterministic, zero-LLM. Every call returns a labeled Verdict / Evidence / CannotProve answer carrying its FactStatus and proof path. No tool ever fabricates an answer.

| Answer | What it means | What you must NOT do | |---|---|---| | Verdict + Evidence (Observed / DeterministicallyDerived / StatisticallyRanked) | A recorded decision/provenance backs this | — | | CannotProve | No recorded decision governs this | Do not read it as "safe / approved / unconstrained." It means unknown, not permitted. Fall back to memtrace-first + asking the user. |

CannotProve is a real, trustworthy answer ("memory has nothing on this"), not a failure and not a green light. Never invent a rationale to fill the gap.

Tool availability (once per session)

These tools are exposed on the normal memtrace MCP server: recall_decision, why_is_this_here, verify_intent, get_arc, and governing_contracts. Hosts do not need a second MemCortex MCP connection. If a tool call returns CannotProve because Cortex is unavailable (for example native Windows without WSL2), say decision memory was unavailable/unknown and continue with memtrace-first; do not fabricate decisions.

The decision rule

| What you're about to do / be asked | Right tool | Procedure | |---|---|---| | "Did we already decide/choose/reject X?" "What's our convention on Y?" | recall_decision("X") | Free-text recall | | "Is there a ban / a 'don't do this' on Z?" | recall_decision("Z") — bans surface as decisions | Free-text recall | | About to edit behavior, re-pick a library/pattern/architecture, or change a subsystem policy | recall_decision FIRST — don't re-litigate a settled call | Free-text recall | | "Why is this code here?" "Why is it done this odd way?" | why_is_this_here(symbol_id) | Symbol provenance | | About to delete/refactor/clean up existing code, especially odd or "dead" code | why_is_this_here + governing_contracts before touching it | Symbol provenance | | "What rules/contracts constrain this symbol?" | governing_contracts(symbol_id) | Symbol contracts | | "Did decision D actually hold, or did we drift?" | verify_intent(decision_id) | Intent verification | | "What commits/episodes implemented decision D?" | get_arc(decision_id) | Implementation arc |

How the tools chain (ids come from recall, not from names)

Only recall_decision takes free text. The other four take numeric node ids (decision_id / symbol_id, uint64). The normal flow is:

recall_decision("auth strategy")
        │  returns ranked hits, decisions first: [{ id, kind: "decision", ... }]
        │  (pick a kind:"decision" hit; conversation hits are context, not chainable)
        ├─► verify_intent(decision_id)   did it hold?
        └─► get_arc(decision_id)         what implemented it?

why_is_this_here(symbol_id)
        │  returns the governing decision lineage for a symbol
        └─► verify_intent(that decision_id)   is that rationale still valid?

symbol_id comes from a prior recall/arc result or the Cortex view — if you only have a name or a free-text question, start with recall_decision. Do not invent ids.

Standard workflows

"Why does this code exist / can I delete it?"

1. If you only have a name/free-text target, recall_decision("<symbol/subsystem>") first.
2. If you have a symbol_id, why_is_this_here(symbol_id) → the governing decision, if any.
3. governing_contracts(symbol_id) → constraints that must survive a rewrite.
4. If a decision governs it → verify_intent(decision_id) to see if it still holds.
5. CannotProve on all checks ≠ safe to delete — confirm with memtrace-impact (blast radius) and the user.

"Should I do X?" (about to make a choice)

1. recall_decision("X") → did we already decide or ban this?
2. If a prior decision exists → verify_intent(decision_id) → is it still in force?
3. Honor a held decision; only revisit a ViolatedAt/superseded one — and say so explicitly

"Did we follow through on decision D?"

1. verify_intent(decision_id) → Held | ViolatedAt | CannotProve
2. get_arc(decision_id) → the episodes that implemented (or should have) it

Red flags — STOP, check decision memory

| Thought | Reality | |---|---| | "This code looks unused, I'll delete it" | why_is_this_here first — a decision may govern it; deletion may reopen a closed issue | | "I'll just edit/refactor this existing behavior" | recall_decision("<behavior/subsystem>") first — the change may violate a recorded decision or ban | | "I'll just use library/pattern X" | recall_decision("X") — you may be undoing a deliberate ban | | "The diff/git log will tell me why" | Git shows what changed, not what was decided or rejected. Decision memory has the rationale and the bans. | | "CannotProve, so it's fine/approved" | CannotProve = unknown, not approved. Don't treat absence of a record as permission. | | "I'll guess the rationale from the code" | Don't fabricate a why. Return what the tool proves, or say it's unknown. |

Skill priority

This is a process skill — it runs alongside memtrace-first before implementation. Use memtrace-first for what/where/impact (code graph); use decision memory for why/whether-it-held (rationale). When both apply, decision memory gates the intent, the code graph gates the mechanics.

Output

The routing outcome: which sibling skill/tool to invoke, and the evidence to quote.

Ask:    "Should I switch to library X?"
Route:  recall_decision("library X")   →  free-text recall
Hit:    { id: 4217, kind: "decision", ... }   (a ban exists)
Next:   verify_intent(4217)            →  intent verification
Quote:  Verdict + Evidence (FactStatus, proof path) — or CannotProve = unknown, not permission