11.4 · 高级筛选（Advanced Filtering）

长期记忆与上下文管理 · 聚焦本章的模块关系、源码依据与实现要点。

项目Mem0 章节11.4 状态全文译文模块界面与交互、模型调用与提供方适配、测试、发布与运维、入库与解析

项目要点页2.5 参考项目项目章节目录Mem0 DeepWiki 原始章节Advanced Filtering 上一章11.3 下一章11.5

源码线索

docs/components/vectordbs/dbs/milvus.mdx
docs/cookbooks/essentials/building-ai-companion.mdx
docs/cookbooks/essentials/controlling-memory-ingestion.mdx
docs/cookbooks/essentials/entity-partitioning-playbook.mdx
docs/cookbooks/essentials/exporting-memories.mdx
docs/cookbooks/integrations/healthcare-google-adk.mdx
docs/cookbooks/integrations/openai-tool-calls.mdx
docs/cookbooks/overview.mdx
docs/docs.json
docs/llms.txt

模块标签

界面与交互
模型调用与提供方适配
测试、发布与运维
入库与解析
文档对象与元数据

章节正文

高级筛选

原始 DeepWiki 页面https://deepwiki.com/mem0ai/mem0/11.4-advanced-filtering

高级过滤

概述

Mem0 的过滤系统在两个层级上运作：

会话作用域限定：基于 user_id、agent_id、app_id 和 run_id 自动过滤，按上下文隔离记忆。docs/platform/features/entity-scoped-memory.mdx:29-35
元数据过滤：使用比较运算符（例如 eq、ne、gt、in、contains）和逻辑组合（AND、OR、NOT）对自定义元数据字段进行高级过滤。docs/platform/features/v2-memory-filters.mdx:20-30

过滤系统既支持简单的等值匹配，也支持带运算符的复杂查询。

来源：mem0/memory/main.py:758-831、docs/platform/features/v2-memory-filters.mdx:18-30

过滤处理架构

下图展示了过滤条件如何从高级的 Memory 类流入 Qdrant 或 MilvusDB 等向量存储实现。

逻辑流程：从自然语言到代码实体空间

Mem0 · 逻辑流程：从自然语言到代码实体空间 · 图 1

来源：mem0/memory/main.py:87-165、mem0/memory/main.py:809-816、mem0/vector_stores/qdrant.py:270-300、mem0/vector_stores/milvus.py:139-155

基于会话的过滤

会话标识符会自动限定所有记忆操作的范围。在开源实现中，所有查询至少需要一个会话标识符，以确保数据隔离。mem0/memory/main.py:152-158

会话标识符类型

标识符	用途	示例用例
`user_id`	单个用户上下文	用户偏好、个人历史
`agent_id`	AI 智能体上下文	智能体特定知识、品牌语调
`app_id`	应用上下文	不同应用的多租户隔离
`run_id`	对话会话	单个对话线程、临时上下文

会话过滤校验

_build_filters_and_metadata 函数（位于 mem0/memory/main.py:87-165）强制要求至少提供一个会话标识符，以防止跨用户数据泄露：

if not session_ids_provided:
    raise Mem0ValidationError(
        message="At least one of 'user_id', 'agent_id', or 'run_id' must be provided.",
        error_code="VALIDATION_001",
        ...
    )

来源：mem0/memory/main.py:152-158、docs/platform/features/entity-scoped-memory.mdx:29-35

元数据过滤运算符

Mem0 支持对元数据字段使用丰富的比较运算符。这些运算符会被特定的 VectorStore 提供程序转换为其原生查询语言。

运算符参考

运算符	描述	代码实现
`eq`	等于	`mem0/memory/main.py:780`
`ne`	不等于	`mem0/memory/main.py:781`
`gt` / `gte`	大于（或等于）	`mem0/memory/main.py:782-783`
`lt` / `lte`	小于（或等于）	`mem0/memory/main.py:784-785`
`in`	值在列表中	`mem0/memory/main.py:786`
`contains`	子串匹配	`mem0/memory/main.py:788`
`icontains`	不区分大小写匹配	`mem0/memory/main.py:789`

来源：mem0/memory/main.py:780-795、docs/platform/features/v2-memory-filters.mdx:32-60

逻辑运算符

通过使用 AND、OR 和 NOT 逻辑运算符组合过滤条件，可以构建复杂查询。mem0/memory/main.py:793-795

实现示例：Qdrant

在 Qdrant._create_filter 中，过滤条件会被递归解析为 qdrant_client.models.Filter 对象。mem0/vector_stores/qdrant.py:270-300

Mem0 · 实现示例：Qdrant · 图 2

来源：mem0/vector_stores/qdrant.py:270-300、tests/vector_stores/test_qdrant.py:172-185

各提供程序的具体实现

每个向量存储都实现了自己的过滤条件转换逻辑，以处理底层数据库的特定要求。

1. Qdrant

Qdrant 使用 qdrant_client.models 包中的 Filter、FieldCondition 和 MatchValue 类。mem0/vector_stores/qdrant.py:6-22

索引创建：Qdrant 在集合初始化期间会自动为 user_id、agent_id、run_id 和 actor_id 创建载荷索引，以优化过滤性能。mem0/vector_stores/qdrant.py:165-177
混合搜索：Qdrant 通过 bm25 稀疏向量槽支持 BM25 混合搜索，该功能可与元数据过滤配合使用。mem0/vector_stores/qdrant.py:146-154

2. Milvus

Milvus 将过滤条件转换为针对 metadata JSON 字段的布尔表达式字符串。mem0/vector_stores/milvus.py:139-155

过滤字符串：生成类似 (metadata["user_id"] == "alice") and (metadata["category"] == "work") 的字符串。tests/vector_stores/test_milvus.py:100-108
混合搜索：Milvus 使用 text 字段和 sparse 向量字段（由 BM25 函数填充）进行混合搜索，该功能可与元数据过滤结合使用。mem0/vector_stores/milvus.py:84-116

3. ChromaDB

ChromaDB 使用 $where 子句字典格式进行元数据过滤。tests/vector_stores/test_chroma.py:66-69

单个过滤条件：转换为 {"user_id": {"$eq": "alice"}}。tests/vector_stores/test_chroma.py:92
多个过滤条件：使用逻辑键，例如 {"$and": [{"user_id": {"$eq": "alice"}}, {"agent_id": {"$eq": "agent1"}}]}。tests/vector_stores/test_chroma.py:66

来源：mem0/vector_stores/qdrant.py:270-300、mem0/vector_stores/milvus.py:139-155、tests/vector_stores/test_chroma.py:66-69、mem0/vector_stores/milvus.py:84-116

过滤应用管线

下面的序列图展示了过滤条件从客户端调用，经过内部处理逻辑，最终到向量存储执行的转换过程。

序列：从搜索到存储

Mem0 · 序列：从搜索到存储 · 图 3

来源：mem0/memory/main.py:809-816、mem0/memory/main.py:832-850、mem0/vector_stores/qdrant.py:215-225

使用模式总结

多值元数据变通方案

对于某些平台上不支持 in 运算符的元数据过滤，可以使用 OR 逻辑运算符来实现相同效果。docs/platform/features/v2-memory-filters.mdx:104-116

filters = {
    "OR": [
        {"metadata": {"type": "semantic"}},
        {"metadata": {"type": "episodic"}}
    ]
}

通配符匹配

可以使用 * 通配符匹配特定字段的任何非空值，这对于验证元数据是否存在非常有用。docs/platform/features/v2-memory-filters.mdx:61-63

# 匹配任何非空的 user_id
filters = {"user_id": "*"}

来源：docs/platform/features/v2-memory-filters.mdx:61-63、docs/platform/features/v2-memory-filters.mdx:104-116