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>"
      }
    ],
    "tool_memory_detail_list": [
      {
        "id": "<string>",
        "tool_type": "ToolTrajectoryMemory",
        "tool_value": "<string>",
        "tool_used_status": [
          {
            "used_tool": "<string>",
            "experience": "<string>",
            "error_type": "<string>",
            "success_rate": "<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, 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[]

This field is used to restrict the scope of knowledge bases that can be accessed in a single search. It is empty by default and can be used for implementing frontend permission control.

memory_limit_number
number
default: 6

Limits the number of fact memory items returned, controlling the length of fact memory. Defaults to 6 if not provided. The maximum allowed value 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: 6

Limits the number of preference memory items returned, controlling the length of fact memory. Defaults to 6 if not provided. The maximum allowed value 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.

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

Delete Memory