Skip to main content
GET
/
api
/
v1
/
memories
/
search
Search memories
curl --request GET \
  --url https://api.evermind.ai/api/v1/memories/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "user_123",
  "group_id": "group_456",
  "memory_types": [
    "profile"
  ],
  "top_k": 40,
  "include_metadata": true,
  "start_time": "2024-01-01T00:00:00",
  "end_time": "2024-12-31T23:59:59",
  "query": "coffee preference",
  "retrieve_method": "keyword",
  "current_time": "<string>",
  "radius": 0.6
}
'
{
  "message": "Memory search successful, retrieved 1 groups",
  "result": {
    "has_more": false,
    "importance_scores": [
      0.85
    ],
    "memories": [
      {
        "episodic_memory": [
          {
            "group_id": "group_456",
            "memory_type": "episodic_memory",
            "summary": "Discussed coffee choices",
            "timestamp": "2024-01-15T10:30:00",
            "user_id": "user_123"
          }
        ]
      }
    ],
    "metadata": {
      "memory_type": "retrieve",
      "source": "episodic_memory_es_repository",
      "user_id": "user_123"
    },
    "original_data": [],
    "pending_messages": [],
    "query_metadata": {
      "memory_type": "retrieve",
      "source": "episodic_memory_es_repository",
      "user_id": "user_123"
    },
    "scores": [
      {
        "episodic_memory": [
          0.95
        ]
      }
    ],
    "total_count": 45
  },
  "status": "ok"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Memory retrieve/search request

Used for GET /api/v1/memories/search endpoint. Supports passing parameters via query params or body.

​
user_id
string | null

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

Example:

"user_123"

​
group_id
string | null

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

Example:

"group_456"

​
memory_types
enum<string>[]

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

  • episodic_memory: episodic memory
  • foresight: prospective memory
  • event_log: event log (atomic facts)
  • Note: profile type is not supported in search interface
Available options:
profile,
episodic_memory,
foresight,
event_log
Example:
["episodic_memory"]
​
top_k
integer
default:40

Maximum number of results to return

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

10

​
include_metadata
boolean
default:true

Whether to include metadata

Example:

true

​
start_time
string | null

Time range start (ISO 8601 format)

Example:

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

​
end_time
string | null

Time range end (ISO 8601 format)

Example:

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

​
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

Response

Successful Response

Memory search API response

Response for GET /api/v1/memories/search endpoint.

​
result
RetrieveMemResponse · object
required

Memory search result

​
status
string
default:ok

Response status

Examples:

"ok"

"failed"

​
message
string
default:""

Response message

Example:

"Operation successful"