0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/stores/vectorize/src
Leo 22b24cc40a
fix(core): apply semanticRecall.filter during agent runs (#29418)
## Description

`semanticRecall.filter` worked in `Memory.recall()` but not during
`agent.generate()` or `agent.stream()`. During an agent run, recall
happens in the `SemanticRecall` processor, which never read `filter` and
queried the vector store with the scope filter only. So messages from
threads that didn't match the filter ended up in the prompt.

This PR changes
`packages/core/src/processors/memory/semantic-recall.ts`:

```diff
 query filter
-  scopeFilter
+  filter ? { $and: [scopeFilter, filter] } : scopeFilter   // same as Memory.recall()

 embedding metadata written during agent runs
-  { message_id, thread_id, resource_id, ... }
+  { ...threadMetadata (only when filter is set), message_id, thread_id, resource_id, ... }
```

- The filter applies to both query paths: client-side embedder and
self-embedding stores.
- Embeddings written during agent runs had no thread metadata, so even
with the query fixed, a filter like `{ mode: { $eq: 'work' } }` could
never match messages that agents saved. When a filter is set, the
processor now reads the thread from storage and stores its metadata on
the embedding, as `Memory.saveMessages()` already does. It reads from
storage because durable and recovered runs put only the thread id in the
memory context.
- Without a filter, nothing about writes changes. Some vector stores
reject nested metadata values and this processor only logs a failed
upsert, so the metadata is written only when a filter needs it.
- Docs: added `filter` to the processor reference and a note on the
semantic recall page that messages agents saved before a filter was set
don't match it until they're saved or indexed again.

## Related issue(s)

Closes #29352

## Type of change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [x] Test update

## Checklist

- [x] I have linked the related issue(s) in the description above
- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR

## Evidence

Before = `semantic-recall.ts` from `origin/main`, with the same tests.
After = this branch.

- **Core, real Agent + MockMemory + in-memory vector store that applies
filters**
(`packages/core/src/processors/memory/semantic-recall-filter.test.ts`,
new): generate and stream, filter vs no filter, self-embedding store,
thread scope, durable-shaped context (`thread: { id }` only), thread
metadata written only with a filter.
**Before:** `Tests 7 failed | 2 passed (9)` (the two no-filter cases
pass on both).
  **After:** `Tests 9 passed (9)`.
- **Memory integration, real `Memory` + LibSQL store and vector +
Agent**
(`packages/memory/integration-tests/src/semantic-recall-metadata-filter.test.ts`):
generate and stream; messages saved with `saveMessages()`, by earlier
agent runs, and in a thread the run created with metadata. Also checks
`Memory.recall()` agrees with the agent run.
**Before:** `Tests 6 failed | 2 passed (8)` (the two existing `recall()`
cases pass on both).
  **After:** `Tests 8 passed (8)`.
- **The issue's own repro script** (LibSQL, mock embedder and model),
run against local builds:
  **Before:** `agent prompt contains personal message: true`
  **After:** `agent prompt contains personal message: false`
- Neighbouring core suites (`semantic-recall.test.ts`,
`processor-caching.test.ts`, `memory-config.test.ts`,
`embedding-dimension.test.ts`): 69/69 pass. `@mastra/core` typecheck
passes; oxlint, oxfmt and lint-staged are clean on the changed files.

Not tested: a real DurableAgent run end to end. The durable context
shape is covered by calling the Memory-built processor with `thread: {
id }` only, as `durable-agent.ts` and `finalize-run.ts` set it.

## Merge Danger

**Door:** two-way. A revert restores the old behavior. Embeddings
already written with thread metadata stay in the vector store but are
harmless extra fields.

**Blast radius:** agents with `semanticRecall.filter` configured. They
now recall fewer messages (only matching threads), which is the
documented behavior. Messages saved by older versions have no thread
metadata, so they won't match a filter until re-saved or re-indexed; the
changeset and docs say so. Users without a filter see no change in
queries.

**After merging main (#29826):** main's shared embedding helper now
always stores thread metadata on agent-run embeddings, so this PR no
longer adds its own filter-only metadata read; docs, changeset and the
unit test were updated to match.

**Cloudflare Vectorize (`@mastra/vectorize`):** the scope and user
filter are combined as `{ $and: [...] }` (the same shape
`Memory.recall()` already sends on main), which the Vectorize translator
rejected, so recall with a filter returned nothing there. The translator
now merges a filter that is exactly `{ $and: [...] }` into one object.
Several conditions on one field merge only as one lower plus one upper
bound; other same-field combinations and non-object clauses throw. Not
run against a live Vectorize index; checked against Cloudflare's
metadata-filtering docs and 38 translator tests (Sol reviewed 3 rounds).

## Council review

Rounds: 4

| Seat | Round 1 | Round 2 | Round 3 | Round 4 |
| --- | --- | --- | --- | --- |
| Claude Opus 5.5 | not run | not run | 8.5/10 | 9/10 |
| GPT-6.1 Sol | 9/10 (Tests 8, Code quality 8) | 9.6/10 | 9.5/10 |
9.5/10 |
| Grok 4.7 | empty seat | empty seat | empty seat | empty seat |

Created with Claude Opus 5.5 in T3 Code.

🤖 Generated with [Claude Code](https://claude.com/claude-code)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

## ELI5

Agents now use the configured metadata filter when they search for
relevant messages. This keeps messages from unrelated threads out of the
agent’s prompt. Cloudflare Vectorize can also process the combined
filters used for these searches.

## Changes

- `SemanticRecall` combines the configured `VectorFilter` with the
thread or resource scope filter using `$and`.
- When a filter is configured, the processor reads thread metadata from
storage and writes it to message embeddings. Older embeddings may need
to be saved or indexed again.
- The Vectorize filter translator merges supported top-level `$and`
clauses, including repeated conditions with the same value. It rejects
unsupported combinations on the same field.
- Updated documentation and added tests for `generate()`, `stream()`,
self-embedding queries, and Vectorize filter translation.

## Verification

- Reported: 9/9 core filter tests, 8/8 integration tests, 69/69
neighboring core tests, 38 Vectorize translator tests, and the
`@mastra/core` typecheck passed.
- A real DurableAgent run was not tested end to end. A core test covers
a processor request context that contains only a thread ID.
- Live Cloudflare Vectorize testing: not available.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
History 2026-11-10 18:19:59 -05:00
..
vector fix(core): apply semanticRecall.filter during agent runs (#29418) 2026-11-10 18:19:59 -05:00
index.ts chore(rag): move vector prompts to individual store packages (#3964) 2025-04-29 15:12:19 -04:00