Skip to main content
GET
/
api
/
v1
/
memories
/
search
Search relevant memories (supports keyword/vector/hybrid search)
curl --request GET \
  --url https://api.example.com/api/v1/memories/search \
  --header 'Content-Type: application/json' \
  --data '
{
  "memory_types": [
    "episode_memory"
  ],
  "query": "coffee preference",
  "retrieve_method": "keyword",
  "top_k": 10,
  "user_id": "user_123"
}
'
{
  "status": "ok",
  "message": "Memory retrieval successful",
  "result": {
    "groups": [
      {
        "group_id": "group_456",
        "memories": [
          {
            "memory_type": "episode_memory",
            "user_id": "user_123",
            "timestamp": "2024-01-15T10:30:00",
            "summary": "Discussed coffee preference",
            "group_id": "group_456"
          }
        ],
        "scores": [
          0.95
        ],
        "original_data": []
      }
    ],
    "importance_scores": [
      0.85
    ],
    "total_count": 45,
    "has_more": false,
    "query_metadata": {
      "source": "episodic_memory_es_repository",
      "user_id": "user_123",
      "memory_type": "retrieve"
    },
    "metadata": {
      "source": "episodic_memory_es_repository",
      "user_id": "user_123",
      "memory_type": "retrieve"
    }
  }
}

Body

application/json

Search memories request parameters

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"

​
query
string | null

Search query text

Example:

"coffee preference"

​
retrieve_method
string | null
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
Example:

"keyword"

​
top_k
integer | null
default:10

Maximum number of results to return

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

10

​
memory_types
string[] | null

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
Example:
["episodic_memory"]
​
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"

​
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

​
include_metadata
boolean | null
default:true

Whether to include metadata

Example:

true

​
filters
Filters · object

Additional filter conditions

Example:
{}

Response

Successfully retrieved memory data

The response is of type Response Search Memories Api V1 Memories Search Get · object.