neruva-langgraph 0.1.1

Drop-in LangGraph integration for Neruva. Wraps BaseCheckpointSaver + BaseStore to persist graph checkpoints and cross-thread KV state into the Neruva substrate. Substrate (v0.5.7) adds typed-shape context dispatch, tenant-specific PII rules, depth-unlimited nested-belief tracking, counterfactual rollouts, EFE planner, continual learning. Deterministic from seed (bit-identical replay). One-line install, works with every LangGraph StateGraph.

neruva-langgraph

Drop-in LangGraph integration for Neruva agent memory. Two wrappers cover the canonical LangGraph plug points: graph checkpoints and the cross-thread KV store.

pip install neruva-langgraph

What's new in the substrate (v0.5.7, May 2026)

The substrate this adapter wraps has gained a lot since the last release. Existing code keeps working — new capabilities are just available.

• Deterministic replay — every query is bit-identical across reruns from the same seed. Replay any past graph state for audit or debugging.
• Typed-shape context — pull structured JSON from records with per-field citations. {question, shape: {field: type}} → typed result without an LLM at query time.
• Tenant-specific PII rules — register your custom ID formats (employee codes, patient codes, order IDs) from 3-5 examples. The substrate redacts them automatically. Sub-microsecond per span.
• Depth-unlimited nested-belief tracking — store and retrieve chains like Alice → Bob → Carol thinks X at any depth, with inner-position-swap rejection.
• Counterfactual rollouts — "what if action k had been a' instead?" Replay an action sequence with one step substituted.
• Active inference planning — score candidate action sequences by KL distance to a goal-marginal. Caller-owned dynamics.
• Continual K-gram learning — provable no-forgetting via integer-add commutativity; repeated train() calls accumulate.

NeruvaCheckpointSaver

Persists every graph checkpoint into Neruva Records. One namespace per thread_id, so each conversation gets its own replayable timeline. Drop into any StateGraph.compile():

from langgraph.graph import StateGraph
from neruva_langgraph import NeruvaCheckpointSaver

graph = builder.compile(
    checkpointer=NeruvaCheckpointSaver(api_key="nv_..."),
)
graph.invoke(
    {"input": "hello"},
    config={"configurable": {"thread_id": "user_alice"}},
)

Realistic example -- multi-turn StateGraph with persistent checkpoints

from typing import TypedDict
from langgraph.graph import StateGraph, END
from langchain_anthropic import ChatAnthropic
from neruva_langgraph import NeruvaCheckpointSaver

class State(TypedDict):
    messages: list

def call_model(state: State) -> State:
    llm = ChatAnthropic(model="claude-opus-4-7")
    state["messages"].append(llm.invoke(state["messages"]))
    return state

builder = StateGraph(State)
builder.add_node("model", call_model)
builder.set_entry_point("model")
builder.add_edge("model", END)
graph = builder.compile(checkpointer=NeruvaCheckpointSaver())
graph.invoke({"messages": ["What did I tell you last week?"]},
             config={"configurable": {"thread_id": "user_alice"}})

NeruvaContextStore

LangGraph's BaseStore for cross-thread KV (e.g. user preferences, shared facts). Backed by Records + agent_recall for semantic search:

from neruva_langgraph import NeruvaContextStore

store = NeruvaContextStore(api_key="nv_...")
graph = builder.compile(
    checkpointer=NeruvaCheckpointSaver(),
    store=store,
)
store.put(("users", "alice"), "profile", {"city": "Toronto"})
hit = store.get(("users", "alice"), "profile")
print(hit)   # -> Item(value={'city': 'Toronto'}, ...)

Why Neruva instead of LangGraph's built-in checkpointers?

Feature	LangGraph defaults	Neruva
Persists across process restart	sqlite / postgres setup	Built-in (GCS-backed)
Cross-session recall	No	Yes via namespaces=[...]
Vector / semantic store search	No (KV only)	Yes via agent_recall
Auto fact extraction (KG)	No	Auto (hd_kg_extraction_prompt)
Determinism / replayability	No	Bit-identical from seed
Portability	DB-locked	.neruva zip container

Get an API key - Docs - Status