Skip to main content
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.