3.4 · 会话作用域与过滤器（Session Scoping and Filters）

会话作用域与过滤器

会话作用域与过滤器

相关源文件

本章引用的主要源码文件：

• docs/api-reference.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/frameworks/llamaindex-react.mdx
• docs/cookbooks/integrations/agents-sdk-tool.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
• docs/migration/api-changes.mdx
• docs/migration/oss-to-platform.mdx
• docs/open-source/python-quickstart.mdx
• docs/platform/features/advanced-retrieval.mdx
• docs/platform/features/async-client.mdx
• docs/platform/features/contextual-add.mdx
• docs/platform/features/criteria-retrieval.mdx
• docs/platform/features/custom-categories.mdx
• docs/platform/features/custom-instructions.mdx
• docs/platform/features/direct-import.mdx
• docs/platform/features/entity-scoped-memory.mdx
• docs/platform/features/v2-memory-filters.mdx

会话作用域与过滤器控制着 Mem0 中的内存隔离与检索精度。会话标识符（user_id、agent_id、app_id、run_id）将内存划分为互不重叠的命名空间，而元数据过滤器则支持在这些分区内进行细粒度查询。该系统可防止用户间的数据泄露，组织多智能体工作流，并支持临时会话上下文。

核心会话标识符

Mem0 通过层级化的会话标识符来强制实施内存隔离。在开源 SDK 中，系统会校验这些标识符，确保任何与内存存储交互的操作都至少提供一个标识符。

校验逻辑： 如果未提供任何实体参数，Memory 类会拒绝操作。该逻辑由 _reject_top_level_entity_params 中的 ENTITY_PARAMS 检查 mem0/memory/main.py:100-111 以及 _validate_and_trim_entity_id 中的标识符规范化 mem0/memory/main.py:113-141 共同强制实施。

来源： mem0/memory/main.py:100-141、docs/llms.txt:34-51、docs/platform/features/v2-memory-filters.mdx:32-41、docs/cookbooks/essentials/entity-partitioning-playbook.mdx:22-39

会话作用域架构

标识符校验与处理

系统确保标识符是有效的字符串，且不含内部空白字符，以防止在向量/图存储后端中出现查询注入或格式化错误。

图示：实体 ID 校验流程

来源： mem0/memory/main.py:103-111、mem0/memory/main.py:113-141

作用域操作中的数据流

当添加或搜索内存时，会话标识符会通过 Memory 类流入 VectorStore 和 GraphMemory 组件。

图示：作用域内存数据流

来源： mem0/memory/main.py:236-267、mem0/memory/main.py:758-856、mem0/memory/graph_memory.py:65-94

元数据过滤

除了核心会话标识符之外，Mem0 还支持任意元数据过滤。元数据作为载荷的一部分存储在向量存储中，可以使用简单的相等性比较或高级运算符进行查询。

在向量存储中的实现

在搜索过程中，filters 字典会直接传递给 vector_store.search 方法 mem0/memory/main.py:875-880。

• 开源版： 过滤器通常由底层向量数据库（例如 Qdrant、Chroma）处理。
• 平台版： 支持包含逻辑运算符的丰富 JSON 结构过滤器 docs/platform/features/v2-memory-filters.mdx:18-30。

过滤器运算符（平台版）

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

多智能体隔离

在多智能体系统中，通过将 user_id 与 agent_id 结合使用来实现隔离。这可以防止某个智能体访问属于另一个智能体的内存，即使它们共享同一个用户。

分区策略

1. 用户级分区： agent_id 为 null 的内存。存储全局用户偏好。
2. 智能体级分区： 同时设置了 user_id 和 agent_id 的内存。存储该智能体特有的交互历史。

常见陷阱： 使用 {"AND": [{"user_id": "alice"}, {"agent_id": "bot"}]} 进行搜索时，只会返回在 add() 调用中同时显式设置了这两个字段的内存。如果某条内存仅使用 user_id 添加，则不会出现在过滤了非空 agent_id 的搜索结果中 docs/platform/features/v2-memory-filters.mdx:61-63。

来源： docs/platform/features/v2-memory-filters.mdx:32-63、docs/cookbooks/essentials/entity-partitioning-playbook.mdx:76-93

图内存作用域

图内存使用相同的过滤器来约束实体和关系的提取与检索。

作用域提取

当调用 graph.add() 时，会话过滤器（例如 user_id、agent_id）会附加到图中创建的每个节点和关系上 mem0/memory/graph_memory.py:86-94。这确保了图结构与向量存储的分区边界保持一致。

作用域检索

GraphMemory.search() 方法在执行实体匹配或关系遍历之前，会使用提供的过滤器来缩小搜索空间 mem0/memory/graph_memory.py:96-130。

来源： mem0/memory/graph_memory.py:86-130、mem0/memory/main.py:835-843

技术实现细节

记忆 类与过滤器

在 mem0/memory/main.py 中，search 和 get_all 方法是进行过滤检索的主要入口点。

• search(query, filters, ...)：结合语义向量搜索与元数据过滤 mem0/memory/main.py:758-856。
• get_all(filters, ...)：检索所有符合过滤条件的内存，无需查询字符串 mem0/memory/main.py:653-709。
• delete_all(filters, ...)：根据过滤匹配结果执行批量删除 mem0/memory/main.py:911-948。

历史记录与作用域

SQLiteManager 会跟踪内存变更的历史记录。虽然历史记录主要通过 memory_id 进行跟踪，但 actor_id（通常是特定参与者的名称或标识符）可用于过滤历史记录 mem0/memory/storage.py:150-191。

来源： mem0/memory/main.py:653-709、mem0/memory/main.py:911-948、mem0/memory/storage.py:150-191

使用模式总结

来源： mem0/memory/main.py:281-948、docs/platform/features/v2-memory-filters.mdx:69-102、docs/platform/features/async-client.mdx:78-81