Skip to content

docs: clarify filter field prefix requirements#1333

Merged
sscargal merged 1 commit into
MemMachine:mainfrom
haosenwang1018:docs/filter-prefix-search-list
May 15, 2026
Merged

docs: clarify filter field prefix requirements#1333
sscargal merged 1 commit into
MemMachine:mainfrom
haosenwang1018:docs/filter-prefix-search-list

Conversation

@haosenwang1018

@haosenwang1018 haosenwang1018 commented Apr 17, 2026

Copy link
Copy Markdown
Contributor

Purpose of the change

Document the stricter filter behavior introduced by #1291 so the public API docs match runtime behavior.

Description

Fixes #1306
Fixes #1307
Fixes #1308

This updates the memory search/list docs to explain that:

  • filter values use the structured filter expression language
  • user metadata fields must be referenced with the m. or metadata. prefix
  • unsupported fields are rejected instead of being silently ignored

Updated locations:

  • OpenAPI router doc source
  • generated docs/openapi.json
  • Python memory API docs
  • TS REST docs for SearchMemoriesOptions and ListMemoriesOptions

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?

  • Unit Test
  • Integration Test
  • End-to-end Test
  • Test Script (please provide)
  • Manual verification (list step-by-step instructions)

Manual verification:

  1. Updated packages/common/src/memmachine_common/api/doc.py
  2. Regenerated OpenAPI via uv run python docs/tools/generate_openapi.py
  3. Verified the resulting docs/openapi.json descriptions for list/search memories reflect the prefixed filter syntax
  4. Updated Python and TS docs examples to use m.source

Checklist

  • I have signed the commit(s) within this pull request
  • My code follows the style guidelines of this project (See STYLE_GUIDE.md)
  • I have performed a self-review of my own code
  • I have commented my code
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added unit tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • Any dependent changes have been merged and published in downstream modules
  • I have checked my code and corrected any misspellings

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 sscargal requested a review from Copilot April 17, 2026 17:38
Copilot AI reviewed Apr 17, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Note

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

Updates public API documentation to match the stricter filter behavior introduced in #1291 (requiring metadata field prefixes and rejecting unsupported fields).

Changes:

  • Clarifies in router docstrings that filter uses the structured filter expression language and requires m. / metadata. prefixes for user metadata.
  • Regenerates docs/openapi.json to reflect the updated endpoint descriptions.
  • Updates Python + TS REST docs/examples to use m.source and to document rejection of unsupported filter fields.

Reviewed changes

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

Show a summary per file
File Description
packages/common/src/memmachine_common/api/doc.py Updates endpoint docstrings for list/search memories filter semantics and prefix requirements.
docs/openapi.json Regenerated OpenAPI description strings to align with updated router docs.
docs/api_reference/ts-rest/interfaces/SearchMemoriesOptions.mdx Updates filter field docs + adds example using m.source.
docs/api_reference/ts-rest/interfaces/ListMemoriesOptions.mdx Updates filter field docs + adds example using m.source.
docs/api_reference/python/memory_api.mdx Updates Python example + parameter docs to use prefixed metadata keys.

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

Comment thread docs/api_reference/python/memory_api.mdx Outdated
Comment thread docs/api_reference/ts-rest/interfaces/SearchMemoriesOptions.mdx Outdated
Comment thread packages/common/src/memmachine_common/api/doc.py
Comment on lines +732 to +735
The filter field accepts the structured filter expression language.
User-defined metadata keys must be referenced with the `m.` or `metadata.` prefix
(for example, `m.source = "chat_v3"`). Unknown or unsupported fields are rejected
instead of being ignored.

Copilot AI Apr 17, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

“Rejected” is an important behavioral change, but the docs don’t say how the rejection manifests (e.g., HTTP status code / error shape). Consider explicitly stating the response behavior (such as returning a 4xx) and/or linking to (or briefly summarizing) the structured filter expression language reference so users know what syntax is accepted beyond the single equality example.

Copilot uses AI. Check for mistakes.
@sscargal

sscargal commented Apr 17, 2026

Copy link
Copy Markdown
Contributor

@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.

@sscargal sscargal added this to the v0.3.9 milestone May 13, 2026
@haosenwang1018 @sscargal
docs: clarify filter field prefix requirements
cfc6467 
Update the API docstrings and the TypeScript `ListMemoriesOptions`
reference to document the `m.` / `metadata.` prefix requirement for
user-defined metadata fields in the filter expression language.
Unknown or unsupported fields are now rejected by the server (see
MemMachine#1291), so referencing user metadata without a prefix returns a 400
instead of being silently ignored.

Files updated:
  - `packages/common/src/memmachine_common/api/doc.py` —
    `SEARCH_MEMORIES` and `LIST_MEMORIES` endpoint docstrings.
  - `docs/api_reference/ts-rest/interfaces/ListMemoriesOptions.mdx` —
    `filter` property description + `m.source = "chat_v3"` example
    in the usage snippet.
  - `docs/openapi.json` — regenerated from the updated doc.py via
    `docs/tools/generate_openapi.py`.

The original PR (MemMachine#1333) also touched
`docs/api_reference/python/memory_api.mdx` and
`docs/api_reference/ts-rest/interfaces/SearchMemoriesOptions.mdx`,
but `main` has since received equivalent (and slightly more
detailed) wording in both files via the merge of MemMachine#1352 and the
related cleanup. Those hunks have been dropped during rebase to
avoid no-op conflicts.

Refs: MemMachine#1333

Co-authored-by: Steve Scargall <steve.scargall@gmail.com>
Signed-off-by: Steve Scargall <37674041+sscargal@users.noreply.github.com>
@sscargal sscargal force-pushed the docs/filter-prefix-search-list branch from 22a1b4c to cfc6467 Compare May 13, 2026 22:14
@sscargal sscargal self-requested a review May 13, 2026 22:17
sscargal
sscargal approved these changes May 15, 2026
View reviewed changes

@sscargal sscargal left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@sscargal sscargal merged commit b1feb56 into MemMachine:main May 15, 2026
46 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@sscargal sscargal sscargal approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

v0.3.9

3 participants

@haosenwang1018 @sscargal