Skip to main content
GET
/
api
/
v0
/
memories
/
search
Python
# To use the Python SDK, install the package:
# pip install evermemos

from evermemos import EverMemOS

memory = EverMemOS(api_key="<api_key>").v0.memories

response = memory.search(extra_query={"user_id": "<user_id>", "query": "<query>"})
print(response.result.total_count)
{
  "message": "Memory search successful",
  "result": {
    "has_more": false,
    "memories": [
      {
        "group_id": "group_456",
        "memory_type": "episodic_memory",
        "summary": "User mentioned controlling their diet recently, eating only two meals a day, with dinner mainly being salad",
        "timestamp": "2024-01-15T10:30:00+00:00",
        "user_id": "user_123"
      }
    ],
    "metadata": {
      "episodic_count": 1,
      "latency_ms": 156,
      "profile_count": 2
    },
    "original_data": [],
    "pending_messages": [],
    "profiles": [
      {
        "category": "Dietary Preferences",
        "description": "Prefers light flavors, favoring vegetables and seafood",
        "item_type": "explicit_info",
        "score": 0.89
      },
      {
        "description": "Prioritizes dietary health, preferring low oil and low salt",
        "item_type": "implicit_trait",
        "score": 0.75,
        "trait_name": "Health Conscious"
      }
    ],
    "query_metadata": {
      "memory_type": "retrieve",
      "source": "hybrid_search",
      "user_id": "user_123"
    },
    "scores": [
      0.82
    ],
    "total_count": 3
  },
  "status": "ok"
}

Authorizations

Authorization
string
header
default:Bearer <api_key>
required

Bearer authentication header of the form Bearer 'api_key', where 'api_key' is your EverMemOS auth api key.

Body

application/json
user_id
string | null

User ID (at least one of user_id or group_id must be provided)

Example:

"user_123"

memory_types
enum<string>[]

List of memory types to retrieve, enum values from MemoryType:

  • profile: user profile (Milvus vector search only)
  • episodic_memory: episodic memory
  • foresight: prospective memory (not yet supported for search)
  • event_log: event log (not yet supported for search) Note: Only profile and episodic_memory are supported. Defaults to both if not specified.
Available options:
profile,
episodic_memory,
foresight,
event_log
Example:
["episodic_memory"]
include_metadata
boolean
default:true

Whether to include metadata

Example:

true

start_time
string | null

Time range start (ISO 8601 format with Timezone is required). Only applies to episodic_memory, ignored for profile

Example:

"2024-01-01T00:00:00+00:00"

end_time
string | null

Time range end (ISO 8601 format with Timezone is required). Only applies to episodic_memory, ignored for profile

Example:

"2024-12-31T23:59:59+00:00"

query
string | null

Search query text

Example:

"coffee preference"

retrieve_method
enum<string>
default:keyword

Retrieval method, enum values from RetrieveMethod:

  • keyword: keyword retrieval (BM25, default)
  • vector: vector semantic retrieval
  • hybrid: hybrid retrieval (keyword + vector)
  • rrf: RRF fusion retrieval (keyword + vector + RRF ranking fusion)
  • agentic: LLM-guided multi-round intelligent retrieval
Available options:
keyword,
vector,
hybrid,
rrf,
agentic
Example:

"keyword"

current_time
string | null

Current time, used to filter forward-looking events within validity period

radius
number | null

COSINE similarity threshold for vector retrieval (only for vector and hybrid methods, default 0.6)

Required range: 0 <= x <= 1
Example:

0.6

top_k
integer
default:-1

Maximum number of results to return. -1 means return all results that meet the threshold (up to 100). Valid values: -1 or 1-100.

Required range: -1 <= x <= 100
Examples:

10

-1

group_ids
string[] | null

Array of Group IDs to search (max 10 items). None means search all groups for the user.

Example:
["group_456", "group_789"]

Response

Successful Response

result
RetrieveMemResponse · object
required

Memory search result

status
string
default:ok

Response status

Examples:

"ok"

"failed"

message
string
default:""

Response message

Example:

"Operation successful"