Core Operations

Search Memory

This API queries a user’s memory and returns the fragments most relevant to the input for the Agent to use. Returned memory can include Fact Memory, Preference Memory, Tool Memory, and Skill. Skills can be auto-generated from user conversations or uploaded as custom Skill files in a Knowledge Base.

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": "A user wants to return headphones purchased three days ago",
  "user_id": "memos_user_123",
  "conversation_id": "0928",
  "knowledgebase_ids": ["kb_xxx"],
  "include_skill": True
}
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
Memory filter conditions used to precisely limit candidate memories before retrieval. Supports two formats: pass a global filter condition composed of and/or directly, or pass source-specific filters under knowledgebase, user, and public. Available fields include agent_id, app_id, tags, create_time, update_time, and custom fields written through info when adding messages, such as business_type, biz_id, and scene. Fields in info are used directly by field name in filter, for example {"scene":"chat"}; do not wrap them in another info object. Supports comparison operators gte, lte, gt, lt, and tags.contains.
Example:
"{"knowledgebase":{"and":[{"tags":{"contains":"reading"}},{"create_time":{"gte":"2025-01-01"}},{"create_time":{"lte":"2025-12-31"}}]},"user":{"and":[{"scene":"chat"}]}}"
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 recalls relevant Skills based on the query, including personalized Skills auto-generated from user conversations and custom Skills uploaded within the knowledgebase_ids scope. 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.45
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