核心操作

Search Memory

该接口用于检索指定用户的记忆，返回与输入查询内容最相关的记忆片段，供 Agent 使用。召回的记忆片段包括“事实记忆”、“偏好记忆”、“工具记忆”和“技能 Skill”。Skill 既可以来自用户对话自动生成，也可以来自知识库中上传的自定义 Skill 文件。

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>",
        "relativity": 0.87
      }
    ],
    "tool_memory_detail_list": [
      {
        "id": "<string>",
        "tool_type": "ToolTrajectoryMemory",
        "tool_value": "<string>",
        "tool_used_status": [
          {
            "used_tool": "<string>",
            "error_type": "<string>",
            "success_rate": 0,
            "tool_experience": "<string>"
          }
        ],
        "create_time": "<string>",
        "conversation_id": "<string>",
        "status": "activated",
        "update_time": "<string>",
        "relativity": 0,
        "experience": "<string>"
      }
    ],
    "preference_note": "<string>",
    "skill_detail_list": [
      {
        "id": "<string>",
        "skill_value": {
          "name": "<string>",
          "description": "<string>",
          "procedure": "<string>",
          "experience": [
            "<string>"
          ],
          "preference": [
            "<string>"
          ],
          "examples": [
            "<string>"
          ],
          "script": {},
          "others": {}
        },
        "skill_url": "<string>",
        "skill_type": "<string>",
        "create_time": "<string>",
        "conversation_id": "<string>",
        "status": "activated",
        "confidence": 0,
        "tags": [
          "<string>"
        ],
        "update_time": "<string>",
        "relativity": "<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上限为20k。
filter
object
记忆过滤条件，用于在检索前精确限定候选记忆范围。支持两种写法：直接传入由 and/or 组成的全局过滤条件；或按记忆来源分别传入 knowledgebase、user、public 过滤条件。可用字段包括 agent_id、app_id、tags、create_time、update_time，以及添加消息时通过 info 写入的 business_type、biz_id、scene 等自定义字段。info 中的字段在 filter 中直接按字段名使用，例如 {"scene":"chat"}，不需要包一层 info。支持比较运算符 gte、lte、gt、lt，以及 tags.contains。
Example:
"{"knowledgebase":{"and":[{"tags":{"contains":"阅读"}},{"create_time":{"gte":"2025-01-01"}},{"create_time":{"lte":"2025-12-31"}}]},"user":{"and":[{"scene":"chat"}]}}"
knowledgebase_ids
string[]
该字段用于限制当次搜索可访问的知识库范围，默认为空（即不检索任何知识库）。传入具体知识库 ID，则可检索指定的知识库；传入all，则可检索该项目下所有关联知识库。
memory_limit_number
number
default: 9
召回的记忆条数上限，在满足相关性阈值（relativity）的前提下最多返回该数量的记忆，不保证返回固定条数。默认值 9，最大值 25。
include_preference
boolean
default: true
是否启用偏好记忆召回。开启后，将根据查询的内容智能召回用户的偏好记忆。不传时该功能默认开启。
preference_limit_number
number
default: 9
召回的偏好记忆条数上限，在满足相关性阈值（relativity）的前提下最多返回该数量的记忆，不保证返回固定条数。默认值 9，最大值 25。
include_tool_memory
boolean
default: false
是否启用工具记忆召回。开启后，系统会根据查询内容智能召回工具相关的记忆。不传时该功能默认关闭。
tool_memory_limit_number
number
default: 6
限定返回的工具记忆条数，用于控制召回的工具记忆个数,仅在 include_tool_memory=true 时生效。不传时使用系统默认值6，最大值为25。
include_skill
boolean
是否启用技能（Skill）召回。开启后，系统会根据查询内容召回相关 Skill，包括用户对话自动生成的个性化 Skill，以及 knowledgebase_ids 范围内上传的自定义 Skill。不传时该功能默认关闭。
skill_limit_number
number
限定返回的技能（Skill）条数，用于控制召回的技能个数,仅在 include_skill=true 时生效。不传时使用系统默认值6，最大值为25。
relativity
number
default: 0.45
召回记忆的相关性阈值（0~1）。用于过滤低相关记忆，并与限定返回的事实、偏好记忆最大条数，共同约束最终返回结果。不传时使用系统默认阈值，取值为0时表示不进行相关性过滤。

响应体

application/json

Successful Response

code
number
required

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

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

接口提示信息。

Add Message

Get Memory