feat: add structured memory queries

[loveRhythm1990]

What type of PR is this?

• feat (new feature)
• fix (bug fix)
• docs (documentation)
• style (formatting, no code change)
• refactor (code change that neither fixes a bug nor adds a feature)
• perf (performance improvement)
• test (adding or updating tests)
• chore (maintenance, tooling)
• build / ci (build or CI changes)

Which issue(s) this PR fixes

Fixes #227

What this PR does / why we need it

Adds a dedicated structured memory query path for applications that need deterministic filtering without running embedding, vector, keyword, fulltext, graph, or relevance-ranking retrieval.

• Adds POST /v1/memories/query with exact, type-sensitive scalar extra_metadata_filter matching.
• Combines metadata, subject, memory type, session, trust tier, branch, and cursor selectors with AND.
• Requires at least one selector and validates metadata key/value limits to prevent accidental broad scans or unsafe JSON paths.
• Reuses the paginated list response (items, next_cursor) with stable memory ID ordering.
• Adds sync and async Python SDK memories.query() methods and exposes subject_id / extra_metadata on the SDK Memory model.
• Keeps retrieve and search unchanged and intentionally does not add an MCP tool, preserving the existing agent-facing MCP surface.
• Documents the SDK method and adds MatrixOne REST E2E plus sync/async SDK unit coverage.

Validation:

• cargo check -p memoria-api -p memoria-service -p memoria-storage
• cargo test -p memoria-api --test api_e2e test_api_structured_query_by_extra_metadata -- --nocapture
• .venv/bin/python -m pytest tests/unit/test_memories.py tests/unit/test_memories_async.py -q (36 passed)
• .venv/bin/python -m ruff check src/memoria/models.py src/memoria/resources/memories.py

[Copilot]

Pull request overview

Adds deterministic structured memory querying across the REST API, storage layer, and Python SDK.

Changes:

• Adds filtered, cursor-paginated POST /v1/memories/query.
• Adds sync/async Python SDK support and response fields.
• Adds validation, E2E/unit tests, and documentation.

Reviewed changes

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

Show a summary per file

File	Description
sdk/python/tests/unit/test_memories.py	Tests sync querying and validation.
sdk/python/tests/unit/test_memories_async.py	Tests async querying.
sdk/python/src/memoria/resources/memories.py	Implements SDK query methods.
sdk/python/src/memoria/models.py	Exposes subject and metadata fields.
sdk/python/README.md	Documents structured queries.
sdk/python/CHANGELOG.md	Records the SDK feature.
memoria/crates/memoria-storage/src/store.rs	Implements validation and SQL filtering.
memoria/crates/memoria-storage/src/lib.rs	Exports storage query utilities.
memoria/crates/memoria-service/src/service.rs	Adds structured query service options and path.
memoria/crates/memoria-service/src/lib.rs	Exports structured query options.
memoria/crates/memoria-api/tests/api_e2e.rs	Tests filtering, pagination, and branches.
memoria/crates/memoria-api/src/routes/memory.rs	Handles structured query requests.
memoria/crates/memoria-api/src/models.rs	Defines and validates query requests.
memoria/crates/memoria-api/src/lib.rs	Registers the query endpoint.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (2)

memoria/crates/memoria-storage/src/store.rs:5363

• The new SQL path's tenant and active-record predicates are not exercised by the added structured-query tests: those tests use only one user and never deactivate/supersede a matching memory. Add query-specific MatrixOne E2E coverage showing that another user/group scope cannot see a match and that an inactive matching row is excluded, since existing list tests execute a different storage method.

        let mut inner =
            format!("SELECT memory_id FROM {table} WHERE user_id = ? AND is_active = 1");

sdk/python/src/memoria/models.py:45

• Adding subject_id before the existing optional fields changes the public dataclass's positional constructor: callers that previously passed session_id (and later fields) positionally will now bind those values to the wrong attributes without an error. Keep all existing fields in their original order and append the new fields after retrieval_score.

    subject_id: str | None = None

[gouhongshen]

Reviewed current head e8bc4d3. One actionable compatibility finding is inline. Verification: cargo check for memoria-api/service/storage, the structured-query MatrixOne API E2E cases, the storage validation test, and 42 Python SDK unit tests passed.

[aptend]

Reviewed head e8bc4d3. Two blocking contract issues remain:

1. [P1] Keep the public Memory dataclass positional field order compatible. Inserting subject_id before session_id silently shifts every existing optional positional argument. I reproduced an old positional construction where session-old is now stored as subject_id and the old retrieval score is stored as created_at. Append new fields after the existing fields or make them keyword-only, and add a compatibility regression test.

2. [P1] Reject blank selectors instead of silently dropping them. structured_options normalizes whitespace-only subject_id, session_id, trust_tier, and branch to None. When another selector is present, a request such as extra_metadata_filter plus subject_id set to spaces succeeds as a broader metadata-only query; a blank branch can even fall back to the active branch. This contradicts the documented rule that all supplied selectors are combined with AND. Apply the same non-empty validation in REST and sync/async SDK paths.

Verification on this head: cargo check for memoria-storage, memoria-service, and memoria-api passed; the storage validation test passed; 42 Python SDK unit tests passed; git diff --check passed.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (2)

memoria/crates/memoria-api/tests/api_e2e.rs:431

• This query does not actually verify the urgent or memory_types predicates: every fixture has urgent: true and is stored with the default semantic type, so the test still passes if either SQL predicate is omitted. Add near-matching fixtures with urgent: false and a non-semantic type to exercise these filters.

            "extra_metadata_filter": {"scene": "incident", "rank": 2, "urgent": true},
            "memory_types": ["semantic"],

sdk/python/src/memoria/resources/memories.py:62

• For a key longer than 64 bytes, this error states only rules that the key already satisfies, so SDK callers cannot tell why validation failed. Include the 64-byte limit in the message, matching the server-side validation error.

                    "query: extra_metadata_filter keys must start with an ASCII letter or "
                    "underscore and contain only ASCII letters, digits, or underscore"

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (1)

memoria/crates/memoria-storage/src/store.rs:5357

• memory_types is unbounded, and duplicate valid values survive parsing. A request near the 2 MB body limit can therefore make this code generate and bind tens of thousands of IN placeholders, even though the model has only six possible memory types, causing avoidable allocation/DB load or a parameter-limit failure. Reject lists larger than the canonical type set (or deduplicate them) before constructing the SQL.

        if let Some(types) = memory_types.filter(|types| !types.is_empty()) {
            inner.push_str(" AND memory_type IN (");
            inner.push_str(&vec!["?"; types.len()].join(", "));
            inner.push(')');

[aptend]

Reviewed current head 7ef61b2. The positional Memory compatibility fix, predicate/scope coverage, and memory-type deduplication are good, but one previously requested contract issue is still unresolved and one SDK validation edge remains. Targeted Rust tests passed; 47 sync/async Python SDK tests passed; git diff --check passed.