Skip to main content
POST
/
v2
/
memories
/
search
Search Memories
curl --request POST \
  --url https://api.memmachine.ai/v2/memories/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "query": "What was the user's last conversation about finance?",
  "project_id": "",
  "expand_context": 0,
  "filter": "metadata.user_id=123 AND metadata.session_id=abc",
  "score_threshold": 0,
  "top_k": 5,
  "types": [
    "episodic",
    "semantic"
  ]
}
EOF
{
  "content": {
    "episodic_memory": {
      "long_term_memory": {
        "episodes": [
          {
            "content": "<string>",
            "producer_id": "<string>",
            "producer_role": "<string>",
            "uid": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "episode_type": "message",
            "metadata": {},
            "produced_for_id": "<string>",
            "score": 123
          }
        ]
      },
      "short_term_memory": {
        "episode_summary": [
          "<string>"
        ],
        "episodes": [
          {
            "content": "<string>",
            "producer_id": "<string>",
            "producer_role": "<string>",
            "uid": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "episode_type": "message",
            "metadata": {},
            "produced_for_id": "<string>",
            "score": 123
          }
        ]
      }
    },
    "semantic_memory": [
      {
        "category": "<string>",
        "feature_name": "<string>",
        "tag": "<string>",
        "value": "<string>",
        "metadata": {
          "citations": [
            "<string>"
          ],
          "id": "<string>",
          "other": {}
        },
        "set_id": "<string>"
      }
    ]
  },
  "status": 0
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json

Specification model for searching memories.

​
query
string
required

The natural language query used for semantic memory search. This should be a descriptive string of the information you are looking for.

Example:

"What was the user's last conversation about finance?"

​
project_id
string
default:""

The identifier of the project. If empty, the user's default project is used.

Pattern: ^[\p{L}\p{N}_:-]*$
​
expand_context
integer
default:0

The number of additional episodes to include around each matched episode from long term memory for better context.

Example:

0

​
filter
string
default:""

An optional string filter applied to the memory metadata. This uses a simple query language (e.g., 'metadata.user_id=123') for exact matches. Multiple conditions can be combined using AND operators. The metadata fields are prefixed with 'metadata.' to distinguish them from other fields.

Example:

"metadata.user_id=123 AND metadata.session_id=abc"

​
score_threshold
number | null

The minimum score for a memory to be included in the search results. Defaults to -inf (no threshold) represented as None. Meaningful only for certain ranking methods.

Example:

0

​
top_k
integer
default:10

The maximum number of memories to return in the search results.

Example:

5

​
types
enum<string>[]

A list of memory types to include in the search (e.g., episodic, semantic). If empty, all available types are searched.

Memory type.

Available options:
semantic,
episodic
Example:
["episodic", "semantic"]

Response

Successful Response

Response model for memory search results.

​
content
SearchResultContent · object
required

Payload for SearchResult.content returned by /memories/search.

​
status
integer
default:0

The status code of the search operation. 0 typically indicates success.

Example:

0