feat(integrations): add Zep MemoryStore for Strands Agents by danielchalef · Pull Request #590 · getzep/zep

danielchalef · 2026-08-01T00:11:19Z

Summary

Adds zep-strands, a Strands Agents integration that implements the native MemoryStore interface on top of Zep’s temporal Context Graph. This is the extension point the AWS Strands team uses for long-term memory (same surface as Bedrock KB / AgentCore Memory Store / community stores like Dakera).

What’s included

Package: integrations/strands/python/ → PyPI name zep-strands, import zep_strands

API	Behavior
`ZepMemoryStore.search`	`graph.search` (default `scope="auto"` → Context Block)
`ZepMemoryStore.add_messages`	`thread.add_messages` for server-side extraction
`ZepMemoryStore.add`	`graph.add` for text/JSON/message facts
`ZepMemoryStore.initialize`	Provisions user + thread
`ensure_user` / `ensure_thread`	Idempotent out-of-band helpers
`create_zep_search_tool`	Optional pin-or-expose on-demand search tool

Also supports standalone-graph mode via graph_id (search + add only).

Extraction notes

extraction=True (default in writable user/thread mode) uses Strands’ server-side path via add_messages.
Construction fails fast if extraction is enabled without writable user_id + thread_id.
Strands’ default cadence is every 5 turns, so conversation batches only reach Zep when the trigger fires (or on flush()) — graph building is delayed vs turn-by-turn persistence, and Zep ingestion remains async after that.

Usage sketch

from strands import Agent
from strands.memory import MemoryManager
from zep_cloud.client import AsyncZep
from zep_strands import ZepMemoryStore

store = ZepMemoryStore(
    zep_client=AsyncZep(api_key="..."),
    user_id="user-123",
    thread_id="thread-abc",
    first_name="Jane",
    last_name="Smith",
    writable=True,
    extraction=True,
)
agent = Agent(memory_manager=MemoryManager(stores=[store]))

Validation

ruff check + ruff format --check — pass
mypy src/ — pass
pytest — 55 passed, 1 integration test skipped without ZEP_API_KEY
CI wired via paths-filter entry for strands in test-integrations.yml
Docs index / integrations/CLAUDE.md updated

Follow-ups (not in this PR)

Docs page on help.getzep.com (/strands-memory) once the package is published
Listing in Strands community memory-stores catalog after release

Implement zep-strands — a Strands Agents MemoryStore backed by Zep's temporal Context Graph. Supports user-graph and standalone-graph modes, server-side extraction via thread.add_messages, graph.search recall, optional pin-or-expose zep_search tool, and ensure_user/ensure_thread provisioning. Co-authored-by: Daniel Chalef <danielchalef@users.noreply.github.com>

Co-authored-by: Daniel Chalef <danielchalef@users.noreply.github.com>

socket-security · 2026-08-01T00:12:05Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	pypi/strands-agents@1.50.2

View full report

Co-authored-by: Daniel Chalef <danielchalef@users.noreply.github.com>

github-actions

Critical — integrations/strands/python/src/zep_strands/memory_store.py:403,453,504: SDK failures from graph.search, graph.add, and thread.add_messages propagate into the host agent. A transient Zep/network failure can therefore abort recall, extraction, or an agent turn, contrary to the integration convention that Zep errors must not crash agents. Catch operational SDK exceptions, log them without payloads, and return safe fallbacks ([]/None or the framework’s error result). Add failure-path tests.
Critical — integrations/strands/python/src/zep_strands/memory_store.py:439-442: oversized JSON is truncated as arbitrary text. This removes closing syntax and sends invalid JSON to graph.add, so the advertised size guard still produces a rejected write. Reject oversized JSON explicitly or perform structure-aware chunking; add a test with valid JSON exceeding 9,900 characters.

Fail fast when extraction is enabled without writable user/thread mode, and document that Strands' default extraction cadence (every 5 turns) delays when conversation batches reach Zep — on top of async ingestion. Co-authored-by: Daniel Chalef <danielchalef@users.noreply.github.com>

Co-authored-by: Daniel Chalef <danielchalef@users.noreply.github.com>

Truncating a JSON payload strips its closing syntax, so the size guard sent Zep a document it would reject. Oversized json now raises with chunking guidance; text/message still truncate. Also document why Zep SDK errors propagate out of the store methods: MemoryManager skips failing stores on search, raises AggregateMemoryError on add, and ExtractionCoordinator rolls back its high-water mark so a failed batch retries. Swallowing add_messages errors would be read as success and drop those messages permanently. Co-authored-by: Daniel Chalef <danielchalef@users.noreply.github.com>

Bring zep-strands to peer parity: full Agent+MemoryManager integration test (gated on ZEP+OPENAI), root README listing, and example/docs cleanup. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions

No actionable findings. The new Strands integration appears correctly wired into CI and follows the repository’s integration conventions.

Use production-default extraction=True with a session-boundary flush instead of an every-turn InvocationTrigger in the example and live tests. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions

No actionable findings. The new Strands integration, tests, packaging, and CI wiring appear consistent with repository conventions.

github-actions

Warning

[integrations/strands/python/src/zep_strands/search.py line 360, zep_search exception handler] The tool returns the raw exception text to the model (f"Graph search failed: {exc}") and logs the full traceback. SDK exceptions may contain request URLs, identifiers, response bodies, or other sensitive operational details, which would then be forwarded to the configured model provider. Return a generic tool error and log only a sanitized error type/status; keep detailed diagnostics behind an explicit debug-only mechanism. Add a test using an exception containing sensitive text to ensure it is not returned.

Avoid returning raw SDK exception text to the model; log type/status only. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions

No actionable findings. The new Strands integration appears consistent with repository conventions and includes appropriate validation, error handling, CI wiring, documentation, and tests.

cursoragent and others added 2 commits August 1, 2026 00:11

fix(strands): extract text correctly from AgentResult in example

7d11202

Co-authored-by: Daniel Chalef <danielchalef@users.noreply.github.com>

cursoragent and others added 2 commits August 1, 2026 00:12

fix(strands): sort imports for ruff I001

f250f41

Co-authored-by: Daniel Chalef <danielchalef@users.noreply.github.com>

fix(strands): format example and use _message_text helper

989121e

Co-authored-by: Daniel Chalef <danielchalef@users.noreply.github.com>

danielchalef marked this pull request as ready for review August 1, 2026 00:22

github-actions Bot reviewed Aug 1, 2026

View reviewed changes

cursoragent and others added 4 commits August 1, 2026 00:47

docs(strands): note extraction cadence and fail-fast in Features

7db5ead

Co-authored-by: Daniel Chalef <danielchalef@users.noreply.github.com>

test(strands): add live agent E2E and polish for public release

77ee650

Bring zep-strands to peer parity: full Agent+MemoryManager integration test (gated on ZEP+OPENAI), root README listing, and example/docs cleanup. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions Bot reviewed Aug 7, 2026

View reviewed changes

fix(strands): keep example on default extraction cadence

f92ac87

Use production-default extraction=True with a session-boundary flush instead of an every-turn InvocationTrigger in the example and live tests. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions Bot reviewed Aug 7, 2026

View reviewed changes

Fixed bug with initializing Zep in a synchronous function.

81f16d0

github-actions Bot reviewed Aug 7, 2026

View reviewed changes

fix(strands): sanitize zep_search tool errors

2a80700

Avoid returning raw SDK exception text to the model; log type/status only. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions Bot reviewed Aug 7, 2026

View reviewed changes

mehulp93 merged commit cacd163 into main Aug 7, 2026
16 checks passed

Navigation Menu

Uh oh!

feat(integrations): add Zep MemoryStore for Strands Agents - #590

feat(integrations): add Zep MemoryStore for Strands Agents#590
mehulp93 merged 11 commits into
mainfrom
cursor/strands-zep-memory-store-20c8

danielchalef commented Aug 1, 2026 •

edited by cursor Bot

Loading

Uh oh!

socket-security Bot commented Aug 1, 2026 •

edited

Loading

Uh oh!

github-actions Bot left a comment

Uh oh!

github-actions Bot left a comment

Uh oh!

github-actions Bot left a comment

Uh oh!

github-actions Bot left a comment

Uh oh!

github-actions Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

danielchalef commented Aug 1, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What’s included

Extraction notes

Usage sketch

Validation

Follow-ups (not in this PR)

Uh oh!

socket-security Bot commented Aug 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Warning

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

danielchalef commented Aug 1, 2026 •

edited by cursor Bot

Loading

socket-security Bot commented Aug 1, 2026 •

edited

Loading