Skip to main content
POST
/
api
/
v2
/
memories
/
search
Search Memories
curl --request POST \
  --url http://localhost:8080/api/v2/memories/search \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "org_id": "universal",
  "project_id": "universal",
  "top_k": 10,
  "filter": "",
  "set_metadata": {},
  "expand_context": 0,
  "score_threshold": 0,
  "types": [
    "semantic"
  ],
  "agent_mode": false
}
'
{
  "content": {
    "episodic_memory": {
      "long_term_memory": {
        "episodes": [
          {
            "content": "<string>",
            "producer_id": "<string>",
            "producer_role": "<string>",
            "uid": "<string>",
            "produced_for_id": "<string>",
            "episode_type": "message",
            "metadata": {},
            "created_at": "2023-11-07T05:31:56Z",
            "score": 123
          }
        ]
      },
      "short_term_memory": {
        "episodes": [
          {
            "content": "<string>",
            "producer_id": "<string>",
            "producer_role": "<string>",
            "uid": "<string>",
            "produced_for_id": "<string>",
            "episode_type": "message",
            "metadata": {},
            "created_at": "2023-11-07T05:31:56Z",
            "score": 123
          }
        ],
        "episode_summary": [
          "<string>"
        ]
      }
    },
    "semantic_memory": [
      {
        "category": "<string>",
        "tag": "<string>",
        "feature_name": "<string>",
        "value": "<string>",
        "set_id": "<string>",
        "metadata": {
          "citations": [
            "<string>"
          ],
          "id": "<string>",
          "other": {}
        }
      }
    ]
  },
  "status": 0
}

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?"

​
org_id
string
default:universal
The unique identifier of the organization.

- Must not contain slashes (`/`).
- Must contain only letters, numbers, underscores, hyphens, colon, and Unicode
  characters (e.g., Chinese/Japanese/Korean). No slashes or other symbols
  are allowed.

This value determines the namespace the project belongs to.
Examples:

"MemVerge"

"AI_Labs"

​
project_id
string
default:universal
The identifier of the project.

- Must be unique within the organization.
- Must not contain slashes (`/`).
- Must contain only letters, numbers, underscores, hyphens, colon, and Unicode
  characters (e.g., Chinese/Japanese/Korean). No slashes or other symbols
  are allowed.

This ID is used in API paths and resource locations.
Examples:

"memmachine"

"research123"

"qa_pipeline"

​
top_k
integer
default:10
The maximum number of memories to return in the search results.
Examples:

5

10

20

​
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"

​
set_metadata
Set Metadata · object
Optional metadata key-value pairs used to filter or identify semantic sets.
​
expand_context
integer
default:0
The number of additional episodes to include around each matched
episode from long term memory for better context.
Examples:

0

3

6

​
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

​
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"]
​
agent_mode
boolean
default:false
Whether to enable top-level retrieval-agent orchestration for episodic search.
When false, episodic search uses direct memory retrieval.
Examples:

false

true

Response

Successful Response

Response model for memory search results.

​
content
SearchResultContent · object
required
The dictionary containing the memory search results (e.g., list of memory
objects).
​
status
integer
default:0
The status code of the search operation. 0 typically indicates success.
Example:

0