Core Operations

Search Memory

This API retrieves memories for a specified user or Agent and returns the fragments most relevant to the query.

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
      }
    ],
    "profile_detail_list": [
      {
        "id": "<string>",
        "memory": "<string>",
        "memory_type": "ProfileMemory",
        "template_id": "<string>",
        "profile_category": "<string>",
        "profile_field": "<string>",
        "profile_path": "<string>",
        "status": "activated",
        "created_at": "<string>",
        "updated_at": "<string>",
        "confidence": 0,
        "relativity": 0,
        "algorithm_updatable": true
      }
    ],
    "event_detail_list": [
      {
        "id": "<string>",
        "event_key": "<string>",
        "event_value": "<string>",
        "event_type": "<string>",
        "create_time": "<string>",
        "conversation_id": "<string>",
        "status": "activated",
        "update_time": "<string>",
        "relativity": 0,
        "event_time": [
          "<string>"
        ],
        "event_location": [
          "<string>"
        ],
        "event_roles": [
          "<string>"
        ]
      }
    ],
    "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 narrow candidate memories before semantic recall. You can use and / or at the root for global filtering, or filter by source under user, public, and knowledgebase. For complete fields and examples, see Memory Filters.
Show child attributes
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.
include_memory_view
string[]
default: [ "detail_factual", "preference" ]
Allowed memory types to retrieve. When omitted, fact memories (detail_factual) and preference memories (preference) are recalled by default. See Memory Categories for details.
Enum:"detail_factual""preference""skill""profile""event""tool_memory"
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.
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 Memories