> ## Documentation Index
> Fetch the complete documentation index at: https://engramviz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnose a memory incident

> Move from a bad answer to an evidence-backed diagnosis, controlled repair, and regression test.

Engram models a bad memory-dependent answer as a versioned `MemoryIncident`. The incident is built from
an immutable checkpoint and a replayable `TurnRecord`; it does not mutate the original session.

## Workflow

1. **Observe:** reconstruct memory state, retrieval candidates, selection, active context, and answer.
2. **Diagnose:** identify the earliest recorded stage that failed or mark the explanation indeterminate.
3. **Intervene:** change one explicit memory or policy decision on an isolated branch.
4. **Replay:** reproduce the baseline, rerun the supported stages, and inspect the first branch divergence.
5. **Prove:** export semantic lifecycle and answer assertions as an `engram.memory-regression` matrix.

## Evidence Provenance

* `observed`: explicitly present in a native event or recorded model output.
* `mapped`: translated from a recognized provider/tool operation by an adapter.
* `derived`: deterministically computed from recorded evidence.
* `inferred`: a low-confidence interpretation that is not directly established.
* `simulated`: produced by a controlled replay or counterfactual experiment.
* `unavailable`: the trace did not instrument this stage; absence is not treated as failure.

## Entry Paths

* Promote a replayable answer from the current Engram session and provide the expected answer.
* Import an OpenAI Agents SDK trace containing explicit question, answer, and memory operations.
* Load the deterministic reference incident.

Imported traces are parsed locally. Engram creates an incident only when it can identify both the user
question and the observed model answer. A trace without those fields remains useful in Observe mode but
cannot support incident replay.

## Replay boundary

Replay capabilities are explicit. Incidents without a compatible executor use
the reference context-only fallback: it changes the branch-local context and
renders a deterministic fixture answer without claiming to have rerun the
agent.

A compatible project executor can provide real agent replay. Engram first forks
the captured checkpoint into isolated baseline and treatment runtimes. Both
runs execute the project graph, retrieval, context assembly, and generation
stages declared by the executor manifest. Engram accepts the comparison only
when the untreated baseline reproduces the recorded answer, then reports the
earliest comparable divergence.

For LangGraph, `defineLangGraphExecutor` enforces declarations for isolated
checkpoint state, isolated Store state, and side-effect handling before it
invokes the graph. The application still owns the implementation of those
isolated resources inside custom nodes.

## Regression boundary

Verified incidents export portable `.engram-test.json` files. Version 2 assertions match memory meaning and
lifecycle state rather than unstable provider IDs, and can run controlled query, entity, score, timestamp,
and distractor variants. The artifact proves only what its configured executor ran; production equivalence
requires a production-equivalent executor.