查询记忆

该接口用于查询指定用户的记忆，返回与输入查询内容最相关的记忆片段。您可以调用这些记忆片段作为参考，供大模型生成回答时使用。如本章示例所示，您可以在用户与 AI 对话过程中实时检索用户记忆，也可以对用户整体记忆进行全局检索，用于生成用户画像或支持个性化推荐，从而提升对话的连贯性与用户的个性化体验。

在最近的更新中，召回的记忆片段除了原有的“事实记忆”，新增了对“偏好记忆”的支持，使模型回答时“更懂用户”。

POST
/
search
/
memory
import os
import requests
import json

# 替换成你的 API Key
os.environ["MEMOS_API_KEY"] = "YOUR_API_KEY"
os.environ["MEMOS_BASE_URL"] = "https://memos.memtensor.cn/api/openmem/v1"
data = {
  "query": "我国庆想出去玩，帮我推荐个没去过的城市，以及没住过的酒店品牌",
  "user_id": "memos_user_123",
  "conversation_id": "0928"
}
headers = {
  "Content-Type": "application/json",
  "Authorization": f"Token {os.environ['MEMOS_API_KEY']}"
}
url = f"{os.environ['MEMOS_BASE_URL']}/search/memory"

res = requests.post(url=url, headers=headers, data=json.dumps(data))

print(f"result: {res.json()}")

{
  "code": 0,
  "data": {
    "memory_detail_list": [
      {
        "id": "<string>",
        "memory_key": "<string>",
        "memory_value": "<string>",
        "memory_type": "LongTermMemory",
        "create_time": "<string>",
        "conversation_id": "<string>",
        "status": "activated",
        "confidence": 0.95,
        "tags": [
          "<string>"
        ],
        "update_time": "<string>",
        "relativity": 0.87
      }
    ],
    "preference_detail_list": [
      {
        "id": "<string>",
        "preference_type": "explicit_preference",
        "preference": "<string>",
        "reasoning": "<string>",
        "create_time": "<string>",
        "conversation_id": "<string>",
        "status": "activated",
        "update_time": "<string>"
      }
    ],
    "preference_note": "<string>"
  },
  "message": "<string>"
}

Authorizations

Authorization
string
header
required

Token API_key，可在 API 控制台>接口密钥 中查看

请求体

application/json
user_id
string
required

与查询的记忆关联的用户的唯一标识符。

conversation_id
string

查询内容所在会话的唯一标识符，传入可以明确当前会话，本会话的记忆应当比其他历史会话的权重高。

query
string
required

要在记忆中查询的文本内容，单次查询文本的token上限为4k。

memory_limit_number
number
default: 6

限定返回的事实记忆条数，用于控制事实记忆片段的长度，不传时使用系统默认值6，最大值为25。

include_preference
boolean
default: true

是否启用偏好记忆召回。开启后，将根据查询的内容智能召回用户的偏好记忆。不传时该功能默认开启。

preference_limit_number
number
default: 6

限定返回的偏好记忆条数，用于控制偏好记忆片段的长度，不传时使用系统默认值6，最大值为25。

响应体

application/json

Successful Response

code
number
required

接口状态码，更多内容可查阅错误码列表了解详情。

Example: 0
data
object
展示属性
message
string
required

接口提示信息。

使用示例

对话中使用记忆

在用户与 AI 对话的过程中，你可以调用 MemOS 检索与当前用户发言最相关的记忆，并将其填充到大模型的回复提示词中。

🍬 小Tips：填写 conversation_id 可以帮助 MemOS 理解当前会话的上下文，提升本会话相关记忆的权重，使对话模型的回复内容更加连贯。

如下示例所示，如果你已经参考 添加消息 > 导入历史对话，添加过用户memos_user_345 的历史对话消息，你可以一键复制该示例检索用户记忆。

import os
import json
import requests

os.environ["MEMOS_API_KEY"] = "YOUR_API_KEY"
os.environ["MEMOS_BASE_URL"] = "https://memos.memtensor.cn/api/openmem/v1"

# headers 和 base URL
headers = {
  "Authorization": f"Token {os.environ['MEMOS_API_KEY']}",
  "Content-Type": "application/json"
}
BASE_URL = os.environ['MEMOS_BASE_URL']

# 用户当前发言，直接作为 query
query_text = "国庆节我要去云南玩了，有什么美食推荐吗？"

data = {
    "user_id": "memos_user_345",
    "conversation_id": "memos_conversation_789",  # 新建了一个会话ID
    "query": query_text,
}

# 调用 /search/memory 查询相关记忆
res = requests.post(f"{BASE_URL}/search/memory", headers=headers, data=json.dumps(data))

print(f"result: {res.json()}")
# 示例返回（展示已召回的记忆片段）
# # {
#   "memory_detail_list": [
#     {
#       "id": "c6c63472-25d3-49ee-b360-9b0702d96781",
#       "memory_key": "辣味食物偏好",
#       "memory_value": "用户喜欢吃辣的食物，但不太喜欢重油的菜肴，如麻辣火锅和毛血旺。用户更偏好清爽又带辣味的菜。",
#       "memory_type": "UserMemory",
#       "create_time": 1762674694466,
#       "conversation_id": "memos_conversation_345",
#       "status": "activated",
#       "confidence": 0.99,
#       "tags": [
#         "饮食偏好",
#         "辣味",
#         "重油"
#       ],
#       "update_time": 1762674694423,
#       "relativity": 0.00242424
#     }
#   ],
#   "preference_detail_list": [
#     {
#       "id": "46d8372d-241a-4ffc-890b-ae13c90d5565",
#       "preference_type": "explicit_preference",
#       "preference": "用户喜欢辣味的食物，但不喜欢重油的辣味食物。",
#       "reasoning": "用户在第一次查询中明确表示喜欢辣的食物，在第二次查询中进一步说明自己不喜欢重油的辣味食物，这表明用户的偏好是喜欢辣但清爽的食物。",
#       "create_time": 1762675342352,
#       "conversation_id": "memos_conversation_345",
#       "status": "activated",
#       "update_time": 1762674923302
#     },
#     {
#       "id": "9d62c1ae-a069-478d-a2fd-cb4aadfb6868",
#       "preference_type": "implicit_preference",
#       "preference": "用户可能偏好较健康的饮食选择",
#       "reasoning": "用户表达了对辣味的明确喜好，但对重油食物表示不喜欢。这表明用户可能更关注饮食的健康性，倾向于选择不那么油腻的食物。用户对辣味的喜好与对重油食物的排斥结合在一起，可能暗示着对健康饮食的隐性偏好。",
#       "create_time": 1762674923448,
#       "conversation_id": "memos_conversation_345",
#       "status": "activated",
#       "update_time": 1762674851542
#     }
#   ],
#   "preference_note": "\n# 注意：\n事实记忆是事实的摘要，而偏好记忆是用户偏好的摘要。\n你的回复不得违反用户的任何偏好，无论是显式偏好还是隐式偏好，并简要解释你为什么这样回答以避免冲突。\n"
# }

获取用户整体画像

如果你需要对自己开发的应用进行用户分析，或者希望在 AI 应用中向用户实时展示他们的“个人关键印象”，可以调用 MemOS 全局检索用户的记忆，帮助大模型生成用户的个性化画像。

🍬 小Tips：此时可以不填写conversation_id哦～得到响应详情后，你可以挑选memory_type 为 UserMemory 的记忆，这类记忆提炼了与用户相关的个性化信息，适合用于生成用户画像或推荐内容。

如下示例所示，如果你已经参考 添加消息 > 记录用户偏好或行为，添加过用户memos_user_567 的历史对话消息，你可以一键复制该示例检索用户记忆。

import os
import json
import requests

os.environ["MEMOS_API_KEY"] = "YOUR_API_KEY"
os.environ["MEMOS_BASE_URL"] = "https://memos.memtensor.cn/api/openmem/v1"

# headers 和 base URL
headers = {
  "Authorization": f"Token {os.environ['MEMOS_API_KEY']}",
  "Content-Type": "application/json"
}
BASE_URL = os.environ['MEMOS_BASE_URL']

# 直接询问人物画像，作为 query
query_text = "我的人物关键词是什么？"

data = {
    "user_id": "memos_user_567",
    "query": query_text,
}

# 调用 /search/memory 查询相关记忆
res = requests.post(f"{BASE_URL}/search/memory", headers=headers, data=json.dumps(data))

print(f"result: {res.json()}")

# 示例返回（展示已召回的记忆片段）
# {
#   "memory_detail_list": [
#     {
#       "id": "00d8bb4e-aa8c-4fee-a83e-bf67ed6c3ea1",
#       "memory_key": "希望AI帮助的事项",
#       "memory_value": "用户希望AI帮助规划日常学习计划、推荐电影和书籍，以及提供心情陪伴。",
#       "memory_type": "WorkingMemory",
#       "create_time": 1762675190743,
#       "conversation_id": "memos_conversation_id_567",
#       "status": "activated",
#       "confidence": 0.99,
#       "tags": [
#         "帮助",
#         "学习计划",
#         "推荐",
#         "陪伴"
#       ],
#       "update_time": 1762675209112,
#       "relativity": 0.00013480317
#     },
#     {
#       "id": "17f039d5-d034-41e9-a385-765992a4ab00",
#       "memory_key": "希望AI提供的帮助类型",
#       "memory_value": "用户希望AI提供建议、信息查询和灵感。",
#       "memory_type": "WorkingMemory",
#       "create_time": 1762675153211,
#       "conversation_id": "memos_conversation_id_567",
#       "status": "activated",
#       "confidence": 0.99,
#       "tags": [
#         "AI",
#         "帮助",
#         "类型"
#       ],
#       "update_time": 1762675206651,
#       "relativity": 0.00010301525
#     },
#     {
#       "id": "89bc2453-1471-4a1a-936c-94708da071ed",
#       "memory_key": "聊天风格偏好",
#       "memory_value": "用户喜欢的聊天风格为幽默、温暖和轻松闲聊。",
#       "memory_type": "WorkingMemory",
#       "create_time": 1762675135023,
#       "conversation_id": "memos_conversation_id_567",
#       "status": "activated",
#       "confidence": 0.99,
#       "tags": [
#         "聊天",
#         "风格",
#         "偏好"
#       ],
#       "update_time": 1762675205606,
#       "relativity": 0.00007810917
#     },
#     {
#       "id": "074b5caf-d294-41a6-9f7e-9c2a8b1d3ade",
#       "memory_key": "感兴趣的话题",
#       "memory_value": "用户最感兴趣的话题包括人工智能、未来科技和电影评论。",
#       "memory_type": "WorkingMemory",
#       "create_time": 1762675172952,
#       "conversation_id": "memos_conversation_id_567",
#       "status": "activated",
#       "confidence": 0.99,
#       "tags": [
#         "话题",
#         "兴趣"
#       ],
#       "update_time": 1762675207841,
#       "relativity": 0.000029795949
#     },
#     {
#       "id": "6e1a0715-5c83-4092-b226-762cc3500170",
#       "memory_key": "书籍类型偏好",
#       "memory_value": "用户喜欢的书籍类型包括科普、技术和自我成长类书籍。",
#       "memory_type": "WorkingMemory",
#       "create_time": 1762675029885,
#       "conversation_id": "memos_conversation_id_567",
#       "status": "activated",
#       "confidence": 0.99,
#       "tags": [
#         "书籍",
#         "类型",
#         "偏好"
#       ],
#       "update_time": 1762675194083,
#       "relativity": 0.00002005097
#     },
#     {
#       "id": "5ee1c8c2-ea55-42e7-8fd8-71d0127198b5",
#       "memory_key": "电视剧类型偏好",
#       "memory_value": "用户喜欢的电视剧类型为悬疑和历史剧。",
#       "memory_type": "UserMemory",
#       "create_time": 1762675002841,
#       "conversation_id": "memos_conversation_id_567",
#       "status": "activated",
#       "confidence": 0.99,
#       "tags": [
#         "电视剧",
#         "类型",
#         "偏好"
#       ],
#       "update_time": 1762675002788,
#       "relativity": 0.00001729489
#     }
#   ],
#   "preference_detail_list": [],
#   "preference_note": ""
# }

获取消息

该接口用于获取指定会话的用户与助手历史对话记录，可按数量限制返回结果。如本章示例所示，您可以将返回的最近消息作为大模型生成回答的参考，以保持对话的连贯性和上下文理解；同时，也可在用户刷新或重新打开应用时恢复聊天上下文，确保用户体验连续一致，并为个性化交互提供支持。