MemOS 消息查询 API 实战：使用 POST /product/get/message 拉取原始对话历史

人工智能大模型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 开源版 REST API 中的消息查询接口POST /product/get/message展开系统讲解该接口与记忆查询/get_memory的本质区别、全部请求参数、底层实现原理以及基于MemOSClient的实战调用方式。读完本文你将掌握如何快速恢复历史聊天 UI、为自定义 LLM 注入原始上下文以及基于原始会话文本做回顾性分析并了解 SDK 层面的参数校验、响应模型与安全隔离机制。1. 接口概览拉取未被加工的对话原文POST /product/get/message是 MemOS 中用于检索指定会话conversation原始用户-助手对话记录的核心接口。与记忆Memory类接口返回的摘要信息不同该接口返回的是未经过任何摘要处理的原始文本因此它是构建聊天历史回顾、上下文注入等功能的基石。从接口在 SDK 中的实际实现来看客户端会把user_id、conversation_id、conversation_limit_number、message_limit_number、source五个字段组装成 JSON 请求体POST 到${base_url}/get/message其中本地开源部署时base_url通常为http://localhost:8000/product与文档中的完整路径POST /product/get/message一致。实现见 src/memos/api/client.py。1.1 先分清两件事Memory 与 Message开发时请务必区分这两种数据类型它们在 MemOS 中代表完全不同的信息层次数据形态接口返回内容示例Get Memory/get_memory系统加工后的事实与偏好摘要The user prefers R language for visualizationGet Message/get_message原始对话文本Ive been learning R recently, recommend a visualization package记忆是系统通过算法抽取、泛化后的结构化沉淀适合做长期画像消息则是用户与助手之间逐字逐句的原始交流适合做界面还原与上下文复用。二者的响应模型也各不相同记忆查询返回的是memory_detail_list等记忆明细列表而消息查询返回的是message_detail_list相关模型定义见 src/memos/api/product_models.py。记忆侧更完整的分页查询与全量导出能力可参考 Get Memories 文档。2. 关键参数详解含 SDK 层校验规则下表完整列出get_message接口的请求参数继承自官方文档并结合源码补充校验说明参数类型必填默认值说明user_idstr是-与待检索消息关联的唯一用户标识conversation_idstr否见下方说明None指定会话的唯一标识message_limit_numberint否6限制返回的消息条数建议最大值为 50conversation_limit_numberint否6限制返回的会话历史数量sourcestr否None标识消息的来源渠道2.1 源码中的参数校验与默认值透传在开源版 SDK 中get_message方法会先调用_validate_required_params对user_id与conversation_id做非空校验两者任一为空都会抛出ValueError对应实现见 src/memos/api/client.py。这一点在单元测试中有明确验证test_get_message_requires_conversation_id只传user_id不传conversation_id时断言抛出conversation_id is required异常且不会发起任何 HTTP 请求test_get_message_uses_playground_default_limits不传两个 limit 参数时断言请求体中conversation_limit_number与message_limit_number均为None即默认值由服务端兜底。测试代码见 tests/api/test_client.py。因此实践建议是虽然参数表中conversation_id标记为可选但使用开源版 SDK 时必须显式传入conversation_id才能完成调用。2.2 参数合法性边界user_id与conversation_id的长度都有硬性限制超出会触发参数校验错误码。根据 Common Error Codes 文档40010user_id超过 100 字符40011conversation_id超过 100 字符40002必填参数为空如未传user_id。3. 工作原理与安全隔离get_message的完整处理链路可以拆解为三步定位会话系统根据请求中的conversation_id从底层存储中检索属于该用户与该会话的消息记录反向切片依据message_limit_number参数按时间倒序取出指定数量的消息保证返回的一定是最新的若干条安全隔离所有请求都会经过RequestContextMiddleware对user_id的归属关系做严格校验防止越权访问他人会话。其中安全与可观测性环节的源码依据位于 src/memos/api/middleware/request_context.py。该中间件BaseHTTPMiddleware子类会为每个进入的请求完成以下工作从请求头中提取链路追踪 ID优先级为g-trace-idx-trace-idtrace-id缺失时自动生成新的trace_id构造RequestContext并写入全局上下文记录api_path、env、user_type、user_name以及来源标识source记录请求开始与完成的耗时日志非 200 状态会以 error 级别输出。RequestContextMiddleware在应用启动时被注册进 FastAPI 应用见 src/memos/api/server_api.py并标记sourceserver_api因此该中间件对所有/product/*接口统一生效是数据隔离与审计的公共底座。从消息在整个系统中的流转形态看写入侧的原始消息会以ScheduleMessageItem的形式进入调度队列该模型携带user_id、mem_cube_id、session_id、label、content、chat_history、trace_id等字段见 src/memos/mem_scheduler/schemas/message_schemas.py这与读取侧按user_idconversation_id定位原始文本的设计相互印证。4. 快速开始本地部署 SDK 拉取会话4.1 准备本地服务与客户端开源版的 REST API 服务基于 FastAPI 构建本地可通过 Docker Compose 或uvicorn启动默认监听8000端口启动后 Swagger 文档位于http://localhost:8000/docs。完整的 LLM 引擎、向量数据库与存储后端配置请参考 REST API Server Configuration Guide。MemOSClient的初始化逻辑见 src/memos/api/client.py遵循如下优先级base_url优先取构造参数其次读取MEMOS_BASE_URL环境变量最后回退到默认云端地址api_key优先取构造参数其次读取MEMOS_API_KEY环境变量两者都缺失时抛出ValueError(MemOS API key is required)请求头固定为Content-Type: application/json与Authorization: Token {api_key}。本地自托管时请将base_url指向http://localhost:8000/product。4.2 完整调用示例使用开源版内置的MemOSClient快速拉取会话历史示例代码继承自官方文档并补充了分页与健壮性处理from memos.api.client import MemOSClient # 初始化客户端 client MemOSClient( api_keyYOUR_LOCAL_API_KEY, base_urlhttp://localhost:8000/product ) # 从指定会话中拉取最近 10 条消息 res client.get_message( user_idmemos_user_123, conversation_idconv_r_study_001, message_limit_number10 ) if res and res.code 200: # 遍历返回的消息列表MessageDetail 允许额外字段直接按字典取值 for msg in res.data.message_detail_list: print(f[{msg[role]}]: {msg[content]})需要说明的是MemOSGetMessagesResponse还提供了一条便捷属性messages等价于data.message_detail_list可以直接写成for msg in res.messagesMessageDetail的模型配置为extraallow见 src/memos/api/product_models.py意味着服务端返回的role、content及可能的扩展字段都能直接按字典键访问与官方示例中的msg[role]/msg[content]用法一致。4.3 不使用 SDK 时的等价调用get_message本质是一次带鉴权头的 JSON POST 请求不依赖 SDK 时可用 curl 等价实现curl --location --request POST http://127.0.0.1:8000/product/get/message \ --header Content-Type: application/json \ --header Authorization: Token YOUR_LOCAL_API_KEY \ --data-raw { user_id: memos_user_123, conversation_id: conv_r_study_001, message_limit_number: 10 }请求头格式、字段名与 JSON 序列化方式均与 src/memos/api/client.py 中的_post_json_dict/get_message实现保持一致。4.4 响应结构速览响应遵循标准业务包装结构code状态码、message说明文字、data消息数据。其中data的核心字段为message_detail_list即消息明细数组。相关模型定义位于 src/memos/api/product_models.py。5. 典型使用场景5.1 聊天 UI 历史加载当用户点击进入某段历史会话时可调用该接口恢复聊天界面。官方建议结合message_limit_number做分页加载先拉最近一页如 620 条滚动到顶部再按更早的时间范围继续取数从而显著改善前端渲染性能与首屏体验。5.2 外部模型上下文注入如果你在 MemOS 内置 Chat API 之外使用自定义的 LLM 逻辑可以通过该接口拉取原始对话历史再手动拼接到模型的messages数组中raw_history client.get_message( user_idmemos_user_123, conversation_idconv_r_study_001, message_limit_number20 ).data.message_detail_list messages [ {role: m[role], content: m[content]} for m in raw_history ] # messages 可直接作为 OpenAI 风格 chat completion 的输入这样既能复用 MemOS 的持久化会话存储又保留了对模型调用链路的完全控制权。5.3 消息回顾性分析可以周期性导出原始会话记录用于评估 AI 回答质量例如对比回复与用户意图的匹配度、挖掘用户潜在诉求或构建数据集做二次训练与评测。由于返回的是未经摘要加工的原文分析结果不会受中间处理环节的信息损耗影响。6. 常见错误与排查指引错误码含义排查建议ValueError: conversation_id is requiredSDK 层校验拦截检查是否传入conversation_idValueError: MemOS API key is required未配置 API Key传入api_key或设置MEMOS_API_KEY环境变量40010/40011user_id/conversation_id超长控制在 100 字符以内40100/40130/40132API Key 缺失、无效或过期检查请求头Authorization: Token {api_key}与 Key 状态完整错误码对照表见 Common Error Codes 文档接口在服务端层面的鉴权与请求上下文要求可参考 API Overview。7. 相关接口get_message是消息读写闭环中的读取侧配套能力还包括写入侧client.add_message()将[{role, content}]消息数组写入指定会话见 src/memos/api/client.py支持async_mode异步落库与source渠道标记记忆侧client.get_memory()获取加工后的事实/偏好摘要用于画像展示而非原文还原对话侧client.chat()走完整的内存检索 生成链路add_message_on_answerTrue时回答会自动回写为消息与get_message形成闭环。赞分享人工智能大模型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点击查看免费下载相关推荐Yuxi 平台 Agent 消息调试面板基于原始历史消息的 Run 级会话排障实战指南Yuxi 平台 Agent 消息调试面板基于原始历史消息的 Run 级会话排障实战指南 本指南讲解 Yuxi 开源知识智能体平台中Agent 消息调试面板人工智能大模型AI AgentRAG多智能体知识图谱后端前端Message Pusher项目WebSocket API及消息状态查询详解Message Pusher项目WebSocket API及消息状态查询详解 项目概述 Message Pusher是一个轻量级的消息推送服务提供了WebSo后端即时通讯Zulip API 创建定时消息Scheduled Message完整指南POST /scheduled_messages 接口实战Zulip API 创建定时消息Scheduled Message完整指南POST /scheduled_messages 接口实战 Zulip 的 定时即时通讯后端前端WebSocket上一篇d2dx暗黑破坏神2终极现代化解决方案让经典游戏重获新生下一篇暗黑破坏神2存档编辑器零基础快速修改角色与物品的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考