企业官网建设流程全解析

• 人工智能
• 大模型
• Agent 记忆
• AI Agent
• RAG
• 知识图谱
• dsh-plugin

MemOS 开源版提供了一组基于 FastAPI 的 REST API 服务（架构与鉴权总览见 open_source_api 概述），其中POST /product/get/message用于拉取指定会话中用户与助手的原始对话记录，是与返回事实摘要的“记忆”接口互补的核心数据通道。本文从接口定位、参数语义、底层工作机理出发，结合仓库源码 client.py 与 product_models.py 中的实现细节，给出可直接运行的调用示例与聊天历史回溯、上下文注入等实战方案。

1. 接口速览

说明：本文聚焦开源项目的功能说明。云端版本的完整接口字段与配额限制，请以对应平台的 API 文档为准。

2. 记忆（Memory）与消息（Message）的区分

在开发过程中，务必区分系统返回的两类数据，二者在语义、加工深度与用途上完全不同：

从源码看，两者的响应模型也做了严格区分：MemOSGetMemoryResponse 承载memory_detail_list等记忆视图，而MemOSGetMessagesResponse的 data 是 GetMessagesData，其内部仅包含message_detail_list（消息详情列表），每条消息通过MessageDetail模型（extra="allow"，即对额外字段宽松兼容）承载 role、content 等原始字段。开发者不应将两者混用。

3. 关键接口参数详解

本接口支持的请求参数如下表（对应 client.py 中get_message()的 payload 构造逻辑）：

关于conversation_id的源码级说明：虽然参数表标记为“否”，但客户端实现中get_message()会调用_validate_required_params(user_id=user_id, conversation_id=conversation_id)（client.py），即一旦该参数被显式传入为空值就会抛出ValueError。仓库测试 test_get_message_requires_conversation_id 明确断言了这一点：不传conversation_id调用client.get_message(user_id="user-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/message（client.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 使用开源版内置的MemOSClient

from memos.api.client import MemOSClient # 初始化客户端：base_url 指向开源版本地服务 client = MemOSClient( api_key="YOUR_LOCAL_API_KEY", base_url="http://localhost:8000/product" ) # 获取指定会话的最近 10 条对话记录 res = client.get_message( user_id="memos_user_123", conversation_id="conv_r_study_001", message_limit_number=10 ) 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_key>（client.py）。
• 响应体为MemOSGetMessagesResponse，包含code、message与data三段（product_models.py）；data.message_detail_list中每条MessageDetail的 role / content 字段即原始对话。

5.2 使用原生 HTTP 请求

不依赖 SDK 时，可以直接构造 HTTP POST：

import requests import json res = requests.post( "http://localhost:8000/product/get/message", headers={ "Content-Type": "application/json", "Authorization": "Token YOUR_LOCAL_API_KEY", }, data=json.dumps({ "user_id": "memos_user_123", "conversation_id": "conv_r_study_001", "conversation_limit_number": 6, "message_limit_number": 10, "source": "web_chat", }), timeout=30, ) 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（如 20～50），快速渲染最近对话；
• 配合“加载更多”按钮，以消息条数为游标实现分页加载，降低单次响应体与前端渲染压力；
• 结合conversation_limit_number在会话列表中展示多个会话的最近消息摘要。

6.2 外部模型上下文注入

如果您正在使用自定义的大模型逻辑（非 MemOS 内置 chat 接口），可以通过此接口获取原始对话历史，并将其手动拼接至模型的messages数组中：

history = client.get_message( user_id="memos_user_123", conversation_id="conv_r_study_001", message_limit_number=12, ) 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. 异常与错误排查

当调用失败时，可对照 错误码参考 定位问题：

8. 关联源码与文档索引

• SDK 方法实现：src/memos/api/client.py（get_message，含参数校验、payload 构造、重试逻辑）
• 响应模型定义：src/memos/api/product_models.py（MessageDetail、GetMessagesData）与 src/memos/api/product_models.py（MemOSGetMessagesResponse）
• 请求上下文中间件：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 Agent
• RAG
• 知识图谱
• dsh-plugin