人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载导读MemoryRetrievalComponent是 openJiuwen agent-core 工作流组件体系中用于长期记忆检索的核心可组合组件它把LongTermMemory的检索能力封装成工作流图中的标准节点让开发者可以在 Workflow 编排中直接以声明式方式用一句查询字符串换取片段记忆与历史摘要。本文以 API 文档 为骨架结合 源码实现、底层记忆引擎 long_term_memory.py 与 单元测试完整讲解配置参数、输入输出契约、执行调用链、错误处理与实战接入方式。读完本文你将掌握如何在 Agent 工作流中接入长期记忆检索节点并理解其背后的相似度过滤、作用域隔离与结果格式化机制。一、组件定位从工作流组件体系看 MemoryRetrievalComponentopenJiuwen agent-core 的工作流组件遵循可组合Composable 可执行Executable的双层设计ComponentComposable负责图构建通过add_component(graph, node_id, wait_for_all)将组件挂载到工作流图上ComponentExecutable负责运行时执行通过invoke / stream / collect / transform四种 I/O 模式完成业务逻辑见 component.py。MemoryRetrievalComponent继承自ComponentComposable对应可执行类为MemoryRetrievalExecutable继承自ComponentExecutable实现的是invoke批进批出模式。它属于resource资源类组件目录与同目录下的 knowledge_retrieval_comp.py知识库检索、memory_write_comp.py长期记忆写入一起构成 Agent 的外挂记忆/知识工具箱。该组件的核心语义是给定一个查询字符串从长期记忆中同时检索两类内容——片段记忆fragment memory与历史摘要history summary。典型应用场景包括多轮对话中回忆用户画像、在生成回答前注入相关历史经验、在长期记忆写入之后按需回读验证等。二、配置类 MemoryRetrievalCompConfig 全参数解析MemoryRetrievalCompConfig是组件的配置数据类dataclass继承自ComponentConfig。ComponentConfig基类仅包含一个可选字段metadata: Optional[WorkflowComponentMetadata]见 base.py用于描述节点 ID、节点类型与节点名称。配置类的完整字段如下与 API 文档一致均可在源码中逐一对上见 memory_retrieval_comp.py参数类型必填默认值说明memoryLongTermMemory是无用于执行检索的长期记忆实例scope_idstr否LongTermMemory.DEFAULT_VALUE作用域 ID用于跨场景隔离记忆数据user_idstr否LongTermMemory.DEFAULT_VALUE用户 ID用于按用户隔离记忆数据thresholdfloat否0.3相似度阈值低于该值的结果会被过滤掉其中LongTermMemory.DEFAULT_VALUE的取值为字符串__default__见 long_term_memory.py即不指定scope_id/user_id时使用默认隔离键。从源码调用关系看这四个配置项最终会被原样透传给底层记忆检索方法见下文第四节因此它们直接影响检索的数据范围scope/user 隔离与结果质量threshold 过滤。在配置时需注意memory必须是已初始化好的LongTermMemory实例该类是单例内部管理 KV 存储、向量存储、数据库存储与消息存储等多类后端见 long_term_memory.pyscope_id在底层还会经过格式校验格式非法时检索会直接抛出MEMORY_GET_MEMORY_EXECUTION_ERROR类型的错误threshold建议结合向量相似度分布经验调整过低会引入噪声结果过高会导致召回不足。三、组件类 MemoryRetrievalComponent图构建 APIMemoryRetrievalComponent的构造签名MemoryRetrievalComponent(component_config: Optional[MemoryRetrievalCompConfig] None)即component_config为可选参数不传时_config为None实际业务使用中必须传入因为可执行类构造时依赖component_config.memory。组件暴露两个方法3.1 add_componentadd_component(graph: Graph, node_id: str, wait_for_all: bool False) - None将组件作为节点加入工作流图。源码实现为def add_component(self, graph: Graph, node_id: str, wait_for_all: bool False) - None: graph.add_node(node_id, self.to_executable(), wait_for_allwait_for_all)其中Graph是工作流图的抽象基类提供start_node、end_node、add_node、add_edge、add_conditional_edges、compile等接口见 graph/base.py。wait_for_allTrue表示等待所有上游节点输出就绪后再执行该节点在add_workflow_comp的wait_for_all参数中语义相同。3.2 to_executableto_executable() - MemoryRetrievalExecutable将可组合组件转换为对应的可执行实例源码实现为return MemoryRetrievalExecutable(self._config)。设计要点与ComponentComposable基类约定一致——add_component描述组件在图中如何挂载to_executable生成运行时实体二者职责分离便于在构建期与运行期分别做扩展参考 component.py 中对这两个接口的约定。四、输入 / 输出契约MemoryRetrievalInput 与 MemoryRetrievalOutput4.1 输入 MemoryRetrievalInput字段类型默认值说明querystr无必填用于检索记忆的查询字符串不能为空top_kint5返回的最大结果数量对应的 Pydantic 模型定义memory_retrieval_comp.pyclass MemoryRetrievalInput(BaseModel): query: str top_k: int Field(default5) model_config ConfigDict(extraallow)注意query不允许为空字符串或纯空白字符串否则会抛出参数校验错误。该约束有两层保障Pydantic 模型校验阶段MemoryRetrievalExecutable.validate_inputs捕获ValidationError抛出COMPONENT_MEMORY_RETRIEVAL_INPUT_PARAM_ERRORinvoke内部的显式检查if not query.strip(): raise build_error(...)错误信息为Query must be a non-empty string。4.2 输出 MemoryRetrievalOutput字段类型默认值说明fragment_memory_resultsList[MemResult][]检索到的片段记忆结果列表summary_resultsList[MemResult][]检索到的历史摘要结果列表MemResult是底层记忆引擎定义的返回结构包含两个字段见 long_term_memory.pyclass MemResult(BaseModel): mem_info: MemInfo Field(defaultNone, descriptionmemory information) score: float Field(default0.0, descriptionmemory score of relevance)其中MemInfo携带mem_id记忆 ID、content记忆内容、type记忆类型、timestamp时间戳等元信息。type对应MemoryType枚举其取值包括USER_PROFILE用户画像、SEMANTIC_MEMORY语义记忆、EPISODIC_MEMORY情景记忆以及SUMMARY历史摘要等见 memory_unit.py。score表示该条记忆与查询的相关性分数输出结果会按分数降序排列见下节。五、执行原理MemoryRetrievalExecutable.invoke 完整调用链可执行类的核心入口是async def invoke(self, inputs, session, context) - Output完整流程如下memory_retrieval_comp.py绑定会话self._set_session(session)记录当前执行会话用于后续日志与组件 ID、会话 ID 的追踪校验输入self.validate_inputs(inputs)通过MemoryRetrievalInput.model_validate解析输入空白查询拦截query.strip()为空则抛出COMPONENT_MEMORY_RETRIEVAL_INPUT_PARAM_ERROR记录开始日志使用workflow_logger记录WORKFLOW_COMPONENT_START事件元数据包含query_length、top_k、threshold、user_id、scope_id、sensitive_mode敏感模式开关等并行双路检索在同一个try块内先后 awaitmem_results: List[MemResult] await self._memory.search_user_mem( queryquery, numretrieval_input.top_k, user_idself._config.user_id, scope_idself._config.scope_id, thresholdself._config.threshold, ) summary_results: List[MemResult] await self._memory.search_user_history_summary( queryquery, numretrieval_input.top_k, user_idself._config.user_id, scope_idself._config.scope_id, thresholdself._config.threshold, )可见top_k、user_id、scope_id、threshold都被原样透传给底层方法其中top_k对应底层num参数。异常统一包装任一检索方法抛异常时记录WORKFLOW_COMPONENT_ERROR日志并抛出COMPONENT_MEMORY_RETRIEVAL_INVOKE_CALL_FAILED错误信息形如Memory retrieval call failed: {e}原始异常作为cause保留格式化输出_format_output(mem_results, summary_results)将结果封装为MemoryRetrievalOutput并model_dump()成字典返回记录结束日志WORKFLOW_COMPONENT_END事件元数据包含num_results与num_summary_results。5.1 底层检索search_user_mem 与 search_user_history_summaryLongTermMemory的检索实现long_term_memory.pysearch_user_mem首先校验scope_id格式非法则抛错接着检查search_manager是否已初始化然后调用_apply_scope_embedding(scope_id)应用作用域级 embedding构造SearchParams(query, scope_id, top_knum, user_id, threshold, search_typeself.fragment_type)交由search_manager.search(params)执行。返回前会对结果按score降序排序并截取前num条最后封装为MemResult列表并触发MEMORY_SEARCH_FINISHED事件。search_user_history_summary流程类似检索对象为历史摘要类型MemoryType.SUMMARY同样带MEMORY_SEARCH_STARTED事件钩子。其中self.fragment_type指向片段记忆的三类USER_PROFILE用户画像、EPISODIC_MEMORY情景记忆、SEMANTIC_MEMORY语义记忆long_term_memory.py。这解释了输出字段命名fragment_memory_results对应这三类片段记忆summary_results对应历史摘要。5.2 异常与状态码组件涉及的异常码定义在 codes.pyCOMPONENT_MEMORY_RETRIEVAL_INPUT_PARAM_ERROR输入参数校验失败空 query、缺字段、类型错误COMPONENT_MEMORY_RETRIEVAL_INVOKE_CALL_FAILED底层检索调用失败。配合build_error与BaseError统一错误模型上层可通过exc.code与exc.message捕获并判断错误类型。六、在工作流中的实战接入MemoryRetrievalComponent 的使用遵循 openJiuwen 工作流的通用三步法参考 workflow.md 中add_workflow_comp的说明实例化记忆引擎与组件from openjiuwen.core.memory import LongTermMemory from openjiuwen.core.workflow.components.resource.memory_retrieval_comp import ( MemoryRetrievalComponent, MemoryRetrievalCompConfig, ) memory LongTermMemory() retrieval_comp MemoryRetrievalComponent( MemoryRetrievalCompConfig( memorymemory, scope_idchat_scene, user_iduser_1001, threshold0.35, ) )挂载到工作流借助Workflow.add_workflow_comp通过inputs_schema绑定上游节点传递的查询参数from openjiuwen.core.workflow import Workflow, Start, End flow Workflow() flow.set_start_comp(start, Start(), inputs_schema{user_inputs: ${user_inputs}}) flow.add_workflow_comp( memory_retrieval, retrieval_comp, inputs_schema{query: ${start.query}, top_k: 5}, ) flow.set_end_comp(end, End(), inputs_schema{mem: ${memory_retrieval.fragment_memory_results}}) flow.add_connection(start, memory_retrieval) flow.add_connection(memory_retrieval, end)执行通过create_workflow_session()创建会话并await flow.invoke(...)输出中的fragment_memory_results/summary_results即可作为下游节点的记忆上下文输入。实践提示top_k与threshold是控制召回数量与质量的旋钮。记忆稀疏的场景可适当调大top_k并降低threshold而上下文窗口紧张、对相关性敏感的场景则应反向收紧。scope_id与user_id务必与记忆写入侧保持一致否则会出现写入读不到的隔离问题。七、记忆闭环与 MemoryWriteComponent 配套使用与MemoryRetrievalComponent天然配套的是同目录下的 MemoryWriteComponent。二者共同组成写入 → 检索的长期记忆闭环写入侧MemoryWriteCompConfig提供memory、scope_id、user_id、session_id、agent_config、gen_mem是否生成记忆默认True、gen_mem_with_history_msg_num生成记忆时参考的历史消息数默认2等配置其输入messages为消息列表通过memory.add_messages(...)完成写入检索侧MemoryRetrievalComponent用相同的scope_id/user_id读取写入口径下的数据。推荐的典型编排对话增强场景Start → LLM 生成 → MemoryWrite(记录本次对话) → MemoryRetrieval(基于新问题检索历史) → LLM(结合记忆作答) → End写入与检索共享同一LongTermMemory实例与隔离键即可实现跨会话、跨场景的个性化记忆回读。八、测试验证行为契约的可执行证据openJiuwen 为 MemoryRetrievalComponent 提供了完整的行为级单元测试见 test_workflow_with_memory.py关键用例覆盖检索成功MockLongTermMemory返回构造好的MemResult含mem_id、content、type、score断言输出同时包含fragment_memory_results与summary_results两个键且字段值原样透传mem_id、score一一对应多结果与参数透传断言top_k、threshold被正确传入底层search_user_mem的num、threshold参数空结果底层返回空列表时输出为两个空列表组件不抛错空查询报错query 时抛出COMPONENT_MEMORY_RETRIEVAL_INPUT_PARAM_ERROR错误消息为Query must be a non-empty string缺字段报错缺少query字段时validate_inputs抛出同码错误底层失败包装search_user_mem抛异常时抛出COMPONENT_MEMORY_RETRIEVAL_INVOKE_CALL_FAILED消息为Memory retrieval call failed。这些测试用例即组件的行为契约说明书输入校验、参数透传、异常包装、输出格式四大行为均有自动化保障可作为二次开发或自建 Agent 记忆链路时的参考基准。九、注意事项与最佳实践小结隔离键一致性scope_id/user_id需与记忆写入侧保持完全一致含__default__默认值否则检索命中率为零底层会对scope_id做格式校验非法格式直接抛错。query 非空空串/纯空白查询会在输入校验阶段即被拦截COMPONENT_MEMORY_RETRIEVAL_INPUT_PARAM_ERROR生产链路中应在上游先做 query 清洗。阈值权衡threshold0.3是默认值而非绝对标准应根据实际 embedding 分布与召回质量调整输出结果已按score降序排列可放心取头部结果。异步模型组件invoke是异步方法在工作流之外单独使用时应置于 async 上下文测试中通过pytest.mark.asyncio驱动。日志可观测组件在开始/结束/异常时都会记录带component_id、session_id、query_length、sensitive_mode等元数据的结构化日志WORKFLOW_COMPONENT_START / WORKFLOW_COMPONENT_ERROR / WORKFLOW_COMPONENT_END排查检索链路问题时应优先检索这些事件类型。横向对比如果需要检索的是知识库文档而非用户记忆应改用同目录下的KnowledgeRetrievalComponent知识库检索组件二者输入输出模型不同切勿混用。十、结语MemoryRetrievalComponent是 openJiuwen agent-core 中工作流 长期记忆结合的关键桥梁它以极小的接入成本一个配置类 一个图挂载方法将底层LongTermMemory的向量检索、摘要检索、相似度过滤、作用域隔离等能力暴露给工作流编排层。理解其配置语义、输入输出契约与底层调用链是构建具备个性化记忆与历史经验回读能力的 Agent 工作流的基础。相关可继续深入阅读的材料组件基类 component.py、记忆引擎 long_term_memory.py、写入组件 memory_write_comp.py、工作流挂载 API workflow.md 与组件体系文档 components.md。赞分享人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载相关推荐Haystack 集成 Mem0 长期记忆Mem0MemoryStore、Retriever/Writer 组件与 Agent 记忆工具实战指南Haystack 集成 Mem0 长期记忆Mem0MemoryStore、Retriever/Writer 组件与 Agent 记忆工具实战指南 本文基于 H人工智能大模型RAGAI AgentNLPDLSS Swapper9 种 DLL、8 个游戏库不更新游戏也能切换缩放版本DLSS Swapper9 种 DLL、8 个游戏库不更新游戏也能切换缩放版本 如果你的游戏还停在上一代 DLSS而新版早就发布你又不想等厂商推送补丁、桌面应用openJiuwen Agent 长期记忆引擎实践指南openjiuwen.core.memory 模块全解析openJiuwen Agent 长期记忆引擎实践指南openjiuwen.core.memory 模块全解析 openjiuwen.core.memory人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习上一篇如何用AI技术将音乐完美分离5个步骤让音频编辑变得简单下一篇如何用OpenVINO AI插件为Audacity添加专业级音频处理能力完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考