多彩编程 多彩编程MZPH · CODE BLOG
ARTICLE DETAIL

文章详情

深耕前端与后端开发技术的一线实战笔记与踩坑复盘。

MemOS 添加记忆接口实战:POST /product/add 与 MemCube 隔离机制深度解析

MemOS 添加记忆接口实战:POST /product/add 与 MemCube 隔离机制深度解析 人工智能大模型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/add它负责将对话、纯文本与元数据转化为结构化记忆片段并通过 MemCube 机制实现个人记忆、知识库与多租户场景下的隔离存储。读完本文你将掌握该接口的全部参数语义、底层调用链与 MemCube 写入路由原理并能在真实项目中用 SDK 或原生 HTTP 请求完成记忆写入与反馈修正。1. 接口概览非结构化记忆的生产入口POST /product/add是 MemOS 存储非结构化数据的核心入口。它支持三类输入形态对话列表messages数组、纯文本messages字符串以及扩展元数据info字段系统会将其解析、去重并组织为结构化的记忆片段持久化到记忆库中。在开源版架构中该接口最关键的底层设计是MemCube记忆以 Cube 为物理隔离与动态组织单元接口本身不做全局去重而是在单个 Cube 内部完成去重与冲突解决。这意味着写到哪里即writable_cube_ids往往比写什么更能决定记忆的组织形态理解这一机理是高效使用接口的前提。2. 核心机理MemCube 与隔离2.1 隔离单元MemCube 是记忆生成的原子单位Cube 之间完全独立系统仅在单个 Cube 内部进行去重和冲突解决。这一设计与源码中的视图层实现一一对应AddHandler会根据目标 Cube 数量构建不同的写入视图见 add_handler.py单 Cube构建SingleCubeView在该 Cube 内完成记忆组织多 Cube构建CompositeCubeView对所有目标 Cube 执行 fan-out 写入见 composite_cube.py源码注释明确说明其行为是simply fan-out writes to all cubes。2.2 灵活映射Cube ID 的语义由使用者自行约定接口层不关心其背后对应的是用户还是知识库个人模式将user_id作为writable_cube_ids传入即建立个人私有记忆知识库模式将知识库的唯一标识QID作为writable_cube_ids传入内容即存入该知识库。从源码看_resolve_cube_ids的执行顺序是优先使用writable_cube_ids去重后保留未提供时回退到[user_id]见 add_handler.py。因此即使调用方漏传目标 Cube系统也会默认写入用户私有 Cube不会出现无家可归的记忆。2.3 多目标写入接口支持同时向多个 Cube 写入记忆实现跨域同步例如同时写入个人私有库与团队共享知识库。CompositeCubeView.add_memories会遍历全部SingleCubeView并合并各 Cube 返回的结果列表从而让一次调用完成多域写入见 composite_cube.py。3. 关键接口参数详解核心参数定义如下继承自原文档参数表并结合 product_models.py 的APIADDRequest模型展开参数名类型必填默认值说明user_idstr是-用户唯一标识符用于权限校验未指定writable_cube_ids时也会作为写入目标。messageslist/str是-待存储的消息列表或纯文本内容。writable_cube_idslist[str]是-核心参数指定写入的目标 Cube ID 列表支持多目标写入。async_modestr否async处理模式async后台队列处理立即返回task_id或sync当前请求阻塞直到记忆写入完成。is_feedbackbool否false若为true系统将自动路由至反馈处理器执行记忆更正不生成新事实。session_idstr否default会话标识符用于追踪对话上下文。custom_tagslist[str]否-自定义标签可作为后续搜索时的过滤条件。infodict否-扩展元数据。其中的所有键值对均支持后续过滤检索。modestr否-仅在async_modesync时生效可选fast快速或fine精细。3.1 async_mode 与 mode 的联动规则源码对两者关系做了显式约束见 product_models.pyasync_modeasync时若同时传入mode系统会打印警告并强制将其置为None——因为异步队列任务固定走快速提取管线async_modesync时modefast切换至快速管线否则默认走fine精细管线。这一规则在SingleCubeView._process_text_mem中得到落实async模式恒为fastsync模式根据add_req.mode fast决定见 single_cube.py。3.2 messages 的三种合法形态messages字段的类型别名定义在 general_types.pyMessagesType str | MessageList | RawMessageList即纯文本字符串如知识库导入场景直接传一句话标准对话消息列表role/content可选chat_time时间戳与message_id见 general_types.py原始消息列表支持文本、图片、文件等多模态输入项。在APIADDRequest的字段注释中messages还支持包含 tool 消息tool_description / tool_input / tool_output以及纯输入项无对话时的直接内容输入见 product_models.py。3.3 info 元数据与保留字段过滤info中的全部键值对都会成为后续过滤检索的候选条件。但需要注意AddHandler在入口处会对info做一次保留字段过滤——调用list_all_fields()取出记忆系统的全部保留字段并剔除同名键若发生剔除会记录警告日志见 add_handler.py。也就是说info里不能出现与记忆内部字段同名的键。3.4 废弃字段与向后兼容APIADDRequest保留了若干兼容字段model_validator会在请求进入处理逻辑前自动完成映射见 product_models.pymem_cube_id→writable_cube_ids旧字段新字段优先memory_content→ 追加为messages中的文本项doc_path→ 追加为messages中的文件项source→ 写入info[source]推荐改用info[source_type]/info[source_url]。从源码注释看这些字段是将删除的过渡字段will delete later新开发应直接使用新字段。4. 工作原理从路由到 AddHandler 的完整调用链4.1 路由注册/product/add定义在 server_router.py路由器以/product为前缀POST /add端点将APIADDRequest直接交给全局单例AddHandler.handle_add_memories。整个AddHandler采用依赖注入方式构建构造时校验naive_mem_cube、mem_reader、mem_scheduler、feedback_server四个必需依赖见 add_handler.py。4.2 AddHandler 调度逻辑handle_add_memories被hookable(add)装饰见 add_handler.py这意味着在正式处理前后会依次触发add.before/add.after插件钩子分别允许修改请求与修改结果钩子机制见 hooks.py。其核心流程如下多模态解析由MemReader组件将messages转化为内部记忆对象。MemReader.get_memory负责从场景数据中抽取并分类记忆内容对话数据用 LLM 提炼问答对文件路径则先经 chunker 切分再逐块总结同时支持topic_chunk_size/chunk_size等切分参数见 simple_struct.py。反馈路由若is_feedbackTrueHandler 会将chat_history与messages拼接定位最后一条role user的消息作为反馈内容、其前的历史作为history构造APIFeedbackRequest并调用cube_view.feedback_memories只修正已有记忆而不生成新事实见 add_handler.py。异步分发非反馈场景下调用cube_view.add_memories(add_req)若为async模式MemScheduler将任务推入任务队列接口立即返回task_idScheduleMessageItem携带task_id/session_id/mem_cube_id等上下文见 single_cube.py。内部组织算法在目标 Cube 内执行组织逻辑通过去重和融合优化记忆质量。从_process_text_mem可以看到写入被拆分为get_memory解析嵌入、write_db写入text_mem并可选建立原始文件节点边、schedule调度后续记忆任务三个阶段每个阶段都有耗时埋点见 single_cube.py。4.3 同步模式下的精细管线sync fine组合会启用更完整的处理save_rawfile开启时RawFileMemory会被单独抽取并调用add_rawfile_nodes_n_edges建立文件节点关联同时对merged_from标记的旧记忆执行归档避免重复见 single_cube.py 与 single_cube.py。因此当需要保留原始文件证据或做精细融合时应选择sync模式。5. 快速上手SDK 与原生 HTTP 调用5.1 使用 MemOSClient SDK推荐使用MemOSClientSDK 进行标准化调用示例沿用原文档见 client.pyfrom memos.api.client import MemOSClient # 初始化客户端 client MemOSClient(api_key..., base_url...) # 场景一为个人用户添加记忆 client.add_message( user_idsde_dev_01, writable_cube_ids[user_01_private], messages[{role: user, content: 我正在学习 R 语言的 ggplot2。}], async_modeasync, custom_tags[Programming, R] ) # 场景二往知识库导入内容并开启反馈 client.add_message( user_idadmin_01, writable_cube_ids[kb_finance_2026], messages2026年财务审计流程已更新请参考附件。, is_feedbackTrue, # 标记为反馈以更正旧版流程 info{source: Internal_Portal} )SDK 客户端的初始化支持三级配置优先级显式传入的base_url参数 MEMOS_BASE_URL环境变量 默认地址api_key同样可来自MEMOS_API_KEY环境变量未提供会抛出ValueError。认证采用Authorization: Token api_key头见 client.py。需要说明的是从源码看MemOSClient.add_message内部实际请求的端点为/add/message而本文档描述的接口为POST /product/addapi_analyzer.py 中的调度器示例则直接使用/product/add。两者是版本演进中并存的两条写入通道参数语义一致建议以实际部署版本 Swagger 文档/docs为准进行验证。5.2 原生 HTTP 调用不依赖 SDK 时可直接构造 JSON 请求curl -X POST $BASE_URL/product/add \ -H Content-Type: application/json \ -H Authorization: Token $MEMOS_API_KEY \ -d { user_id: sde_dev_01, writable_cube_ids: [user_01_private], messages: [{role: user, content: 我正在学习 R 语言的 ggplot2。}], async_mode: async, custom_tags: [Programming, R] }5.3 响应结构同步接口统一返回MemoryResponse结构code状态码默认 200、message如Memory added successfully与data记忆结果列表见 product_models.py 与 product_models.py。SDK 侧则封装为MemOSAddResponse可通过属性便捷访问success、task_id、status等字段见 product_models.py 与 product_models.py。在async模式下返回的task_id是追踪异步任务的关键凭证可配合任务状态查询接口StatusRequest模型定义了按user_id/task_id查询的能力见 product_models.py轮询后台记忆生产进度。6. 实战建议与注意事项6.1 模式选择高频写入、追求低延迟使用async_modeasync接口秒回task_id记忆由后台队列异步生产需要立即可用、等待完整结果使用async_modesync此时可通过mode在fast快速与fine精细含文件节点与融合归档之间权衡注意mode在 async 模式下会被静默忽略不要依赖它控制异步任务的提取深度。6.2 场景模板速查场景user_idwritable_cube_idsis_feedback备注个人私有记忆用户 ID用户私有 Cubefalse与 user_id 同名即可未传时自动回退知识库导入管理员 ID知识库 QIDfalse内容进入共享知识库反馈修正用户 ID目标 Cubetrue提取末条 user 消息更正旧记忆跨域同步用户 ID多个 Cube ID 列表false一次写入同步到个人与团队库6.3 测试佐证仓库测试对接口输入输出格式做了回归保障test_server_router.py 验证/product/add的请求解析兼容mem_cube_idmemory_content旧字段与MemoryResponse响应格式test_product_models.py 针对 issue #1505 保证 Swagger 交互文档中能正确渲染可复制的请求示例test_client.py 验证 SDK 的async_mode参数正确透传。6.4 扩展性hookable(add)使该接口天然具备插件扩展点通过注册add.before钩子可以在记忆入库前改写请求如注入来源、脱敏通过add.after钩子可以加工返回结果。这意味着记忆写入这一基础动作可以被团队按需定制为审计、通知或二次加工流水线而无需改动核心代码见 hooks.py。总结POST /product/add是一个隔离清晰、模式灵活、可扩展的记忆生产接口。掌握writable_cube_ids的 Cube 路由语义、async_mode与mode的联动规则、以及is_feedback的更正语义即可在个人记忆、知识库与多租户场景中稳定高效地生产记忆。赞分享人工智能大模型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/feedback 的记忆修正机制与配置要点MemOS 反馈记忆纠偏接口实战深入剖析 POST /product/feedback 的记忆修正机制与配置要点 本文以 MemOS 开源仓库中的《添加反馈》人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-plugin让通用模型说出你的行业黑话3 步用 Axolotl 完成领域适应的继续预训练让通用模型说出你的行业黑话3 步用 Axolotl 完成领域适应的继续预训练 你贴一张出院小结进通用大模型它开始背诵急性心肌梗死的教科书定义——这种尴尬人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-pluginMemOS 获取记忆接口实战/product/get_memory 分页查询与 /product/get_all 全量子图导出指南MemOS 获取记忆接口实战/product/get_memory 分页查询与 /product/get_all 全量子图导出指南 本篇指南聚焦 MemOS人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-plugin创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表