feat(valkey): metadata_filter fields not indexed in memory_index FT schema

快速结论：当 CrewAI 使用 Valkey 作为向量记忆后端并通过 metadata_filter 过滤记忆时，过滤子句引用了 memory_index FT schema 中不存在的元数据字段，导致 feat(valkey): metadata_filter fields not indexed in memory_index FT schema；优先排查 schema 中实际定义了哪些可索引字段。

适用环境：Issue 已确认工具为 CrewAI（含 ValkeyStorage 向量记忆后端）；涉及文件 lib/crewai/src/crewai/memory/storage/valkey_storage.py。Issue 中未给出具体的操作系统、Python、CUDA、显卡或依赖版本，故不作补充。

最快修复方案：暂无确认的一步修复方案。Issue 明确指出该问题被推迟到后续 PR 处理，评论中仅表示“Fix being added to PR: #5703”，未提供已验证的修复步骤。

注意事项：Issue 中给出的两个修复方向（A：把元数据字段物化进 FT 索引；B：在 FT.SEARCH 之外做事后过滤）都还只是方案选项，未经确认落地；Issue 最终也以 repository cleanup 为由关闭，若问题仍存在需要新开 Issue 并引用本 Issue。

问题场景

在使用 CrewAI 的 Valkey 向量记忆后端（ValkeyStorage）进行记忆检索时，调用 ValkeyStorage._vector_search() 内部会构造带 metadata_filter 的查询，例如 @key:value 这类对任意元数据键的过滤条件。问题出现在向量检索环节：查询把元数据字段当作 FT schema 中可索引的字段来引用，但 memory_index 索引实际上并没有这些字段。

涉及代码位置在 lib/crewai/src/crewai/memory/storage/valkey_storage.py 第 513–519 行和第 1237–1245 行附近。该问题是在审查 PR #5703（ValkeyStorage 向量记忆后端，part 4/4）时提出的。

报错原文

feat(valkey): metadata_filter fields not indexed in memory_index FT schema

Issue 描述中说明，由于 metadata_filter 引用的字段未被索引，FT.SEARCH 的结果不能被真正限制，表现为“either error or silently return wrong results”（报错或静默返回错误结果）。

原因分析

根本原因是查询逻辑与索引 schema 不一致：

memory_index 的 FT schema 只定义了以下字段：

VectorField("embedding")
TagField("scope")
TagField("categories")
NumericField("created_at")
NumericField("importance")

而 _vector_search() 中构造的 metadata_filter 子句却引用了任意元数据键字段（例如 @key:value）。这些字段没有出现在索引 schema 中，RediSearch/Valkey 的 FT.SEARCH 无法基于未索引字段进行过滤，于是出现报错或静默返回不符合过滤条件的结果。

评论中补充了同类问题的普遍性：FT schema 定义了固定的一组索引字段，但应用代码假设任意元数据键都可查询。这属于“把向量搜索外挂在通用存储上”时经常遇到的契约不一致问题。

环境排查

确认当前 CrewAI 版本是否包含 ValkeyStorage 向量记忆后端，以及 valkey_storage.py 对应行号附近是否存在 metadata_filter 构造逻辑。
确认 Valkey（或 Redis Stack / RediSearch 兼容服务）实例的版本及其 FT.SEARCH 与索引能力支持情况；Issue 未给出具体版本号。
检查 memory_index 的实际 schema 定义，核对其中是否存在 TagField / NumericField 等字段与你传入的 metadata_filter 键能对应上。
确认 Python、PyTorch、CUDA、显卡等环境信息；Issue 中未提供，可暂不作为该问题的直接排查项。
确认是否基于 PR #5703 或其衍生版本运行，因为该问题正是从该 PR 的 review 中提出的。

解决步骤

先复现并定位：在调用 ValkeyStorage._vector_search() 时带上一个使用了自定义元数据键的 metadata_filter，观察 FT.SEARCH 是报错还是返回了未被过滤的结果。
对照 memory_index 的 schema，列出当前真正被索引的字段（如 scope、categories、created_at、importance），与 metadata_filter 中引用的字段做差异比对。
作为临时规避（可优先尝试）：只使用 schema 中已索引的字段作为过滤条件，例如 scope、categories、created_at、importance；避免使用未索引的自定义元数据键。
若必须按任意元数据键过滤，参考 Issue 给出的两个方向处理：
Option A —— 把必要的元数据字段物化进 FT 索引（按类型添加为 TagField 或 NumericField），并同步更新 schema 构造逻辑。这需要预先定义一组已知的元数据键，或动态管理索引 schema。
Option B —— 从 _vector_search() 的 FT 查询中移除 metadata 子句，改为在 FT.SEARCH 返回结果之后应用 metadata_filter 作为 post-filter，再返回最终 hits。该方式更简单，但从 Valkey 取回的文档数可能多于严格所需。
关注修复落地情况：Issue 评论中提到 “Fix being added to PR: https://github.com/crewAIInc/crewAI/pull/5703”，可跟踪该 PR 的合并与发版状态。该 Issue 本身已因 repository cleanup 关闭，若问题仍存在需新开 Issue 并引用 #5795。