Search Memory

This API allows you to query a user’s memory and returns the fragments most relevant to the input. These can serve as references for the model when generating responses. As shown in the examples bellow, You can retrieve memory in real time during a user’s conversation with the AI, or perform a global search across their entire memory to create user profiles or support personalized recommendations, improving both dialogue coherence and personalization.

In the latest update, in addition to “Fact Memory”, the system now supports “Preference Memory”, enabling LLM to respond in a way that better understands the user.

POST
/
search
/
memory
import os
import requests
import json

# Replace with your API Key
os.environ["MEMOS_API_KEY"] = "YOUR_API_KEY"
os.environ["MEMOS_BASE_URL"] = "https://memos.memtensor.cn/api/openmem/v1"

data = {
  "query": "I want to travel during the National Day holiday. Please recommend a city I haven’t been to and a hotel brand I haven’t stayed at.",
  "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": "<string>",
        "preference_type": "explicit_preference",
        "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, available in API Console > API Keys

Body

application/json
user_id
string
required

Unique identifier of the user associated with the memory being queried.

conversation_id
string

Unique identifier of the conversation containing the memory. Providing this ensures the current conversation’s memories have higher priority over other historical.

query
string
required

Text content to search within the memories.The token limit for a single query is 4k.

filter
object

Filter conditions, used to precisely limit the memory scope before retrieval.Available fields include: "agent_id", "app_id", "create_time", "update_time", and specific fields in "info". Supports logical operators (and, or) and comparison operators (gte, lte, gt, lt). For the "info" field, supports filtering by "business_type", "biz_id", "scene", and other custom fields.

Example:
"{"and": [{"create_time":{"gte":"..."}}]}"
knowledgebase_ids
string[]

Specifies the scope of knowledge bases accessible for the current search. Defaults to empty, meaning no knowledge bases are searched.Pass specific Knowledgebase IDs to search within that designated repository; pass "all" to search across all associated knowledgebases within the project.

memory_limit_number
number
default: 9

Maximum number of memories that can be recalled: as long as the relevance threshold (relativity) is met, up to this many memories may be returned. Default is 9, maximum is 25.

include_preference
boolean
default: true

Whether to enable preference memory recall. When enabled, the system will intelligently retrieve the user’s preference memories based on the query. Defaults to true if not provided.

preference_limit_number
number
default: 9

Maximum number of preference memories that can be recalled: as long as the relevance threshold (relativity) is met, up to this many preferred memories may be returned. Default is 9, maximum is 25.

include_tool_memory
boolean
default: false

Whether to enable tool memory recall. When enabled, the system will intelligently retrieve tool-related memories based on the query. Default is false if not provided.

tool_memory_limit_number
number
default: 6

Limits the number of tool memory items returned, controlling the count of recalled tool memories. Effective only when include_tool_memory=true. Default is 6 if not provided, max is 25.

include_skill
boolean

Whether to enable Skill recall. When enabled, the system will intelligently recall memories related to tools based on the query content. Default is disabled if not provided.

skill_limit_number
number

Limits the number of returned Skills, controlling the count of recalled skills. Effective only when `include_skill=true`. Default is 6 if not provided, max is 25.

relativity
number
default: 0

Relevance threshold (0–1) for recalled memories. Filters out low-relevance memories and, together with the maximum counts for factual and preferred recalls, constrains the final results. When omitted, the system default threshold is used. A value of 0 disables relevance filtering.

Response

application/json

Successful Response

code
number
required

API status code. See Error Code for details.

Example: 0
data
object

Object containing the query result.

Show child attributes
message
string
required

API response message.

Add Message

Get Memory