> ## 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.

# LangGraph quickstart

> Capture, replay, and preserve a LangGraph memory incident in one local workflow.

This guide adds local Engram capture and real checkpoint replay to a LangGraph
agent. It does not require an Engram account, database, or hosted collector.

## Requirements

* Node.js 20 or newer
* A JavaScript or TypeScript LangGraph agent
* macOS, Linux, or Windows

## Try the complete workflow first

To see Engram's core incident loop before instrumenting an agent:

```bash theme={"dark"}
npx --yes @engramviz/cli demo stale-location
```

The command initializes local capture, starts Studio, records a deterministic
three-turn stale-memory failure, and opens the Incidents workspace. No API key
or memory-provider account is required.

## 1. Install and scaffold Engram

From your agent repository:

```bash theme={"dark"}
npm install --save-dev @engramviz/cli
npm install @engramviz/sdk @engramviz/adapter-langgraph
npx engram init --project support-agent --framework langgraph
```

This creates:

* `.engram/config.json`: private local capture credentials.
* `engram.config.json`: checked-in framework, executor, and regression paths.
* `engram.executor.mjs`: one replay module shared by Studio and CI.
* `regressions/`: portable `*.engram-test.json` artifacts.
* `.github/workflows/engram-memory-regressions.yml`: a ready CI job.

Initialization is idempotent and preserves existing files.

## 2. Instrument memory and one replay boundary

Wrap LangGraph's cross-thread Store before compiling the graph:

```ts theme={"dark"}
import { InMemoryStore } from "@langchain/langgraph";
import { EngramClient } from "@engramviz/sdk";
import { instrumentLangGraphStore } from "@engramviz/adapter-langgraph";

const engram = new EngramClient({ adapter: "langgraph" });
const store = instrumentLangGraphStore(new InMemoryStore(), engram);
const graph = workflow.compile({ store, checkpointer });
```

At the application-owned node boundary from which a replay is safe, capture the
graph state inside the active turn:

```ts theme={"dark"}
import { captureLangGraphReplayCheckpoint } from "@engramviz/adapter-langgraph";

await engram.withTurn({ input: question }, async () => {
  const seeded = await graph.updateState(config, initialState, "retrieve");
  await captureLangGraphReplayCheckpoint(graph, seeded, { asNode: "retrieve" });
  return graph.invoke(null, seeded);
});
```

The helper automatically annotates the active Engram turn. The explicit
`asNode` remains required: Engram will not guess where your graph can safely
resume.

<Warning>
  Call `turn.load(...)` only after the application actually places memories into
  model input. A Store search result is retrieval evidence, not proof of active
  context.
</Warning>

## 3. Wire the generated executor

Open `engram.executor.mjs` and implement its three marked functions:

1. `createRuntime`: construct a fresh graph, checkpointer, Store, and blocked or sandboxed tools for each baseline/treatment variant.
2. `applyIntervention`: apply the proposed memory correction to that isolated state.
3. `observe`: map the completed graph state to the selected memories, loaded context, and answer.

The reference implementation is in the
[`langgraph-support-agent`](https://github.com/Meyk0/engram-viz/tree/main/examples/langgraph-support-agent)
example. This is the only application-specific seam: Studio and CI both import
the same module.

## 4. Start Studio and check the integration

In one terminal:

```bash theme={"dark"}
npx engram dev
```

The configured executor is discovered automatically. In another terminal:

```bash theme={"dark"}
npx engram doctor
```

Doctor checks capture credentials, framework/executor agreement, the executor
manifest, replay capabilities, side-effect defaults, a captured LangGraph
checkpoint, and Studio's authenticated executor bridge.

## 5. Capture and open the incident

Run the real reproduction command through Engram:

```bash theme={"dark"}
npx engram run --expected Oakland -- npm run reproduce:incident
```

The CLI prints a direct URL with the trace and expected answer preselected.
Engram injects only `ENGRAM_URL`, `ENGRAM_TOKEN`, and `ENGRAM_PROJECT_ID` into
the child process; replay credentials stay server-side.

## 6. Diagnose, replay, and prove

Open the **Incidents** workspace and select the captured answer. Engram separates:

1. Memory state before the question
2. Retrieval candidates and selection
3. Memories loaded into active context
4. The recorded answer

Apply a branch-local repair and replay. Engram first reruns the untreated
baseline and refuses a causal comparison if it cannot reproduce the captured
answer. It then executes the treatment, reports the earliest observable
divergence, and exports the verified behavior into `regressions/`.

Run every configured regression through the same executor:

```bash theme={"dark"}
npx engram test
```

The workflow created during initialization runs that command on pull requests
and uploads the structured report.

<CardGroup cols={2}>
  <Card title="Run the support-agent example" icon="headset" href="/examples/langgraph-support-agent">
    See the complete graph, model, executor, and regression path.
  </Card>

  <Card title="Instrument LangGraph" icon="workflow" href="/instrument/langgraph">
    Capture durable Store operations while keeping checkpoint state distinct.
  </Card>
</CardGroup>