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:

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:

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:

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:

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.

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.

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 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:

npx engram dev

The configured executor is discovered automatically. In another terminal:

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:

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:

npx engram test

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

Run the support-agent example

See the complete graph, model, executor, and regression path.

Instrument LangGraph

Capture durable Store operations while keeping checkpoint state distinct.