feat(hindsight): use explicit tag filters for auto-prefetch

[poruru-code]

Summary

Add explicit tag filters for Hindsight automatic prefetch recall.

This changes auto-prefetch to use request-side tag filters instead of the earlier metadata-based filtering approach, aligning the implementation with the intended filtering surface.

Related

• Follow-up to feat(hindsight): richer session-scoped retain metadata (salvage of #6290) #13987.

Changes

• add recall_prefetch_tags
• add recall_prefetch_tags_match
• make auto-prefetch use recall_prefetch_tags / recall_prefetch_tags_match when configured
• fall back to existing recall_tags / recall_tags_match when prefetch-specific tags are unset
• do not combine prefetch-specific tags with generic recall tags
• keep manual hindsight_recall unchanged
• keep auto-retain and manual hindsight_retain unchanged
• update tests and docs

Behavior

• recall_prefetch_tags only affects automatic prefetch recall
• when unset, auto-prefetch behaves as before and uses recall_tags
• when set, auto-prefetch uses only the prefetch-specific selector
• reflect mode remains unchanged

Notes

This PR is intentionally narrow:

• read path only
• no retain-side behavior change
• no manual recall API change
• no automatic session-derived scoping

recall_prefetch_tags only matches memories that already carry those tags. It does not backfill old memories, infer tags from metadata, or change retain behavior.

For strict scoping, use _strict tag match modes, since non-strict any / all modes may still include untagged memories.

Testing

Passed:

• uv run scripts/run_tests.sh tests/plugins/memory/test_hindsight_provider.py
• uv run scripts/run_tests.sh tests/agent/test_memory_user_id.py

Also validated against a real Hindsight Cloud bank:

• auto-prefetch hits via recall_prefetch_tags
• manual hindsight_recall remains governed by generic recall_tags
• auto-prefetch falls back to recall_tags when prefetch-specific tags are unset

[Copilot]

Pull request overview

Adds an opt-in metadata scoping mechanism for Hindsight automatic prefetch recall so that recalled memories can be locally filtered to the current session’s stable identity metadata (reducing cross-session/bank leakage) without changing manual hindsight_recall behavior.

Changes:

• Introduces config keys recall_prefetch_metadata_fields and recall_prefetch_metadata_strict, including normalization/allowlisting and boolean parsing.
• Builds an “active metadata scope” from provider session state and filters auto-prefetch recall results (with strict vs non-strict semantics, and a no-op when scope is empty).
• Adds focused unit tests and documents the new configuration in the Hindsight README.

Reviewed changes

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

File	Description
plugins/memory/hindsight/__init__.py	Implements metadata field normalization, active scope construction, and local filtering for auto-prefetch recall results (ignored for reflect).
tests/plugins/memory/test_hindsight_provider.py	Adds normalization tests and comprehensive prefetch filtering behavior tests (strict/non-strict/empty-scope/reflect/manual-tool unaffected).
plugins/memory/hindsight/README.md	Documents the new auto-prefetch-only metadata scoping keys and their semantics.

---

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

[nicoloboschi]

for filtering you must use tags, not metadata

[poruru-code]

@nicoloboschi
Thanks — I reworked this to use explicit tag filters for auto-prefetch on the request path.

The metadata-based post-filtering path is gone. Auto-prefetch now uses:

• recall_prefetch_tags
• recall_prefetch_tags_match

When these are set, they apply only to auto-prefetch. When they are unset, auto-prefetch falls back to the existing recall_tags / recall_tags_match behavior.

I intentionally kept the scope narrow:

• no manual hindsight_recall API change
• no auto-retain change
• no manual hindsight_retain change
• no session-derived tagging on the write path

I also updated the targeted tests and docs, and validated the resulting behavior against a real Hindsight Cloud bank.

[teknium1]

Thanks for narrowing this to request-side tag filtering after the earlier review. Current main still applies recall_tags to auto-prefetch at plugins/memory/hindsight/__init__.py:1509-1511 and to manual hindsight_recall at plugins/memory/hindsight/__init__.py:1738-1740; the dedicated prefetch selector remains a real missing capability.

The current schema also has no prefetch-specific tag fields (plugins/memory/hindsight/__init__.py:990-998). The proposed separation preserves the manual path while making auto-prefetch independently configurable. No correctness issue was identified in the revised tag-filter approach.

This is an automated hermes-sweeper review.