LangGraph Store

Capture LangGraph memory evidence and replay incidents from isolated graph checkpoints.

@engramviz/adapter-langgraph instruments LangGraph’s cross-thread Store interface. It captures durable memory writes, searches, reads, and deletes while preserving the distinction between retrieval and model context.

Install

npm install @engramviz/sdk @engramviz/adapter-langgraph

The adapter supports @langchain/langgraph 1.x and wraps any compatible Store implementation, including InMemoryStore and persistent Store backends.

Wrap the Store

Wrap the Store before compiling the graph, then run the graph inside an Engram turn:

import { InMemoryStore } from "@langchain/langgraph";
import {
  instrumentLangGraphStore,
  langGraphMemoryIds
} from "@engramviz/adapter-langgraph";
import { EngramClient, getActiveEngramTurn } from "@engramviz/sdk";

const engram = new EngramClient({ adapter: "langgraph" });
const store = instrumentLangGraphStore(new InMemoryStore(), engram);

const graph = workflow.compile({ store });

const answer = await engram.withTurn(
  {
    input: "Where do I live?",
    provider: { id: "langgraph", model: "my-agent" }
  },
  async () => {
    return graph.invoke({ input: "Where do I live?" });
  }
);

Inside a graph node, LangGraph exposes the Store as runtime.store. Store searches are captured automatically. Report context loading only after the application actually copies results into the model input:

const memories = await runtime.store.search(
  ["users", userId, "memories"],
  { query: state.input, limit: 5 }
);

const loaded = selectForPrompt(memories);
await getActiveEngramTurn()?.load(langGraphMemoryIds(loaded));

search proves that LangGraph returned candidates. It does not prove that the application placed them in a prompt. Engram never converts a search result into active context automatically.

Captured operations

LangGraph Store call	Engram operation	Evidence
put	store by default	Namespace, key, value, and upsert semantics
search	retrieve	Ranked candidates, scores, selected IDs, and limit
get	retrieve	Direct keyed lookup
delete	delete	Namespace-qualified memory ID
batch	Operation for each direct batch item	Mapped from the batch request and result

LangGraph put is an upsert, so the adapter cannot know whether a key existed without adding another Store read. Use classifyPut when the application knows that a write is an update:

const store = instrumentLangGraphStore(rawStore, engram, {
  classifyPut: ({ key }) => knownKeys.has(key) ? "update" : "store"
});

Memory IDs include the full namespace and key. For example, ["users", "user-1", "memories"] plus "city" becomes langgraph:users/user-1/memories/city. This prevents identical keys in different namespaces from collapsing into one Engram memory.

Checkpoints are different

LangGraph checkpointers persist graph state within a thread and enable resume, history, and replay. LangGraph Store persists arbitrary information across threads. Engram’s adapter observes the latter as durable memory.

It intentionally does not turn every checkpoint value into a memory event. Doing so would make transient execution state look like a durable user fact. Instrument an explicit application boundary separately if checkpoint state is part of the memory behavior being investigated.

Capture a replay boundary

For an incident to rerun the actual graph, capture state at an explicit node boundary while an Engram turn is active:

import {
  captureLangGraphReplayCheckpoint
} from "@engramviz/adapter-langgraph";

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

The helper automatically attaches the checkpoint to the active Engram turn. Pass { attachToActiveTurn: false } only when storing the returned checkpoint yourself, or pass an explicit turn for applications that cannot use async context. asNode is required because replay must resume from a known graph boundary. Engram stores JSON-compatible state values, not the checkpointer implementation or arbitrary closures.

Define the real replay executor

Export a provider-neutral executor from a local module:

import { defineLangGraphExecutor } from "@engramviz/adapter-langgraph";

export default defineLangGraphExecutor({
  id: "support-agent",
  version: "1.0.0",
  supportedSideEffectModes: ["blocked"],

  async createRuntime({ variant, sideEffectMode }) {
    const store = await cloneReplayStore();
    return {
      graph: buildGraph({ store, tools: replaySafeTools }),
      config: { configurable: { thread_id: `replay-${variant}` } },
      isolation: {
        checkpoint: "isolated",
        memoryStore: "isolated",
        sideEffects: sideEffectMode
      }
    };
  },

  applyIntervention({ checkpoint, intervention }) {
    return applyMemoryPolicy(checkpoint.values, intervention);
  },

  observe({ finalState, source, variant }) {
    return mapGraphStateToDecisionRun(finalState, source, variant);
  }
});

Scaffold the module and shared project configuration once:

npx --yes @engramviz/cli init --project support-agent --framework langgraph
npx --yes @engramviz/cli dev

Studio and engram test both discover engram.executor.mjs through engram.config.json. This prevents a passing CI test from silently using a different replay implementation than the engineer used during diagnosis.

Engram runs an untreated baseline first and rejects a causal comparison when it cannot reproduce the captured answer. It then applies the intervention only to the treatment fork, reruns the graph, and compares memory state, retrieval, selection, active context, and answer.

The executor checks the isolation declarations, but your application must make them true. Clone or reconstruct checkpoint and Store state for each variant. Block, record, or safely sandbox tool and network effects. Never replay against a mutable production Store.

Run the LangGraph example

Exercise a real StateGraph and InMemoryStore with deterministic capture.

Run the support-agent quickstart

Exercise the model-backed production-shaped workflow and shared executor.

Understand the evidence model

See what observed, mapped, derived, and unavailable evidence mean.

LangGraph references

• Memory overview
• Persistence and Store
• InMemoryStore API