docs(langgraph): document filter and episode type support by haosenwang1018 · Pull Request #1349 · MemMachine/MemMachine

haosenwang1018 · 2026-04-17T17:37:38Z

Purpose of the change

Keep the LangGraph integration README aligned with the current wrapper capabilities.

Description

Follow-up to #1310 and #1002

This updates integrations/langgraph/README.md to document the wrapper features that were recently added/fixed:

raw search filter string support via filter='metadata.category = "work"'
episode_type string normalization support (for example episode_type="message")

It also updates the example LangGraph node snippet to show both capabilities in context.

Type of change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Refactor (does not change functionality, e.g., code style improvements, linting)
Documentation update
Project Maintenance (updates to build scripts, CI, etc., that do not affect the main project)
Security (improves security without changing functionality)

How Has This Been Tested?

Manual verification:

Verified the LangGraph README now documents raw filter string support
Verified it documents episode_type string support
Verified the node example now shows both filter= and episode_type= usage

Checklist

Maintainer Checklist

Confirmed all checks passed
Contributor has signed the commit(s)
Reviewed the code
Run, Tested, and Verified the change(s) work as expected

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates the Python client + LangGraph wrapper to support passing a raw filter expression string and to accept episode_type as either an enum or string, and refreshes docs/examples to match.

Changes:

Add filter: str | None support to Memory.search() and Memory.list() by AND-combining it with existing filter_dict/built-in metadata filters.
Normalize episode_type strings in LangGraph tools before calling the underlying client.
Update unit/integration tests and docs/examples to use metadata-prefixed filters and the typed SearchResult API.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/client/src/memmachine_client/memory.py	Adds raw `filter` string support and combines it with existing filters.
packages/client/src/memmachine_client/langgraph.py	Adds `filter` passthrough and `episode_type` string-to-enum normalization.
packages/client/client_tests/test_memory.py	Adds coverage for raw filter strings and updates filter_dict expectations.
packages/client/client_tests/test_langgraph.py	Adds tests for raw filter passthrough and episode_type normalization; updates call expectations.
packages/client/client_tests/test_integration_complete.py	Updates integration test to use `metadata.*` keys in filter_dict.
packages/client/README.md	Updates example usage to typed `SearchResult` and metadata-prefixed filters.
integrations/langgraph/README.md	Documents raw filter + episode_type support and updates node example.
examples/memmachine_client_demo.py	Updates demo to use typed results and metadata-prefixed filter examples.
examples/README.md	Updates description to reflect typed API and filter examples.
docs/api_reference/python/client.mdx	Updates API docs example to use typed `SearchResult` accessors.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-20T17:58:38Z

    def list(
        self,
        memory_type: MemoryType = MemoryType.Episodic,
        page_size: int = 100,
        page_num: int = 0,
        filter_dict: dict[str, str] | None = None,
+        filter: str | None = None,
        set_metadata: dict[str, JsonValue] | None = None,
        timeout: int | None = None,
    ) -> ListResult:


Adding filter as a positional parameter in the middle of list() is a backwards-incompatible change for any callers passing set_metadata/timeout positionally (their arguments will shift into filter). To keep backward compatibility, move filter to be keyword-only and/or place it after the existing positional parameters; e.g., keep set_metadata and timeout in their prior positions and add *, filter: str | None = None after them (or introduce * before filter).

Copilot · 2026-04-20T17:58:39Z

+            normalized_episode_type = (
+                EpisodeType(episode_type)
+                if isinstance(episode_type, str)
+                else episode_type
+            )


The current "string normalization" only converts exact string values and does not normalize common user input (e.g., leading/trailing whitespace or case differences). This can cause unexpected failures (ValueError from Enum construction) for inputs like ' message ' or 'MESSAGE'. Consider applying basic normalization (e.g., strip() and a consistent casing strategy) before constructing EpisodeType, and raise a clearer error if the value is invalid.

Copilot · 2026-04-20T17:58:39Z

+The generated tools support:
+- raw search filter strings via `filter='metadata.category = "work"'`
+- `episode_type` as either an `EpisodeType` enum or a string value like `"message"`


The PR title/description frames this as aligning documentation, but this PR also introduces behavior/API surface changes in the Python client and LangGraph wrapper (e.g., new filter parameter, episode_type handling) plus tests. Please update the PR title/description to explicitly mention the client/wrapper code changes (or split docs-only vs behavior changes) so reviewers and release notes accurately reflect the scope.

SarahScargall · 2026-05-04T18:51:23Z

Hi @haosenwang1018!

For this PR (and all your other PRs) to merge, we need you to sign your commits.

Also, please review the feedback CoPilot has generated and respond accordingly. Conflicts are especially important to respond to.

Kind Regards,
Sarah

sscargal

@haosenwang1018 The code changes look good. Please sign your commit(s), squash them if necessary, and resolve the merge conflict. Thanks.

…ion (#1403) * feat(client+langgraph): raw filter strings and EpisodeType normalization Add three small features to the Python client and its LangGraph wrapper so callers can pass structured filter expressions and either-enum-or-string episode types directly. 1. `Memory.search(filter=...)` and `Memory.list(filter=...)` Accept an optional raw filter string alongside `filter_dict`. When both are provided, the two are combined with `AND`. The raw filter is passed through to the v2 `SearchMemoriesSpec.filter` / `ListMemoriesSpec.filter` fields unchanged. 2. `MemMachineTools.search_memory(filter=...)` Pipes the same raw filter through the LangGraph search-memory tool. 3. `MemMachineTools.add_memory(episode_type=...)` Accept either an `EpisodeType` enum or its string value (e.g. `"message"`), normalizing strings via `EpisodeType(...)` before delegating to `Memory.add`. The factory tool's return-type annotation was widened to match. The `filter` parameter shadows the Python builtin, which is the same trade-off `memmachine_common.api.SearchMemoriesSpec` already made for its `filter:` field — keeping the parameter name aligned with the API field. `# noqa: A002` is applied at the three call sites with a comment pointing at the API spec. This commit consolidates the substantive work from haosenwang1018's 9-commit stack (#1341 → #1349) into a single rebased+linted commit against current `main`. The original stack's prefix-style doc and test changes have been omitted because they have already landed on `main` via #1352 and #1311. The original commits authored by haosenwang1018: - 921b55f feat(client): support raw filter strings - e0849bb feat(langgraph): support raw filter strings - 53b489e fix(langgraph): normalize episode type strings Closes #1341, #1342, #1343, #1344, #1345, #1346, #1347, #1348, #1349 Co-authored-by: Steve Scargall <steve.scargall@gmail.com> Signed-off-by: Steve Scargall <37674041+sscargal@users.noreply.github.com> * docs(langgraph): document filter and episode type support --------- Signed-off-by: Steve Scargall <37674041+sscargal@users.noreply.github.com> Co-authored-by: haosenwang1018 <haosenwang1018@users.noreply.github.com> Co-authored-by: Shu Wang <33640803+malatewang@users.noreply.github.com>

sscargal · 2026-05-13T23:15:19Z

Closed by #1403

haosenwang1018 added 9 commits April 17, 2026 13:47

test(client): update remaining filter prefix tests

041128d

feat(client): support raw filter strings

921b55f

feat(langgraph): support raw filter strings

e0849bb

fix(langgraph): normalize episode type strings

53b489e

docs(client): fix search result example usage

b0b9a6b

docs(client): fix packaged search result examples

f06ae69

docs(examples): update remaining filter prefix demo usage

a4bcae1

docs(examples): sync python demo summary

eef6770

docs(langgraph): document filter and episode type support

c7e0ded

sscargal requested a review from Copilot April 20, 2026 17:50

Copilot AI reviewed Apr 20, 2026

View reviewed changes

Copilot started reviewing on behalf of sscargal April 20, 2026 17:59 View session

SarahScargall self-requested a review May 4, 2026 18:51

sscargal requested changes May 12, 2026

View reviewed changes

sscargal added this to the v0.3.9 milestone May 13, 2026

sscargal mentioned this pull request May 13, 2026

feat(client+langgraph): raw filter strings and EpisodeType normalization #1403

Merged

4 tasks

sscargal closed this May 13, 2026

Navigation Menu

Uh oh!

docs(langgraph): document filter and episode type support - #1349

docs(langgraph): document filter and episode type support#1349
haosenwang1018 wants to merge 9 commits into
MemMachine:mainfrom
haosenwang1018:docs/langgraph-readme-capabilities

haosenwang1018 commented Apr 17, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 20, 2026

Uh oh!

Copilot AI Apr 20, 2026

Uh oh!

Copilot AI Apr 20, 2026

Uh oh!

SarahScargall commented May 4, 2026

Uh oh!

sscargal left a comment

Uh oh!

sscargal commented May 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

haosenwang1018 commented Apr 17, 2026

Purpose of the change

Description

Type of change

How Has This Been Tested?

Checklist

Maintainer Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

SarahScargall commented May 4, 2026

Uh oh!

sscargal left a comment

Choose a reason for hiding this comment

Uh oh!

sscargal commented May 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants