docs(client): fix search result example usage by haosenwang1018 · Pull Request #1345 · MemMachine/MemMachine

haosenwang1018 · 2026-04-17T15:49:20Z

Purpose of the change

Fix the Python client docs/demo so they use the actual SearchResult object API instead of treating search results like a dict.

Description

Fixes #973

The current Python SDK example and demo access search results like:

results.get('episodic_memory', [])
item['content']

But the Python client returns typed objects (SearchResult, EpisodicMemory), which causes runtime failures like:

AttributeError: 'SearchResult' object has no attribute 'get'

This change updates:

docs/api_reference/python/client.mdx
examples/memmachine_client_demo.py

to use object-style access instead:

results.episodic_memory or []
item.content
item.producer_role
memory.timestamp
memory.user_metadata

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 docs example now iterates with results.episodic_memory or []
Verified the docs example uses object attributes like item.content
Verified the official demo no longer uses results.get(...) or dict indexing for search results

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

sscargal · 2026-04-17T17:27:04Z

@haosenwang1018 thank you for the pull request submission. Please sign your commits, resolve the unit test failures, and review the CoPilot feedback. You only need to resolve the relevant items. Thanks.

Copilot

Pull request overview

Note

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

Fixes Python SDK docs/demo to use typed result objects for memory search output, and extends the client/tooling to accept raw filter strings (plus episode type support in LangGraph).

Changes:

Update docs and demo to use attribute-style access for search results (e.g., item.content).
Add filter: str | None passthrough to Memory.search() / Memory.list() and LangGraph search_memory().
Add optional episode_type handling + normalization in LangGraph tools, with expanded tests.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/client/src/memmachine_client/memory.py	Adds raw filter string parameter and combines it with built-in / dict filters
packages/client/src/memmachine_client/langgraph.py	Adds `episode_type` support, normalizes enum values, and passes raw `filter` through
packages/client/client_tests/test_memory.py	Adds unit tests for raw filter strings and updates filter_dict expectations
packages/client/client_tests/test_langgraph.py	Updates tool tests for new `filter`/`episode_type` behavior
packages/client/client_tests/test_integration_complete.py	Aligns integration test filter_dict keys with `metadata.` prefix
examples/memmachine_client_demo.py	Switches demo to attribute access for episodic memory items
docs/api_reference/python/client.mdx	Updates docs example to attribute access for search results

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

    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:


        self,
        query: str,
        limit: int | None = None,
        expand_context: int = 0,
        score_threshold: float | None = None,
        filter_dict: dict[str, str] | None = None,
        timeout: int | None = None,
        *,
+        filter: str | None = None,


    print("Results found:")
-    for idx, item in enumerate(results.get('episodic_memory', [])):
-        print(f"[{idx+1}] {item['content']} (Role: {item['producer_role']})")
+    for idx, item in enumerate(results.episodic_memory or []):


+    episodic_memories = results.episodic_memory or []
+    if not episodic_memories:
        print("   No memories found.")
        return

-    episodic_memories = results["episodic_memory"]
-    if episodic_memories and len(episodic_memories) > 0:
-        print(f"   Found {len(episodic_memories[0])} relevant memories:")
-        for i, memory in enumerate(episodic_memories[0][:3], 1):  # Show top 3
-            print(f"      Time: {memory['timestamp']}")
-            print(f"   {i}. {memory['content']}")
-            if memory.get("user_metadata"):
-                print(f"      Metadata: {memory['user_metadata']}")
-            print()
+    print(f"   Found {len(episodic_memories)} relevant memories:")
+    for i, memory in enumerate(episodic_memories[:3], 1):  # Show top 3
+        print(f"      Time: {memory.timestamp}")
+        print(f"   {i}. {memory.content}")
+        if memory.user_metadata:
+            print(f"      Metadata: {memory.user_metadata}")


SarahScargall · 2026-05-04T18:40:20Z

            timeout: Request timeout in seconds (uses client default if not provided)
+            filter: Optional raw filter string. If provided together with built-in or
+                    `filter_dict` filters, all filters are combined with AND.


Hi @haosenwang1018!

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

Also, please take a look at the feedback that CoPilot has generated and respond to it accordingly. Conflicts are especially important to respond to.

Kind Regards,
Sarah

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 (MemMachine#1341 → MemMachine#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 MemMachine#1352 and MemMachine#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 MemMachine#1341, MemMachine#1342, MemMachine#1343, MemMachine#1344, MemMachine#1345, MemMachine#1346, MemMachine#1347, MemMachine#1348, MemMachine#1349 Co-authored-by: Steve Scargall <steve.scargall@gmail.com> Signed-off-by: Steve Scargall <37674041+sscargal@users.noreply.github.com>

…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:14:11Z

Closed by #1403

haosenwang1018 added 5 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

sscargal requested a review from Copilot April 17, 2026 17:21

Copilot AI reviewed Apr 17, 2026

View reviewed changes

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

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(client): fix search result example usage#1345

docs(client): fix search result example usage#1345
haosenwang1018 wants to merge 5 commits into
MemMachine:mainfrom
haosenwang1018:docs/python-search-result-object

haosenwang1018 commented Apr 17, 2026 •

edited by sscargal

Loading

Uh oh!

sscargal commented Apr 17, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

SarahScargall May 4, 2026

Uh oh!

sscargal commented May 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

haosenwang1018 commented Apr 17, 2026 • edited by sscargal Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose of the change

Description

Type of change

How Has This Been Tested?

Checklist

Maintainer Checklist

Uh oh!

sscargal commented Apr 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

SarahScargall May 4, 2026

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

haosenwang1018 commented Apr 17, 2026 •

edited by sscargal

Loading