MemOS 获取记忆接口实战/product/get_memory 分页查询与 /product/get_all 全量子图导出指南【免费下载链接】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 开源仓库中获取记忆Get Memories这一核心 API 能力讲解POST /product/get_memory分页查询与POST /product/get_all全量/子图导出两个接口的设计动机、请求参数、响应结构并结合仓库源码剖析其底层实现原理。读完本文你将能够独立完成记忆资产的前端分页展示、按类型全量导出以及基于查询语句提取相关记忆子图三类典型任务。1. 接口总览两种记忆集合访问模式在 MemOS 中用户的记忆资产以MemCube为组织单元存储其中既包含系统自动生成的原始记忆片段也包括用户偏好和工具使用记录。为了满足轻量展示与批量处理两类差异极大的使用场景开源版通过MemoryHandler提供了两条独立的集合访问通道路由均挂在/product前缀之下定义见 server_router.py接口路径方法设计定位核心能力/product/get_memoryPOST前端 UI 列表分页展示支持page/page_size分页默认附带偏好记忆支持细粒度类型开关与元数据过滤/product/get_allPOST数据迁移、复杂关系分析、全量导出支持按memory_type导出全量数据或传入search_query召回并返回相关记忆子图Subgraph配套的还有按 ID 精确获取的POST /product/get_memory/{memory_id}与POST /product/get_memory_by_ids它们与本文两个接口共同构成完整的记忆读取体系相关说明可参考同目录文档 get_memory_by_id.md。2. 核心机理分页 vs 全量导出两个接口虽然都是读记忆但底层处理链路完全不同理解其设计差异有助于选对接口业务分页模式/get_memory为前端列表设计强调轻量。请求模型GetMemoryRequest见 product_models.py默认开启偏好记忆、工具记忆与技能记忆的附带返回并允许通过filter对元数据做条件过滤。它返回的data是按记忆类别分组的四元结构方便前端直接渲染。全量导出模式/get_all为数据迁移或关系分析设计强调完整。当携带search_query时服务端会执行一次语义检索把命中的记忆节点及其关联关系整理成树形子图返回当不携带查询词时则按memory_type导出某一类记忆的全量数据。从源码看/get_all的两个分支分别落到两个独立 handler有search_query→ handle_get_subgraph调用naive_mem_cube.text_mem.get_relevant_subgraph(...)获取相关子图无search_query→ handle_get_all_memories调用naive_mem_cube.text_mem.get_all(...)获取指定类型全量数据。两者随后走同一条图 → 树格式化链路详见第 6 节。3. 关键接口参数详解3.1 分页查询参数/get_memory按文档定义/get_memory的核心参数如下参数名类型必填说明mem_cube_idstr是目标 MemCube ID。user_idstr否用户唯一标识符。pageint否页码从 1 开始。若设为None则尝试全量导出。page_sizeint否每页条目数。include_preferencebool否是否包含偏好记忆。对照源码中的GetMemoryRequest实际请求模型还提供了两个文档未展开但非常实用的扩展参数include_tool_memory默认True是否返回工具记忆ToolSchemaMemory、ToolTrajectoryMemoryinclude_skill_memory默认True是否返回技能记忆SkillMemoryfilter可选元数据过滤条件支持嵌套的and/or结构以及gt等比较运算符例如{and: [{id: uuid-xxx}, {created_at: {gt: 2024-01-01}}]}。设置pageNone或page_sizeNone时接口会退化为不带分页的全量拉取这与/get_all的定位在语义上互补前者返回分组后的结构化结果后者返回树形子图/类型化全量数据。3.2 全量/子图导出参数/get_all参数名类型必填说明user_idstr是用户 ID。memory_typestr是记忆类型text_mem、act_mem、para_mem。mem_cube_idslist否待导出的 Cube ID 列表。search_querystr否若提供将基于此查询召回并返回相关的记忆子图。对照源码GetMemoryPlaygroundRequest见 product_models.py实际还包含两个值得注意的细节memory_type的完整字面量集合为[text_mem, act_mem, param_mem, para_mem]其中param_mem是文档表中未列出的第四个取值额外提供了search_type参数默认fulltext可选embedding或fulltext用于指定子图召回的检索方式——即走向量语义检索还是全文检索。同时需要说明一个实现现状在 handle_get_all_memories 中当前仅text_mem分支具备完整实现act_mem与para_mem分支会记录Activity memory retrieval not implemented yet/Parameter memory retrieval not implemented yet的 warning 日志。若你的需求是文本记忆事实记忆可放心使用其余类型建议先确认服务端版本的实际支持情况。4. 快速上手示例4.1 前端分页展示SDK 调用# 获取第一页每页 10 条记忆 res client.get_memory( user_idsde_dev_01, mem_cube_idcube_research_01, page1, page_size10 ) for mem in res.data: print(f[{mem[type]}] {mem[memory_value]})如果不经过 SDK、直接以 HTTP JSON 形式调用对应的请求体应贴合GetMemoryRequest模型{ user_id: sde_dev_01, mem_cube_id: cube_research_01, page: 1, page_size: 10, include_preference: true, include_tool_memory: true, include_skill_memory: true }include_preference默认为True意味着默认返回结果中会附带用户的偏好记忆若只想看正文记忆可显式置为false。另外仓库中的 Python 客户端src/memos/api/client.py的get_memory方法对单次拉取条数做了size 50的校验见 client.py批量导大数据时建议配合分页循环或直接使用/get_all。4.2 导出特定的事实记忆子图# 提取与“R 语言”相关的全部事实记忆 res client.get_all( user_idsde_dev_01, memory_typetext_mem, search_queryR language visualization )该请求在服务端的实际处理路径为server_router.get_all_memories检测到search_query非空后会以top_k200的召回规模调用 handle_get_subgraph。mem_cube_ids为空时mem_cube_id会回退为user_id本身见 server_router.py因此即使只传user_id也能正常工作。5. 响应结构说明两个接口均返回标准的业务响应封装BaseResponse外层包含message、code、data三个字段差异主要体现在data的组织方式上。5.1/get_memory的响应 datadata是一个按记忆类别分组的字典最多包含四个键每个键对应一个组每组内含cube_id、memories与total_nodes节点总数可用于前端分页控件{ text_mem: [ { cube_id: cube_research_01, memories: [ { id: ..., memory_value: ..., tags: [] } ], total_nodes: 120 } ], pref_mem: [ { cube_id: ..., memories: [], total_nodes: 8 } ], tool_mem: [ { cube_id: ..., memories: [], total_nodes: 3 } ], skill_mem: [ { cube_id: ..., memories: [], total_nodes: 2 } ] }该结构由 handle_get_memories 拼装正文记忆固定返回涵盖WorkingMemory、LongTermMemory、UserMemory、OuterMemory四种类型其余三类受对应include_*开关控制。5.2/get_all的响应 datadata是列表结构每项对应一个 Cube包含cube_id、memories与memory_statistics。与分页接口不同这里的memories内嵌了tree_structure树形字段用于描述记忆节点间的层次关系{ data: [ { cube_id: cube_research_01, memories: [ { tree_structure: { children: [ ... ] }, nodes: [ ... ] } ], memory_statistics: { WorkingMemory: 40, LongTermMemory: 80 } } ] }5.3 单条记忆的核心字段data中的记忆对象通常包含以下核心字段id记忆唯一标识可用于后续的 获取记忆详情 或 删除记忆 操作memory_value经过算法加工后的记忆文本tags关联的自定义标签。开发者提示如果您已知记忆 ID 并希望查看其完整的元数据如confidence或usage记录请使用获取记忆详情Get_memory_by_id接口其实现为 handle_get_memory统一从text_mem含偏好记忆中按 ID 精确读取未命中时返回Memory with ID xxx not found消息。6. 底层实现原理从图数据库到树形结构/get_all之所以能返回子图是因为 MemOS 的记忆本体存储在图数据库中节点之间天然存在关联边。为了把图结构变成前端易于渲染、LLM 易于消费的树两个全量导出 handler 复用了一条完整的格式化链路见 format_utils.py 相关函数remove_embedding_recursive递归剔除向量字段避免超大 embedding 数据随响应传输实现轻量导出convert_graph_to_tree_forworkmem将图结构转换为工作记忆树采样目标节点数为200target_node_count200并按自定义类型比例分配节点配额WorkingMemory0.20LongTermMemory0.40UserMemory0.40ensure_unique_tree_ids保证树中所有节点 ID 唯一filter_nodes_by_tree_ids依据树节点 ID 集合回滤原始记忆使返回的节点与树结构严格一致sort_children_by_memory_type按记忆类型对子节点排序保证同类记忆在树中相邻呈现。同时convert_graph_to_tree_forworkmem会产出各类型的节点计数node_type_count最终作为memory_statistics随响应返回可用于前端图表统计或导出校验。这一整套逻辑在text_mem与子图两条路径中完全复用保证了分页/导出两种模式下数据口径的一致性。7. 与其他记忆接口的协作获取记忆接口通常不是孤立使用的实践中常见的组合方式如下列表 详情先用/get_memory分页拿到记忆 ID 列表前端点击某条后调用/get_memory/{memory_id}获取完整元数据检索定位 子图导出先用 search_memory 接口做关键词/向量检索再用/get_all携带search_query拉取命中记忆的完整关系子图用于复杂关系分析导出备份 删除清理用/get_all全量导出后进行数据迁移配合 delete_memory 接口支持按memory_ids、file_ids或filter三种模式删除完成清理或重建新增回写写入侧使用 add_memory 接口读写闭环即构成一套完整的记忆资产管理链路。8. 注意事项与最佳实践分页参数置None的含义/get_memory的page/page_size均为可选缺省为None此时接口会一次性返回全部数据不分页与/get_all的导出定位接近适合小规模 Cube 的场景大 Cube 优先走/get_all/get_all内部有节点采样200 节点上限与树形化处理结构更紧凑适合迁移与关系分析前端列表仍应优先使用/get_memory的total_nodes做分页search_type的选择默认fulltext适合精确关键词涉及语义相近表述时可选embedding走向量召回两者都经由get_relevant_subgraph统一返回子图类型支持现状当前text_mem是完整实现的导出类型act_mem/para_mem仅保留入口调用前请确认部署版本敏感数据与向量字段导出结果默认已剔除 embedding 向量若业务上需要原始向量需另行定制或绕过remove_embedding_recursive处理。综上/product/get_memory与/product/get_all分别承担了分页展示与全量子图导出两种互补职责配合 MemOS 的图存储与树形化格式化链路为上层 Agent 应用提供了一套结构化、可迁移的记忆读取方案。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
