| name | memtrace-provenance |
| description | Retrieve the governing decision lineage (why is this here) and contracts that bind a symbol from Cortex decision memory through the normal Memtrace MCP server. Use before deleting, rewriting, refactoring, or 'cleaning up' existing code that looks unused, odd, redundant, legacy, or policy-sensitive, and when the user asks why a symbol exists or what rules constrain it. Symbol-scoped; for free-text decision search use memtrace-decision-recall first. Do not infer intent from the diff or assume unfamiliar code is safe to remove. |
Overview
Provenance answers "why is this code here, and what binds it?" before you change
it. why_is_this_here returns the decision/conversation lineage that governs a symbol
(its Governs/Produced provenance); governing_contracts returns the contract nodes
that constrain it. Together they stop you from deleting code that closes a past issue
or violating an invariant nothing in the AST advertises.
Full parameter spec for every Memtrace tool: references/mcp-parameters.md (bundled at the memtrace-skills plugin root).
Quick Reference
| Tool | Purpose | Returns / FactStatus |
|---|
why_is_this_here | The governing decision/conversation lineage of a symbol | DeterministicallyDerived | CannotProve |
governing_contracts | The contract nodes that constrain a symbol | Contract nodes | CannotProve |
verify_intent | Given a returned governing decision_id — is that rationale still valid? | Held | ViolatedAt | CannotProve |
why_is_this_here and governing_contracts each take a symbol_id (uint64 node
id), not a name. verify_intent takes a decision_id (uint64), not a symbol_id.
If you only have a name or a question, start with recall_decision (free text) — see
memtrace-decision-recall. ids come from a prior recall/arc result or the Cortex
view. Do not invent ids.
Honesty contract: for a symbol no decision produced, why_is_this_here returns an
honest CannotProve; governing_contracts returns CannotProve rather than a false
"no contracts" verdict. CannotProve ≠ safe to delete / unconstrained — it means
unknown, so fall back to blast-radius and the user.
Steps
1. Get the symbol_id
If you have a name or a "why" question, run recall_decision(...) first and take the
symbol_id from the result if present, or use the id returned by a graph/Cortex view.
The id-based tools need a numeric id. If you cannot get a symbol id, do not skip
decision memory entirely: use recall_decision("<symbol/subsystem/behavior>") and
report any matching decision/bans before changing the code.
2. Ask why it's here
why_is_this_here(symbol_id) → the governing decision lineage. This is the rationale
the git blame won't give you: the decision that produced this code and, often, the
problem it was put there to solve.
3. Ask what constrains it
governing_contracts(symbol_id) → contracts that must survive any rewrite (invariants,
interface promises, "must always …" rules). A refactor that breaks one of these is a
regression even if every test passes.
4. Check the rationale still holds
If why_is_this_here returns a governing decision_id, run verify_intent(decision_id)
(see memtrace-intent-verification) — a ViolatedAt verdict (or a decision you can see
was superseded via recall_decision) changes whether the code should still look this way.
Decision Points
| Situation | Action |
|---|
| Code looks unused/dead and you want to delete it | why_is_this_here + governing_contracts BEFORE deleting; CannotProve is not a green light |
| Code is written in a strange/non-obvious way | why_is_this_here if you have a symbol id; otherwise recall_decision for the symbol/subsystem |
| About to refactor a symbol's internals | why_is_this_here + governing_contracts — preserve the rationale and every constraint, not just the test surface |
| User asks "why is this here?" | why_is_this_here(symbol_id); if you only have a name, recall_decision first |
| All provenance returns CannotProve | Treat as unknown; combine with memtrace-impact (blast radius) and ask the user before removing |
Output
why_is_this_here(symbol_id: 4821)
→ DeterministicallyDerived — governing lineage:
decision_id 913 (Governs): "Keep retry shim until legacy clients migrate"
governing_contracts(symbol_id: 4821)
→ contract node: "writes must always be debounced" (must survive any rewrite)
— no decision produced the symbol → CannotProve (unknown, NOT unconstrained)
verify_intent(decision_id) on a returned lineage id yields Held | ViolatedAt | CannotProve.
