Add zep-langgraph integration (#524)

* Add zep-langgraph integration

Zep memory for LangGraph (Python). Leads with node/tool helpers (the pattern
Zep's own LangGraph guide and mem0 use), plus a hybrid-delegate BaseStore.

- Node/tool helpers (PRIMARY): a context helper around thread.get_user_context
  to inject a Context Block into the system prompt, a persistence helper around
  thread.add_messages, and prebuilt graph.search tools — usable in StateGraph /
  create_react_agent.
- ZepStore(BaseStore) (SECONDARY): implements only batch/abatch; hybrid-delegate
  wraps a backing KV store (InMemoryStore by default) for exact-key get/put/
  delete/list, and routes search to Zep graph.search (semantic). Ingestion is
  async (no graph read-after-write within a turn) — documented.
- Depends on langgraph>=1.2.5 and zep-cloud>=3.23.0. Python >=3.11.
- README, SETUP, example, 95 mock tests, Makefile, CHANGELOG. CI filter added.

Verified: ruff + ruff format + mypy + pytest (95 passed). See
integrations/SPIKE_FINDINGS.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Fix zep-langgraph review findings: search pagination, message limits, example

- examples/react_agent.py: drop temperature=0 (gpt-5 reasoning models reject
  it, 400ing SETUP.md's first documented command); match the README's
  ChatOpenAI(model="gpt-5").
- store.py ZepStore.search: honor SearchOp.offset (slice), clamp limit to
  [1, 50] (Zep's graph.search ceiling) with a warning, log a clear warning when
  a BaseStore filter is passed (Zep uses typed search_filters instead of
  ignoring it silently), and fix search_scope="auto" returning zero items by
  reading the materialized context block. Fetch offset+limit rows since Zep has
  no server-side offset.
- persistence.py: apply the 4096-char truncation guard to native Zep Message
  objects (the README/example path previously bypassed it and would 400), via a
  shared _truncate_message_content helper; chunk persist_messages /
  persist_messages_sync to <=30 messages per add_messages call (Zep's cap),
  requesting return_context only on the final chunk. Warnings log lengths/counts
  only -- no message content/PII.

Tests: limit clamp, offset honored, auto-scope context item, filter warning,
oversize native Message truncated (+ no mutation / passthrough), >30 messages
chunked (async + sync), context-on-last-chunk only.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Fix chunked persist abandoning remaining chunks; declare langchain-core dep

persist_messages / persist_messages_sync: on a chunk-level add_messages
failure, continue to the remaining chunks (best-effort) instead of
returning early and silently dropping them. The warning now reports the
failing chunk index and total chunk count (counts only, no PII). Adds
regression tests asserting all chunks are attempted after a mid-batch
failure.

pyproject.toml: add explicit langchain-core>=1.0 dependency. langchain_core
is imported directly (tools, persistence, context, store) but was only
pulled in transitively via langgraph; uv resolves it to 1.x.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: danielchalef

.github/workflows/test-integrations.yml

@@ -36,6 +36,8 @@ jobs:
               - 'integrations/livekit/python/**'
             ag2:
               - 'integrations/ag2/python/**'
+            langgraph:
+              - 'integrations/langgraph/python/**'
             pydantic-ai:
               - 'integrations/pydantic-ai/python/**'
 

integrations/langgraph/python/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## 0.1.0 (2026-06-16)
+
+### Added
+
+- **Node / tool helpers (primary path):**
+  - `get_zep_context` / `get_zep_context_sync` — fetch a thread's Context Block
+    via `thread.get_user_context`.
+  - `build_system_message` / `build_system_message_sync` — fold the Context Block
+    and base instructions into a LangChain `SystemMessage` for prompt injection.
+  - `format_context_block` — combine base instructions with a Context Block.
+  - `persist_messages` / `persist_messages_sync` — persist a conversation turn via
+    `thread.add_messages`; accept LangChain or Zep messages, with optional
+    `return_context` to fold persist + retrieve into one round-trip.
+  - `to_zep_message` / `to_zep_messages` — convert LangChain messages to Zep
+    messages (role mapping, multimodal-content flattening, length truncation).
+  - `create_graph_search_tool` / `create_graph_search_tool_sync` — prebuilt
+    LangChain `StructuredTool` over `graph.search`, ready for `create_react_agent`.
+- **`ZepStore` (secondary path):** a hybrid-delegate
+  `langgraph.store.base.BaseStore`. Implements only the two abstract methods
+  (`batch` / `abatch`); delegates exact-key `get` / `put` / `delete` /
+  `list_namespaces` to a backing KV store (default `InMemoryStore`), ingests every
+  `put` into Zep (`graph.add` with `type="json"`), and routes `search` to Zep
+  semantic `graph.search`. Configurable namespace→target resolver, search scope,
+  ingestion toggle, and backing-store search merge.
+- Graceful error handling throughout: a Zep failure is logged and never crashes
+  the host agent.
+- Mock-based test suite, two runnable examples (`react_agent.py`,
+  `store_agent.py`), README, and SETUP guide.
+
+### Notes
+
+- Targets the Zep V3 SDK (`zep-cloud>=3.23.0`) and `langgraph>=1.2.5`.
+- Zep ingestion is asynchronous — there is no read-after-write of graph facts
+  within a turn.

integrations/langgraph/python/Makefile

@@ -0,0 +1,72 @@
+# Makefile for zep-langgraph development
+
+.PHONY: help install format lint type-check test test-cov clean build all
+
+# Default target
+help:
+	@echo "Available commands:"
+	@echo "  install     - Install package and dependencies in development mode"
+	@echo "  format      - Format code with ruff"
+	@echo "  lint        - Run linting checks"
+	@echo "  type-check  - Run type checking with mypy"
+	@echo "  test        - Run tests"
+	@echo "  test-cov    - Run tests with coverage report"
+	@echo "  all         - Run format, lint, type-check, and test"
+	@echo "  build       - Build the package"
+	@echo "  clean       - Clean build artifacts"
+
+# Install package in development mode
+install:
+	uv sync --extra dev
+
+# Format code
+format:
+	uv run ruff format .
+
+# Run linting checks
+lint:
+	uv run ruff check .
+
+# Fix linting issues automatically
+lint-fix:
+	uv run ruff check --fix .
+
+# Run type checking
+type-check:
+	uv run mypy src/
+
+# Run tests
+test:
+	uv run pytest tests/ -v
+
+# Run tests with coverage
+test-cov:
+	uv run pytest tests/ -v --cov=zep_langgraph --cov-report=term-missing --cov-report=xml
+
+# Run all checks (the order matters: format first, then lint, then type-check, then test)
+all: format lint type-check test
+
+# Build the package
+build:
+	uv build
+
+# Clean build artifacts
+clean:
+	rm -rf dist/
+	rm -rf build/
+	rm -rf *.egg-info/
+	rm -rf .pytest_cache/
+	rm -rf .mypy_cache/
+	rm -rf .ruff_cache/
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+	rm -f coverage.xml
+	rm -f .coverage
+
+# Development workflow - run this before committing
+pre-commit: lint-fix format lint type-check test
+	@echo "All checks passed! Ready to commit."
+
+# CI workflow - strict checks without auto-fixing
+ci: lint type-check test
+	@echo "CI checks passed!"

integrations/langgraph/python/README.md

@@ -0,0 +1,202 @@
+# Zep LangGraph Integration
+
+Give [LangGraph](https://github.com/langchain-ai/langgraph) agents durable,
+cross-session memory backed by [Zep](https://www.getzep.com)'s temporal Context
+Graph. The package ships two layers:
+
+- **Node / tool helpers (primary)** — call Zep directly inside your graph nodes:
+  inject the user's Context Block into the system prompt, persist each turn, and
+  expose a graph-search tool. This matches Zep's own LangGraph guide.
+- **`ZepStore` (secondary)** — a hybrid-delegate
+  [`BaseStore`](https://langchain-ai.github.io/langgraph/reference/store/) for
+  `create_react_agent(store=...)` and langmem's memory tools.
+
+## Installation
+
+```bash
+pip install zep-langgraph
+```
+
+See [SETUP.md](SETUP.md) for creating a Zep account, getting an API key, and
+running the example end to end.
+
+## Quick Start (primary path)
+
+Inject Zep context with a `prompt` callable, expose a graph-search tool, and
+persist each turn. Identity (the user, thread, and the user's real name) is yours
+to manage — create the Zep user and thread out-of-band before the first turn.
+
+```python
+import os
+from langchain_core.messages import AIMessage, HumanMessage
+from langchain_openai import ChatOpenAI
+from langgraph.prebuilt import create_react_agent
+from zep_cloud import Message
+from zep_cloud.client import AsyncZep
+from zep_langgraph import build_system_message, create_graph_search_tool, persist_messages
+
+zep = AsyncZep(api_key=os.environ["ZEP_API_KEY"])
+
+async def prompt(state):
+    system = await build_system_message(
+        zep, thread_id="thread-1", base_instructions="You are a helpful assistant."
+    )
+    return [system, *state["messages"]]
+
+agent = create_react_agent(
+    model=ChatOpenAI(model="gpt-5"),
+    tools=[create_graph_search_tool(zep, user_id="user-1")],
+    prompt=prompt,
+)
+
+result = await agent.ainvoke({"messages": [HumanMessage(content="Where do I work?")]})
+reply = result["messages"][-1]
+await persist_messages(
+    zep,
+    thread_id="thread-1",
+    messages=[Message(role="user", content="Where do I work?", name="Alice Smith"), reply],
+)
+```
+
+A complete runnable version is in
+[examples/react_agent.py](examples/react_agent.py).
+
+## How It Works
+
+The Zep loop is the same everywhere: **create user → create thread → add
+messages → retrieve context**. This package wraps each step as a helper you call
+from inside a graph node.
+
+### Context injection — `build_system_message` / `get_zep_context`
+
+`thread.get_user_context(thread_id)` returns a token-efficient **Context Block**
+assembled from the *entire user graph* (the thread only scopes what is relevant
+right now). `build_system_message` fetches it and folds it into a
+`SystemMessage` together with your base instructions, ready to prepend to the
+model's message list. `get_zep_context` returns just the raw block.
+
+Implemented in [src/zep_langgraph/context.py](src/zep_langgraph/context.py).
+
+### Persistence — `persist_messages`
+
+Wraps `thread.add_messages`. Accepts LangChain `BaseMessage` objects (converted
+automatically — `human`→`user`, `ai`→`assistant`, …) or native Zep `Message`
+objects, flattens multimodal content to text, truncates over-long messages, and
+maps names so Zep can resolve identity. Pass `return_context=True` to fold
+persist + retrieve into one round-trip.
+
+Implemented in
+[src/zep_langgraph/persistence.py](src/zep_langgraph/persistence.py).
+
+### On-demand search — `create_graph_search_tool`
+
+Returns a LangChain `StructuredTool` over `graph.search`. Bind it to a model or
+pass it to `create_react_agent(tools=[...])` and the model decides when to search
+the graph. The target (`user_id` for a personal graph, `graph_id` for a shared
+standalone graph) and the search parameters (`scope`, `reranker`, `limit`) are
+fixed at construction so the model only supplies the query.
+
+Implemented in [src/zep_langgraph/tools.py](src/zep_langgraph/tools.py).
+
+### `ZepStore` — a `BaseStore` for the langmem audience
+
+`BaseStore` is LangGraph's cross-thread long-term-memory interface;
+`create_react_agent(store=...)` and langmem's
+`create_manage_memory_tool` / `create_search_memory_tool` require one. Zep is a
+temporal knowledge graph, not a KV store, so `ZepStore` uses a **hybrid-delegate**
+design: a backing KV `BaseStore` (default `InMemoryStore`) serves exact-key
+`get` / `put` / `delete` / `list_namespaces` faithfully and synchronously, while
+every `put` is *also* ingested into Zep and `search` is routed to Zep's semantic
+`graph.search`. Only the two abstract methods (`batch` / `abatch`) are
+implemented; everything else is inherited and delegates to them.
+
+```python
+from zep_langgraph import ZepStore
+
+store = ZepStore(zep)                  # default backing store: InMemoryStore
+await store.aput(("memories", "user-1"), "m1", {"text": "Alice works at Acme."})
+item = await store.aget(("memories", "user-1"), "m1")     # exact-key, synchronous
+hits = await store.asearch(("memories", "user-1"), query="where does Alice work?")
+```
+
+> **Zep ingestion is asynchronous.** A value written with `put` is available
+> immediately for exact-key `get` (served by the backing store), but its
+> extracted facts are **not** instantly returned by `search` — there is no
+> read-after-write of graph facts within a turn. `ZepStore` is the long-term
+> memory layer, not the checkpointer, so graph execution and short-term state are
+> unaffected.
+
+Implemented in [src/zep_langgraph/store.py](src/zep_langgraph/store.py); see
+[examples/store_agent.py](examples/store_agent.py).
+
+## Public API
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `get_zep_context` / `get_zep_context_sync` | async / sync fn | Fetch the Context Block for a thread |
+| `build_system_message` / `build_system_message_sync` | async / sync fn | Build a `SystemMessage` with the Context Block |
+| `format_context_block` | fn | Combine base instructions with a Context Block |
+| `persist_messages` / `persist_messages_sync` | async / sync fn | Persist a turn (LangChain or Zep messages) |
+| `to_zep_message` / `to_zep_messages` | fn | Convert LangChain messages to Zep messages |
+| `create_graph_search_tool` / `create_graph_search_tool_sync` | fn | Build a `graph.search` `StructuredTool` |
+| `ZepStore` | class | Hybrid-delegate `BaseStore` |
+
+Both an `AsyncZep` (async helpers, recommended) and a synchronous `Zep` client
+are supported. Reuse a single client instance.
+
+## Error Handling
+
+Every helper handles Zep failures gracefully: context retrieval and persistence
+log a warning and return `None`/an empty result, the search tool returns an error
+string, and `ZepStore` keeps serving KV operations from its backing store. **A
+Zep failure never crashes the host agent.**
+
+## Configuration
+
+```bash
+export ZEP_API_KEY="your-zep-api-key"
+export OPENAI_API_KEY="your-openai-api-key"   # for the example's model
+```
+
+## Examples
+
+- [examples/react_agent.py](examples/react_agent.py) — `create_react_agent` with
+  Zep context injection, the graph-search tool, and per-turn persistence.
+- [examples/store_agent.py](examples/store_agent.py) — `ZepStore` as a
+  `BaseStore`, showing the KV round-trip and Zep-routed semantic search.
+
+## Development
+
+```bash
+git clone https://github.com/getzep/zep.git
+cd zep/integrations/langgraph/python
+make install      # uv sync --extra dev
+make format       # ruff format .
+make lint         # ruff check .
+make type-check   # mypy src/
+make test         # pytest tests/ -v
+make all          # all of the above
+make build        # uv build
+```
+
+## Requirements
+
+- Python 3.11+
+- `zep-cloud>=3.23.0`
+- `langgraph>=1.2.5` (pulls in `langchain-core`)
+
+## Support
+
+- [Zep Documentation](https://help.getzep.com)
+- [Zep LangGraph Guide](https://help.getzep.com/langgraph-memory)
+- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
+- [GitHub Issues](https://github.com/getzep/zep/issues)
+
+## License
+
+Apache 2.0 — see [LICENSE](../../../LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please see our
+[Contributing Guide](../../../CONTRIBUTING.md) for details.