MemOS 获取消息接口（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 开源版提供了一组基于 FastAPI 的 REST API 服务架构与鉴权总览见 open_source_api 概述其中POST /product/get/message用于拉取指定会话中用户与助手的原始对话记录是与返回事实摘要的“记忆”接口互补的核心数据通道。本文从接口定位、参数语义、底层工作机理出发结合仓库源码 client.py 与 product_models.py 中的实现细节给出可直接运行的调用示例与聊天历史回溯、上下文注入等实战方案。1. 接口速览项目内容接口路径POST /product/get/message功能描述获取指定会话中用户与助手的原始对话文本未经摘要加工的 message 记录是构建聊天历史回溯功能的核心接口鉴权方式请求 Header 携带Authorization: Token API_KEY开源环境本地自定义 API Key对应 SDK 方法MemOSClient.get_message()client.py响应模型MemOSGetMessagesResponseproduct_models.py说明本文聚焦开源项目的功能说明。云端版本的完整接口字段与配额限制请以对应平台的 API 文档为准。2. 记忆Memory与消息Message的区分在开发过程中务必区分系统返回的两类数据二者在语义、加工深度与用途上完全不同维度获取记忆/get/memory获取消息/get/message返回内容系统处理后的事实与偏好摘要原始对话文本示例“用户喜欢 R 语言进行可视化”“我最近在自学 R 语言推荐个可视化包”加工程度经过抽取、归纳、去噪的结构化结果未经加工、逐条保留的会话原文典型用途长期记忆检索、用户画像、偏好注入聊天 UI 历史加载、模型上下文拼接、消息回溯分析从源码看两者的响应模型也做了严格区分MemOSGetMemoryResponse 承载memory_detail_list等记忆视图而MemOSGetMessagesResponse的 data 是 GetMessagesData其内部仅包含message_detail_list消息详情列表每条消息通过MessageDetail模型extraallow即对额外字段宽松兼容承载 role、content 等原始字段。开发者不应将两者混用。3. 关键接口参数详解本接口支持的请求参数如下表对应 client.py 中get_message()的 payload 构造逻辑参数名类型必填默认值说明user_idstr是-与获取消息关联的用户唯一标识符贯穿请求上下文用于归属校验conversation_idstr是*None指定会话的唯一标识符客户端会强制校验其非空见下文message_limit_numberint否6限制返回的消息条数最大建议值为 50conversation_limit_numberint否6限制返回的会话历史条数sourcestr否None标识消息的来源渠道可用于区分不同入口写入的数据关于conversation_id的源码级说明虽然参数表标记为“否”但客户端实现中get_message()会调用_validate_required_params(user_iduser_id, conversation_idconversation_id)client.py即一旦该参数被显式传入为空值就会抛出ValueError。仓库测试 test_get_message_requires_conversation_id 明确断言了这一点不传conversation_id调用client.get_message(user_iduser-1)会直接抛出conversation_id is required且不会发出任何 HTTP 请求。因此在实际使用中请始终为get_message提供会话 ID。关于默认限额的源码级说明get_message()中message_limit_number与conversation_limit_number的默认值为None由服务端兜底为文档所述默认值 6测试 test_get_message_uses_playground_default_limits 验证了不传限额参数时 payload 中这两个字段为None的行为。同时可参照/get/memory的做法client.py 中size超过 50 会直接抛错将 50 作为单次拉取条数的安全上限。4. 工作原理从文档描述与仓库实现中间件 request_context.py、客户端 client.py可以归纳出该接口的完整工作链路4.1 定位会话系统根据请求提供的conversation_id在底层存储中检索属于该用户及会话的消息记录user_id作为归属标识贯穿检索过程。客户端在构造请求时会将这些参数组装为 JSON payload通过requests.post发送到{base_url}/get/messageclient.py。4.2 切片处理根据message_limit_number参数系统从最新消息开始倒序截取指定条数确保返回的是最近的对话conversation_limit_number则限制一次可取回的会话历史条数。二者配合可实现“按会话粒度 按消息粒度”的双层截取避免单次响应体过大。4.3 安全隔离所有请求均通过RequestContextMiddleware中间件request_context.py每个请求会提取或生成trace_id支持g-trace-id、x-trace-id、trace-id三个 Header 的优先级探测并注入RequestContext含api_path、env、user_type、user_name、source等字段严格校验user_id的归属权防止越权访问。开源环境生产部署时官方建议在此中间件基础上扩展 OAuth2 或更高级的身份校验逻辑见 overview.md 的鉴权章节。4.4 网络重试与超时客户端内置最多 3 次重试MAX_RETRY_COUNT单次请求超时时间为 30 秒失败时打印Failed to get messages (retry x/3)日志重试耗尽后向上抛出异常client.py保障了消息拉取的稳定性。5. 快速上手示例5.1 使用开源版内置的MemOSClientfrom memos.api.client import MemOSClient # 初始化客户端base_url 指向开源版本地服务 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: # 响应 data 为 GetMessagesData内部含 message_detail_list for msg in res.data.message_detail_list: print(f[{msg[role]}]: {msg[content]})说明MemOSClient的初始化支持base_url、api_key参数也支持从环境变量MEMOS_BASE_URL、MEMOS_API_KEY读取未显式指定时默认指向云端地址MEMOS_IS_GLOBAL为真时使用https://api.memt.ai/platform/api/openmem/v1否则使用https://memos.memtensor.cn/api/openmem/v1见 client.py。开源部署请务必传入本地http://localhost:8000/product。请求头自动携带Content-Type: application/json与Authorization: Token api_keyclient.py。响应体为MemOSGetMessagesResponse包含code、message与data三段product_models.pydata.message_detail_list中每条MessageDetail的 role / content 字段即原始对话。5.2 使用原生 HTTP 请求不依赖 SDK 时可以直接构造 HTTP POSTimport requests import json res requests.post( http://localhost:8000/product/get/message, headers{ Content-Type: application/json, Authorization: Token YOUR_LOCAL_API_KEY, }, datajson.dumps({ user_id: memos_user_123, conversation_id: conv_r_study_001, conversation_limit_number: 6, message_limit_number: 10, source: web_chat, }), timeout30, ) res.raise_for_status() data res.json() for msg in data[data][message_detail_list]: print(f[{msg[role]}]: {msg[content]})6. 典型使用场景6.1 聊天 UI 历史加载当用户点击进入某个历史会话时调用此接口可恢复对话现场。建议首次进入时设置一个适中的message_limit_number如 2050快速渲染最近对话配合“加载更多”按钮以消息条数为游标实现分页加载降低单次响应体与前端渲染压力结合conversation_limit_number在会话列表中展示多个会话的最近消息摘要。6.2 外部模型上下文注入如果您正在使用自定义的大模型逻辑非 MemOS 内置 chat 接口可以通过此接口获取原始对话历史并将其手动拼接至模型的messages数组中history client.get_message( user_idmemos_user_123, conversation_idconv_r_study_001, message_limit_number12, ) messages [{role: system, content: 你是一个乐于助人的助手。}] for msg in history.data.message_detail_list: messages.append({role: msg[role], content: msg[content]}) # messages 即可直接作为 LLM 的上下文传入6.3 消息回溯分析可以定期导出原始对话记录用于评估 AI 的回复质量对照用户提问与模型回答分析用户的潜在意图与高频话题作为离线数据集的构建原料配合 MemOS 评价体系 中的相关脚本进行效果度量。7. 异常与错误排查当调用失败时可对照 错误码参考 定位问题错误码含义与本接口相关的排查建议40000 / 40002 / 40003请求参数错误 / 必填参数为空 / 参数为空检查user_id、conversation_id是否完整非空参数类型是否正确40010用户 ID 过长user_id长度不能超过 100 字符40011会话 ID 过长conversation_id长度不能超过 100 字符40100 / 40130 / 40132API Key 缺失或无效检查 Header 中的Authorization: Token API_KEY50004记忆服务暂时不可用稍后重试消息获取操作客户端本身会重试 3 次50144保存聊天历史记录失败若历史写不进去读取自然为空先检查写入链路/add/message8. 关联源码与文档索引SDK 方法实现src/memos/api/client.pyget_message含参数校验、payload 构造、重试逻辑响应模型定义src/memos/api/product_models.pyMessageDetail、GetMessagesData与 src/memos/api/product_models.pyMemOSGetMessagesResponse请求上下文中间件src/memos/api/middleware/request_context.py客户端测试tests/api/test_client.py必填校验与默认限额行为接口总览与鉴权说明docs/cn/open_source/open_source_api/start/overview.md对比阅读记忆获取接口 get_memory.md、建议问题接口 get_suggestion_queries.md、反馈接口 feedback.md赞分享人工智能大模型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点击查看免费下载相关推荐ViMax 实操多智能体 AI 视频生成从一句话到成片的完整路径ViMax 实操多智能体 AI 视频生成从一句话到成片的完整路径 想让一句灵感变成一段完整短片或者让一份剧本直接变成带分镜的视频但又不想从零学编剧、分镜人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-plugin如何用chat4cj分页拉取历史消息channels.history的6个可选参数实战指南如何用chat4cj分页拉取历史消息channels.history的6个可选参数实战指南 chat4cj 是一个用 Cangjie 语言 编写的 Rocke后端即时通讯Zulip API 创建定时消息Scheduled Message完整指南POST /scheduled_messages 接口实战Zulip API 创建定时消息Scheduled Message完整指南POST /scheduled_messages 接口实战 Zulip 的 定时即时通讯后端前端WebSocket创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考