Haystack Mem0MemoryStore 深度指南基于 Mem0 云 API 的长期记忆存储层【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystackMem0MemoryStore 是 Haystack 生态中面向Mem0 云 API的记忆存储Memory Store实现它把ChatMessage对象写入 Mem0、并按查询相关性检索长期记忆为 Agent 与 RAG 流水线提供跨会话的持久化记忆能力。本篇以 version-2.22 experiments-api 中的 Mem0MemoryStore 参考文档 为核心骨架结合仓库内 mem0memorystore.mdx、Mem0MemoryRetriever、Mem0MemoryWriter 与 Mem0 Memory Tools 文档带你完整掌握该存储层的初始化、写入、检索、删除、过滤器归一化与流水线集成方案。一、记忆存储层在 Haystack 中的定位Haystack 的记忆体系以Memory Store为数据底座它负责记忆的持久化写入与检索而Mem0MemoryRetriever、Mem0MemoryWriter以及Mem0MemoryRetrieverTool/Mem0MemoryWriterTool这些组件则围绕同一存储实例工作。仓库文档明确说明Mem0MemoryStore正是这一共享数据层见 mem0memorystore.mdx。在 v2.22 时代该实现以haystack_experimental.memory_stores.mem0.memory_store模块的形式出现见 实验 API 参考文档类全名为haystack_experimental.memory_stores.mem0.memory_store.Mem0MemoryStore后续随集成成熟正式用法迁移到mem0-haystack包代码导入路径为haystack_integrations.memory_stores.mem0见 mem0memorystore.mdx。两处 API 签名保持一致本文以参考文档的完整签名为准展开讲解。二、安装与初始化2.1 安装集成包Mem0 集成以独立包形式分发需要先安装pip install mem0-haystack然后配置 Mem0 云 API 密钥export MEM0_API_KEYyour-mem0-api-key2.2 构造函数签名参考文档给出的初始化签名如下见 参考文档init小节def __init__(*, api_key: Secret Secret.from_env_var(MEM0_API_KEY))关键点api_key是唯一的初始化参数类型为Secret默认值Secret.from_env_var(MEM0_API_KEY)表示只要设置了MEM0_API_KEY环境变量即可零配置实例化也支持显式传入例如Mem0MemoryStore(api_keySecret.from_token(...))。从源码签名可以推断该存储层把密钥管理完全交给 Haystack 的Secret机制避免 API Key 以明文形式散落在业务代码与序列化结果中。创建实例from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore store Mem0MemoryStore() # 自动从 MEM0_API_KEY 读取密钥由于user_id、run_id、agent_id等都是运行时参数而非初始化参数单个 store 实例即可服务多个用户、多个会话与多个 Agent无需为每个用户单独创建存储对象。2.3 序列化支持to_dict / from_dict参考文档提供了两个序列化方法见 to_dict 与 from_dictdef to_dict() - dict[str, Any] classmethod def from_dict(cls, data: dict[str, Any]) - Mem0MemoryStoreto_dict将存储配置序列化为字典from_dict则是反向反序列化的类方法。这保证了Mem0MemoryStore可以嵌入到 Haystack 的 YAML/JSON 流水线描述中配合Pipeline.loads()/Pipeline.dump()完成整条记忆增强流水线的持久化与复用。三、写入记忆add_memories3.1 完整签名与参数参考文档给出的写入方法签名见 add_memories 小节def add_memories(*, messages: list[ChatMessage], infer: bool True, user_id: str | None None, run_id: str | None None, agent_id: str | None None, async_mode: bool False, **kwargs: Any) - list[dict[str, Any]]参数说明汇总参数类型默认值说明messageslist[ChatMessage]必填带记忆元数据的 ChatMessage 列表inferboolTrue是否让 Mem0 从消息中自动推断事实为False时整条消息原文作为记忆写入user_idstr \| NoneNone记忆存取的用户级作用域 IDrun_idstr \| NoneNone记忆存取的会话/运行级作用域 IDagent_idstr \| NoneNone记忆存取的 Agent 级作用域 ID若想让 Mem0 存储助手的聊天消息必须设置agent_idasync_modeboolFalse是否异步写入为True时方法立即返回记忆在后台写入**kwargsAny—透传给 Mem0client.add方法的额外参数返回值是包含memory_id与记忆内容的字典列表。3.2 关于 metadata 的两点重要约束参考文档明确给出两条注意事项见 add_memories 参数说明列表内每条ChatMessage.meta会被忽略——因为 Mem0 不允许在消息列表级别为每条消息单独传 metadata整批记忆的元数据通过metadata关键字参数传入即在**kwargs中传递metadata...。这决定了使用模式如果要对写入的记忆附加自定义元数据例如来源标签、业务字段应放在add_memories(..., metadata{...})层面而不是散落在每条ChatMessage.meta中。3.3 写入示例from haystack.dataclasses import ChatMessage from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore store Mem0MemoryStore() # inferFalse原文直接作为记忆 store.add_memories( messages[ChatMessage.from_user(Alice prefers concise Python examples.)], user_idalice, inferFalse, ) # inferTrue让 Mem0 从一整轮 Agent 对话中自动提炼记忆 store.add_memories( messages[ ChatMessage.from_user(My name is Alice and I prefer concise Python examples.), ], user_idalice, run_iddocs-assistant-session-1, inferTrue, metadata{source: onboarding-conversation}, # 整批记忆的元数据 )infer参数的选取原则见 mem0memorystore.mdxinferTrue适合写入包含用户消息、工具上下文与最终回复在内的完整 Agent 轮次由 Mem0 自动抽取事实inferFalse适合上游组件已经挑选好精确记忆文本的场景直接原文落库避免重复抽取。四、检索记忆search_memories 与 search_memories_as_single_message4.1 search_memories 完整签名参考文档签名见 search_memories 小节def search_memories(*, query: str | None None, filters: dict[str, Any] | None None, top_k: int 5, user_id: str | None None, run_id: str | None None, agent_id: str | None None, include_memory_metadata: bool False, **kwargs: Any) - list[ChatMessage]参数说明汇总参数类型默认值说明querystr \| NoneNone检索查询文本不传则返回作用域内全部记忆filtersdict \| NoneNoneHaystack 风格过滤器作用于检索范围top_kint5最大返回条数user_id/run_id/agent_idstr \| NoneNone记忆存取作用域 IDagent_id同样用于存取助手消息include_memory_metadataboolFalse是否在返回的 ChatMessage 中携带 Mem0 相关元数据**kwargsAny—透传给 Mem0 客户端参数作用域规则重要参考文档强调若未提供filters则user_id、run_id、agent_id三者至少设置一个若提供了filters检索范围被限定在过滤器内其他 ID 参数会被忽略见 search_memories 说明。kwargs 路由规则传入query时 kwargs 透传给 Mem0 的search方法不传query时透传给get_all方法见 参考文档说明。4.2 include_memory_metadata 的行为include_memory_metadata控制返回消息的meta内容见 参考文档说明为True时ChatMessage.meta中的mem0_memory_metadata键会包含 Mem0 相关元数据如memory_id、score等为False时ChatMessage.meta仅包含用户自定义元数据。配合 Mem0MemoryRetriever 文档 可以看到一致的行为描述用户自定义元数据进入metaMem0 检索字段memory_id、user_id、score、时间戳归入meta[mem0]。4.3 search_memories_as_single_message当检索结果需要作为单条消息注入模型上下文时可调用此方法签名见 参考文档def search_memories_as_single_message(*, query: str | None None, filters: dict[str, Any] | None None, top_k: int 5, user_id: str | None None, run_id: str | None None, agent_id: str | None None, **kwargs: Any) - ChatMessage参数语义与search_memories完全一致含无 filters 时至少一个 ID的约束只是返回值从list[ChatMessage]变为单个ChatMessage便于直接拼接进对话上下文。4.4 检索示例# 语义检索返回与查询最相关的记忆 memories store.search_memories( queryWhat does Alice prefer?, user_idalice, top_k3, ) print([msg.text for msg in memories]) # 作用域内全量召回queryNone all_memories store.search_memories(queryNone, user_idalice) print([msg.text for msg in all_memories]) # 单条消息形式返回 memory_msg store.search_memories_as_single_message( queryWhat does Alice prefer?, user_idalice, top_k3, )五、删除记忆delete_all_memories 与 delete_memory5.1 批量删除签名见 参考文档 delete_all_memories 小节def delete_all_memories(*, user_id: str | None None, run_id: str | None None, agent_id: str | None None, **kwargs: Any) - None约束同样明确user_id、run_id、agent_id至少设置一个否则无法确定删除范围kwargs透传给 Mem0 客户端的delete_all方法。典型场景是用户注销或数据合规清理时按用户维度清空记忆。5.2 单条删除签名见 参考文档 delete_memory 小节def delete_memory(memory_id: str, **kwargs: Any) - None按memory_id精确删除单条记忆kwargs透传给 Mem0 客户端的delete方法。memory_id可从add_memories的返回值或search_memories返回的 Mem0 元数据mem0_memory_metadata.memory_id中取得用于纠错与去重维护。六、过滤器归一化normalize_filters参考文档在类内提供了一个静态方法见 normalize_filters 小节staticmethod def normalize_filters(filters: dict[str, Any]) - dict[str, Any]其职责是将 Haystack 过滤器转换为 Mem0 过滤器。这意味着上层如Mem0MemoryRetriever传入的 Haystack 风格过滤条件会在存储层内被翻译为 Mem0 可识别的格式。Haystack 过滤器的通用语法可参考仓库文档 Metadata Filtering。需要说明的是在参考文档对应版本中filters参数的语义描述同时引用了 Haystack 过滤与 Mem0 过滤两套概念分别见 search_memories 与 search_memories_as_single_message 的说明使用时请以当前安装的mem0-haystack版本对应的参考文档为准。七、作用域用多实体 ID 实现多租户记忆Mem0 支持通过四类实体 ID 收敛记忆读写范围见 mem0memorystore.mdx实体 ID语义典型场景user_id用户级单用户长期偏好与事实run_id会话/运行级单次会话、单轮对话上下文agent_idAgent 级单个 Agent 专属记忆app_id应用级整个应用共享记忆这些 ID 全部是运行时参数因此同一个Mem0MemoryStore实例可以为多用户、多会话、多 Agent 服务写读时传入一致的 ID 组合即可隔离数据store.add_memories( messages[ChatMessage.from_user(Alice is working on a documentation search system.)], user_idalice, run_iddocs-assistant-session-1, inferTrue, ) memories store.search_memories( queryWhat project is Alice working on?, user_idalice, run_iddocs-assistant-session-1, ) print([msg.text for msg in memories])特别提醒若需要 Mem0 存储助手侧的聊天消息而不仅是用户消息必须设置agent_id见 参考文档说明。八、在流水线与 Agent 中落地Mem0MemoryStore很少单独使用通常作为数据层被Mem0MemoryWriter、Mem0MemoryRetriever及两个 Agent 工具共享。8.1 写入端Mem0MemoryWriterMem0MemoryWriter把ChatMessage列表写入 store通常位于记忆增强流水线的末尾Agent 或 Chat Generator 之后输出memories_written写入条数。其infer初始化参数与 store 的infer语义一致见 mem0memorywriter.mdx。与 Agent 串联的完整示例from haystack import Pipeline from haystack.components.agents import Agent from haystack.components.generators.chat import OpenAIChatGenerator from haystack.components.generators.utils import print_streaming_chunk from haystack.dataclasses import ChatMessage from haystack_integrations.components.writers.mem0 import Mem0MemoryWriter from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore store Mem0MemoryStore() pipeline Pipeline() pipeline.add_component( agent, Agent( chat_generatorOpenAIChatGenerator(modelgpt-4o-mini), system_prompt( Answer the user and preserve durable user facts or preferences for future conversations. ), streaming_callbackprint_streaming_chunk, ), ) pipeline.add_component(writer, Mem0MemoryWriter(memory_storestore, inferTrue)) pipeline.connect(agent.messages, writer.messages) result pipeline.run( { agent: { messages: [ ChatMessage.from_user( My name is Alice and I prefer concise Python examples., ), ], }, writer: { user_id: alice, }, }, ) print(result[writer][memories_written])8.2 检索端Mem0MemoryRetrieverMem0MemoryRetriever从 store 检索记忆并以 systemChatMessage返回通常位于 Agent 之前把长期记忆注入模型上下文见 mem0memoryretriever.mdx。它把 store 的search_memories能力封装为流水线组件query支持字符串或NoneNone时返回作用域内全部记忆filters与 ID 参数同时提供时按AND合并。from haystack_integrations.components.retrievers.mem0 import Mem0MemoryRetriever from haystack_integrations.memory_stores.mem0 import Mem0MemoryStore store Mem0MemoryStore() store.add_memories( messages[ChatMessage.from_user(Alice prefers concise Python examples.)], user_idalice, inferFalse, ) retriever Mem0MemoryRetriever(memory_storestore, top_k3) result retriever.run(queryanswer style, user_idalice) for memory in result[memories]: print(memory.text)8.3 Agent 原生工具Mem0MemoryRetrieverTool / Mem0MemoryWriterTool当 Agent 需要自主读写记忆时可把两个现成工具挂载到Agent.tools见 mem0memorytools.mdxretrieve_memoriesMem0MemoryRetrieverTool向 LLM 暴露query与top_kAgent 省略query或传null时返回注入作用域内的全部记忆store_memoryMem0MemoryWriterTool向 LLM 暴露text与infer默认inferFalse保证 Agent 精确保存自己挑选的记忆文本。两个工具默认通过inputs_from_state{user_id: user_id}从 Agent State 注入user_id无需把用户 ID 暴露给 LLM 作为工具调用参数。若要注入更多实体 ID可扩展state_schema并用inputs_from_state完成映射例如{user_id: user_id, conversation_id: run_id}会把 State 中的conversation_id传给工具的run_id参数。九、最佳实践与注意事项作用域必须明确写入与检索至少提供一个实体 ID设计多租户应用时建议统一约定user_idrun_id或agent_id的组合约定避免跨用户记忆串扰。infer按需选择整轮对话落库用inferTrue让 Mem0 提炼事实上游已筛选好精确文本时用inferFalse原文存储兼顾质量与成本。metadata 走整批通道add_memories不支持逐条ChatMessage.meta自定义元数据统一通过metadata关键字传入。助手消息依赖agent_id需要持久化助手输出时务必设置agent_id。检索元数据按需开启只有需要memory_id、score等 Mem0 字段做去重、排序或审计时才开启include_memory_metadataTrue。删除即合规用户注销时用delete_all_memories(user_id...)清理单条纠错用delete_memory(memory_id...)。十、进一步阅读Mem0MemoryStore 参考文档v2.22 实验 APIMem0MemoryStore 使用指南Mem0MemoryRetriever 组件文档Mem0MemoryWriter 组件文档Mem0 Memory Tools 文档Metadata Filtering 过滤语法【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考