人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-plugin【免费下载链接】MemOSSelf-evolving memory OS for LLM AI Agents: ultra-persistent memory, hybrid-retrieval, and cross-task skill reuse, with 35.24% token savings and DeepSeek Harness support.项目地址https://gitcode.com/gh_mirrors/memos/MemOS点击查看免费下载本文围绕 MemOS 开源版的核心检索接口POST /product/search展开完整讲解其基于 MemCube 隔离机理的语义检索与逻辑过滤实现从readable_cube_ids的可读范围控制、fast / fine / mixture三种搜索策略到top_k、filter、dedup等召回控制参数的源码级行为。读完本文你将掌握如何在多 Cube、多租户场景下编写正确的检索请求并理解召回结果在 SearchHandler 中经历的完整流水线从而为 RAG 应用调出最相关的记忆上下文。1. 接口定位MemOS 检索增强生成的引擎接口路径POST /product/search功能描述本接口是 MemOS 实现检索增强生成 (RAG) 的核心。它能够跨越多个隔离的MemCube进行语义匹配自动召回相关的事实、用户偏好及工具调用记录为下游的 Chat 生成提供上下文。从源码看该端点在 server_router.py 中注册请求体由APISearchRequest模型定义于 product_models.py承载实际处理逻辑委托给SearchHandler.handle_search_memories()router.post(/search, summarySearch memories, response_modelSearchResponse) def search_memories(search_req: APISearchRequest): Search memories for a specific user. search_results search_handler.handle_search_memories(search_req) return search_results返回的SearchResponse沿用统一的code / message / data三层结构data中按text_mem文本记忆、pref_mem偏好记忆、tool_mem工具调用记忆、skill_mem技能记忆、act_mem、para_mem等分桶组织每个桶形如{cube_id: ..., memories: [...], total_nodes: ...}便于下游直接消费。2. 核心机理Readable Cubes 与检索范围控制与云服务的单一用户视角不同开源版接口通过readable_cube_ids实现了极其灵活的检索范围控制跨 Cube 检索可以同时指定多个 Cube ID如[用户私有Cube, 企业公共知识库Cube]算法会并行从这些隔离的记忆体中召回最相关内容。软信号权重通过传入session_id系统会在召回时优先考虑该会话内的内容。这仅作为提升相关性的“权重”而非强制过滤。绝对隔离未包含在readable_cube_ids列表中的 Cube 内容在算法层是完全不可见的确保了多租户环境下的数据安全性。2.1 多 Cube 的并行扇出fan-out从源码结构看SearchHandler._build_cube_view()见 search_handler.py会根据解析出的 Cube ID 列表构建SingleCubeView或CompositeCubeView。当存在多个可读 Cube 时CompositeCubeView 使用ContextThreadPoolExecutor(max_workers2)对每个 Cube 并行发起检索再按桶合并结果with ContextThreadPoolExecutor(max_workers2) as executor: future_to_view { executor.submit(_search_single_cube, view): view for view in self.cube_views } for future in as_completed(future_to_view): cube_result future.result() merged_results[text_mem].extend(cube_result.get(text_mem, [])) # ... pref_mem / tool_mem / skill_mem 等同理合并这意味着多 Cube 检索的延迟理论上接近单 Cube 检索受限于并行度 2而不是各 Cube 串行累加。2.2 单 Cube 内部的执行入口在 single_cube.py 中SingleCubeView.search_memories()会先通过resolve_filter_for_cube()把多 Cube 过滤器解析为当前 Cube 的子过滤器再构造UserContext将session_id归一到default_session最终统一走_search_text()流程。session_id在底层被转换为search_priority软权重传入检索器这正是文档所述“软信号权重”的实现位置search_priority {session_id: search_req.session_id} if search_req.session_id else None search_filter search_req.filter3. 关键接口参数详解以下参数定义与默认值均来自 APISearchRequest是当前仓库的真实行为。3.1 检索基础参数参数名类型必填/默认说明querystr是用户的搜索查询语句系统将基于此进行语义匹配。user_idstr是请求发起者的唯一标识用于鉴权与上下文追踪。readable_cube_idslist[str]是算法面核心参数指定本次检索可读取的 Cube ID 列表未列出的 Cube 在算法层完全不可见。modestrfast搜索策略可选fast快速、fine精细、mixture混合枚举定义见 general_types.py。session_idstrNone会话软信号仅用于提升会话内内容的相关性权重不做硬过滤。3.2 召回控制参数参数名类型默认值说明top_kint10每个 Cube 召回文本记忆的数量上限源码约束ge1。pref_top_kint6偏好记忆的召回数量上限。tool_mem_top_kint6工具调用记忆的召回数量上限。skill_mem_top_kint3技能记忆的召回数量上限。include_preferencebooltrue是否召回相关的用户偏好记忆显式/隐式偏好。search_tool_memorybooltrue是否召回相关的工具调用记录。include_skill_memorybooltrue是否召回相关的技能记忆。relativityfloat0.45相关性阈值只有metadata.relativity relativity的记忆才会被返回设0可关闭阈值过滤。dedupstrmmr去重策略no不去重、sim语义去重、mmr基于 MMR 的最大边际相关去重。rerankbooltrue是否对文本记忆应用重排序设为false时返回检索原始顺序的候选。filterdictNone逻辑过滤器支持按标签或元数据进行精确过滤。search_memory_typestrAll记忆类别过滤支持WorkingMemory、LongTermMemory、UserMemory、ToolTrajectoryMemory、SkillMemory、PreferenceMemory等。reference_timestrNone时间敏感检索的参考时间缺省使用服务器当前时间。需要说明的是接口文档最初将dedup描述为no / sim / NoneNone 表示默认精确文本去重而在当前仓库源码中该字段的取值扩展为no / sim / mmr且默认值即为mmr见 product_models.py。写请求时显式传no可完全关闭语义去重。3.3 向后兼容APISearchRequest仍保留废弃字段mem_cube_id单 Cube 检索。model_validator会将其自动转换为readable_cube_ids [mem_cube_id]并打印迁移告警moscube旧版 MemOSCube 流水线与operation已被弃用并忽略。新代码应直接使用readable_cube_ids。4. 工作原理SearchHandler 策略流水线当请求到达后端时SearchHandler会根据指定的mode调用不同的组件执行检索。完整处理链位于 search_handler.py 的handle_search_memories()请求深拷贝与候选扩充copy.deepcopy隔离请求对象当dedup in (sim, mmr)时top_k会先扩大 3 倍以保留足够候选供后续去重筛选。查询重写利用 LLM 对用户的query进行语义增强提升匹配精度。fine模式的策略由FineStrategy枚举控制rewrite/recreate/deep_search/agentic_search默认recreate并可通过环境变量FINE_STRATEGY覆盖见 general_types.py。多模式匹配Fast 模式通过向量索引进行快速召回适用于对响应速度要求极高的场景。Fine 模式增加重排序Rerank环节提升召回内容的相关度。Mixture 模式结合语义搜索与图谱搜索召回更具深度的关联记忆。多维聚合系统并行检索事实top_k、偏好pref_top_k和工具记忆tool_mem_top_k、技能记忆skill_mem_top_k结果以分桶结构聚合返回。Relativity 阈值过滤_apply_relativity_threshold()按metadata.relativity relativity对text_mem与pref_mem逐桶裁剪并同步修正total_nodes。后处理去重根据dedup配置压缩高度相似的记忆条目。重排序rerank_knowledge_mem()对最终文本记忆按查询相关性二次重排文件类记忆占比file_mem_proportion0.5。4.1 去重的实现细节源码级sim语义去重_dedup_text_memories()对全部候选计算余弦相似度矩阵按相关性降序贪婪选取只有与已选集合中所有条目的相似度都低于0.92阈值时才入选从而保证返回内容互不冗余。mmr最大边际相关去重_mmr_dedup_text_memories()对文本与偏好记忆联合执行 MMR 选择先按相关性预填充少量条目再以mmr_score 0.8 * relevance - 0.2 * diversity迭代挑选对相似度超过 0.9 的候选施加指数惩罚系数 10.0最后按原始相关性重排以保证生成质量。文本层相似度由Dice40% TF-IDF35% 2-gram25%加权组合判定。可通过环境变量MEMOS_MMR_CANDIDATE_PRUNING_ENABLED开启候选剪枝将每个桶的候选压缩到目标配额的两倍以内。4.2 可扩展的 Hook 机制handle_search_memories标注了hookable(search)并在检索的各个阶段触发钩子见 hook_defs.pysearch.before/search.after、SEARCH_MEMORY_RESULTS、SEARCH_RESULTS_AFTER_RERANK、SEARCH_CONTEXT_RENDER。插件可以借此拦截或改写检索结果source字段即为插件调用方提供路由依据。4.3 Dream 上下文召回可选当设置环境变量MEMOS_DREAM_CONTEXT_RECALLon时_merge_context_recall()会额外从图数据库中按 embedding 召回Context类型的“梦境”上下文桶并合并进text_mem数量由MEMOS_DREAM_CONTEXT_RECALL_TOP_K控制默认 2。该特性默认关闭。5. 快速上手示例5.1 通过 SDK 进行多 Cube 联合检索以下调用展示了同时检索“用户私有 Cube 两个专业知识库”的典型场景from memos.api.client import MemOSClient client MemOSClient(api_key..., base_url...) # 场景同时检索用户记忆和两个专业知识库 res client.search_memory( user_idsde_dev_01, query根据我之前的偏好推荐一些 R 语言的可视化方案, # 传入可读的 Cube 列表包括个人空间和两个知识库 readable_cube_ids[user_01_private, kb_r_lang, kb_data_viz], modefine, # 使用精细模式以获得更准确的推荐 include_preferenceTrue, # 召回“用户喜欢简洁风格”等偏好 top_k5 ) if res: # 结果包含在 memory_detail_list 中 print(f召回结果: {res.data})说明具体 SDK 的search_memory方法参数以你所安装的memos客户端版本为准readable_cube_ids、mode、include_preference、top_k等概念与下文 HTTP 请求一一对应。5.2 直接调用 HTTP 接口仓库自带的 server_router_api.py 提供了完整可运行的请求示例请求体即APISearchRequest的 JSON 形态payload { user_id: USER_ID, query: What are my hotel preferences?, readable_cube_ids: [MEM_CUBE_ID], top_k: 5, mode: fast, include_preference: True, } resp requests.post( f{BASE_URL}/search, headersHEADERS, datajson.dumps(payload), timeout60 ) print(resp.status_code, resp.text)data中的分桶结果可用于直接拼装 LLM 上下文各分桶内每条记忆均带memory正文与metadata含memory_type、relativity、score、created_at等。6. 进阶使用过滤器FilterSearchHandler 支持复杂的过滤器以满足更细粒度的业务需求。filter支持嵌套的and/or条件以及gt、contains等比较运算符可作用于id、created_at、tags等字段。# 示例仅搜索标签为 Programming 且创建于 2026 年之后的记忆 search_filter { and: [ {tags: {contains: Programming}}, {created_at: {gt: 2026-01-01}} ] } res client.search_memory( query数据清洗逻辑, user_idsde_dev_01, readable_cube_ids[user_01_private], filtersearch_filter )6.1 多 Cube 过滤器解析从源码看filter支持两种形态一种是直接作用于所有 Cube 的全局过滤条件另一种是以 Cube ID 为键的“每 Cube 子过滤器”。resolve_filter_for_cube()见 search_service.py会在SingleCubeView.search_memories()入口处把全局过滤器拆分、绑定到具体 Cube再将解析后的子过滤器传给底层检索器cube_filter resolve_filter_for_cube(search_req.filter, self.cube_id) if cube_filter is not search_req.filter: search_req copy.copy(search_req) search_req.filter cube_filter写入侧同理APIADDRequest支持在添加记忆时传入custom_tags自定义标签与info任意元数据如agent_id、source_url等这些字段均可作为后续filter的过滤依据形成“写入打标 → 检索过滤”的完整闭环。7. 可观测性与调试请求/结果摘要日志SearchHandler在入口与出口分别调用summarize_search_request()与summarize_search_results()见 log.py一行日志即可概览查询词、模式、Cube 列表与各桶召回数量便于排查召回质量。阶段耗时埋点SingleCubeView.search_memories与底层检索均使用timed装饰器统计耗时多 Cube 扇出会记录cube_count上下文。单元测试参考接口行为在 test_server_router.py 中有覆盖包括必填参数校验缺少query返回 422与SearchResponse响应格式断言MMR 候选剪枝等细节在tests/api/test_mmr_candidate_pruning.py中验证。8. 与相邻模块的关系Chat 检索Chat 接口chat.md内部同样经由SearchHandler.handle_search_memories()完成上下文召回见 chat_handler.pyAPIChatCompleteRequest复用了readable_cube_ids、relativity、filter等同一套参数体系。MemCube 机理Cube 的注册、创建与隔离语义详见 mem_cube.md跨 Cube 读写readable_cube_ids/writable_cube_ids是该模块的对外核心抽象。接口总览更多 Product APIAdd / Chat / Feedback / Delete可参阅 overview.md。内存写入配套检索依赖高质量记忆写入侧APIADDRequest的custom_tags与info元数据设计在 product_models.py 中定义是filter检索生效的前提。总结POST /product/search是 MemOS 将“记忆”转化为“上下文”的关键通道readable_cube_ids在保证多租户绝对隔离的同时支持跨 Cube 并行召回mode决定 fast / fine / mixture 的检索深度top_k、relativity、dedup与filter则提供了从数量、质量到元数据条件的精细控制。结合本文给出的参数表与源码级流水线说明你可以直接在应用中构造正确、可调优的检索请求把最相关的记忆高效注入到 RAG 与 Agent 的生成链路中。赞分享人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-plugin【免费下载链接】MemOSSelf-evolving memory OS for LLM AI Agents: ultra-persistent memory, hybrid-retrieval, and cross-task skill reuse, with 35.24% token savings and DeepSeek Harness support.项目地址https://gitcode.com/gh_mirrors/memos/MemOS点击查看免费下载相关推荐ruflo-rag-memory 记忆命令实战基于 HNSW 向量检索的跨会话 RAG 记忆 CRUD 全解析ruflo rag memory 记忆命令实战基于 HNSW 向量检索的跨会话 RAG 记忆 CRUD 全解析 本指南围绕 ruflo rag memory人工智能AI Agent多智能体Agent 编排Agent 记忆工具调用代码智能体MCP 服务AI 评测amis Checkboxes 复选框组件深度指南多选值模式、全选机制与动态选项管理amis Checkboxes 复选框组件深度指南多选值模式、全选机制与动态选项管理 在 amis 低代码框架中Checkboxes复选框是表单里最基础人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-pluginruflo-rag-memory 插件深度解析基于 HNSW 向量检索与 AgentDB 的跨会话语义记忆系统ruflo rag memory 插件深度解析基于 HNSW 向量检索与 AgentDB 的跨会话语义记忆系统 ruflo rag memory 是 rufl人工智能AI Agent多智能体Agent 编排Agent 记忆工具调用代码智能体MCP 服务AI 评测创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
