hindsight-langgraph 0.1.2

LangGraph integration for Hindsight - persistent memory tools, nodes, and store for AI agents

hindsight-langgraph

LangGraph and LangChain integration for Hindsight — persistent long-term memory for AI agents.

Provides three integration patterns:

• Tools — retain/recall/reflect as LangChain @tool functions for agent-driven memory. Works with both LangChain and LangGraph.
• Nodes (LangGraph) — pre-built graph nodes for automatic memory injection and storage
• BaseStore (LangGraph) — drop-in BaseStore adapter for LangGraph's built-in memory system

Prerequisites

• A running Hindsight instance (self-hosted via Docker or Hindsight Cloud)
• Python 3.10+

Installation

pip install hindsight-langgraph

Quick Start: Tools

Bind Hindsight memory tools to your LangGraph agent so it can store and retrieve memories on demand.

from hindsight_client import Hindsight
from hindsight_langgraph import create_hindsight_tools
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

client = Hindsight(base_url="http://localhost:8888")
tools = create_hindsight_tools(client=client, bank_id="user-123")

agent = create_react_agent(
    ChatOpenAI(model="gpt-4o"),
    tools=tools,
)

result = await agent.ainvoke(
    {"messages": [{"role": "user", "content": "Remember that I prefer dark mode"}]}
)

Quick Start: Memory Nodes

Add recall and retain nodes to your graph for automatic memory injection before LLM calls and storage after responses.

from hindsight_client import Hindsight
from hindsight_langgraph import create_recall_node, create_retain_node
from langgraph.graph import StateGraph, MessagesState, START, END

client = Hindsight(base_url="http://localhost:8888")

recall = create_recall_node(client=client, bank_id="user-123")
retain = create_retain_node(client=client, bank_id="user-123")

builder = StateGraph(MessagesState)
builder.add_node("recall", recall)
builder.add_node("agent", agent_node)  # your LLM node
builder.add_node("retain", retain)

builder.add_edge(START, "recall")
builder.add_edge("recall", "agent")
builder.add_edge("agent", "retain")
builder.add_edge("retain", END)

graph = builder.compile()

Dynamic Bank IDs

Use bank_id_from_config to resolve the bank per-request from the graph's config:

recall = create_recall_node(client=client, bank_id_from_config="user_id")
retain = create_retain_node(client=client, bank_id_from_config="user_id")

# Bank ID resolved at runtime
result = await graph.ainvoke(
    {"messages": [{"role": "user", "content": "hello"}]},
    config={"configurable": {"user_id": "user-456"}},
)

Quick Start: BaseStore

Use Hindsight as a LangGraph BaseStore for cross-thread persistent memory with semantic search.

from hindsight_client import Hindsight
from hindsight_langgraph import HindsightStore

client = Hindsight(base_url="http://localhost:8888")
store = HindsightStore(client=client)

graph = builder.compile(checkpointer=checkpointer, store=store)

# Store and search memories via the store API
await store.aput(("user", "123", "prefs"), "theme", {"value": "dark mode"})
results = await store.asearch(("user", "123", "prefs"), query="theme preference")

Configuration

Global config

from hindsight_langgraph import configure

configure(
    hindsight_api_url="http://localhost:8888",
    api_key="your-api-key",  # or set HINDSIGHT_API_KEY env var
    budget="mid",
    tags=["source:langgraph"],
)

Per-call overrides

All factory functions accept client, hindsight_api_url, and api_key to override the global config.

Parameter	Description	Default
hindsight_api_url	Hindsight API URL	https://api.hindsight.vectorize.io
api_key	API key (or HINDSIGHT_API_KEY env var)	None
budget	Recall budget: low, mid, high	mid
max_tokens	Max tokens for recall results	4096
tags	Tags applied to retain operations	None
recall_tags	Tags to filter recall results	None
recall_tags_match	Tag matching: any, all, any_strict, all_strict	any

Requirements

• Python 3.10+
• langchain-core >= 0.3.0
• hindsight-client >= 0.4.0
• langgraph >= 0.3.0 (only for nodes and store patterns — install with pip install hindsight-langgraph[langgraph])

Documentation

• Integration docs
• Cookbook: ReAct agent with memory
• Hindsight API docs