Search Memories

curl --request POST \
  --url http://localhost:8080/api/v2/memories/search \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "query": "What was the user's last conversation about finance?",
  "org_id": "MemVerge",
  "project_id": "memmachine",
  "top_k": 5,
  "filter": "metadata.user_id=123 AND metadata.session_id=abc",
  "set_metadata": {},
  "expand_context": 0,
  "score_threshold": 0,
  "types": [
    "episodic",
    "semantic"
  ],
  "agent_mode": false
}
EOF

import requests

url = "http://localhost:8080/api/v2/memories/search"

payload = {
    "query": "What was the user's last conversation about finance?",
    "org_id": "MemVerge",
    "project_id": "memmachine",
    "top_k": 5,
    "filter": "metadata.user_id=123 AND metadata.session_id=abc",
    "set_metadata": {},
    "expand_context": 0,
    "score_threshold": 0,
    "types": ["episodic", "semantic"],
    "agent_mode": False
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: 'What was the user\'s last conversation about finance?',
    org_id: 'MemVerge',
    project_id: 'memmachine',
    top_k: 5,
    filter: 'metadata.user_id=123 AND metadata.session_id=abc',
    set_metadata: {},
    expand_context: 0,
    score_threshold: 0,
    types: ['episodic', 'semantic'],
    agent_mode: false
  })
};

fetch('http://localhost:8080/api/v2/memories/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8080",
  CURLOPT_URL => "http://localhost:8080/api/v2/memories/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'query' => 'What was the user\'s last conversation about finance?',
    'org_id' => 'MemVerge',
    'project_id' => 'memmachine',
    'top_k' => 5,
    'filter' => 'metadata.user_id=123 AND metadata.session_id=abc',
    'set_metadata' => [
        
    ],
    'expand_context' => 0,
    'score_threshold' => 0,
    'types' => [
        'episodic',
        'semantic'
    ],
    'agent_mode' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:8080/api/v2/memories/search"

	payload := strings.NewReader("{\n  \"query\": \"What was the user's last conversation about finance?\",\n  \"org_id\": \"MemVerge\",\n  \"project_id\": \"memmachine\",\n  \"top_k\": 5,\n  \"filter\": \"metadata.user_id=123 AND metadata.session_id=abc\",\n  \"set_metadata\": {},\n  \"expand_context\": 0,\n  \"score_threshold\": 0,\n  \"types\": [\n    \"episodic\",\n    \"semantic\"\n  ],\n  \"agent_mode\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:8080/api/v2/memories/search")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"What was the user's last conversation about finance?\",\n  \"org_id\": \"MemVerge\",\n  \"project_id\": \"memmachine\",\n  \"top_k\": 5,\n  \"filter\": \"metadata.user_id=123 AND metadata.session_id=abc\",\n  \"set_metadata\": {},\n  \"expand_context\": 0,\n  \"score_threshold\": 0,\n  \"types\": [\n    \"episodic\",\n    \"semantic\"\n  ],\n  \"agent_mode\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:8080/api/v2/memories/search")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"What was the user's last conversation about finance?\",\n  \"org_id\": \"MemVerge\",\n  \"project_id\": \"memmachine\",\n  \"top_k\": 5,\n  \"filter\": \"metadata.user_id=123 AND metadata.session_id=abc\",\n  \"set_metadata\": {},\n  \"expand_context\": 0,\n  \"score_threshold\": 0,\n  \"types\": [\n    \"episodic\",\n    \"semantic\"\n  ],\n  \"agent_mode\": false\n}"

response = http.request(request)
puts response.read_body

{
  "content": {
    "episodic_memory": {
      "long_term_memory": {
        "episodes": [
          {
            "content": "<string>",
            "producer_id": "<string>",
            "producer_role": "<string>",
            "uid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "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": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "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": [
            "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          ],
          "id": "<string>",
          "other": {}
        }
      }
    ]
  },
  "status": 0
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Memories

Search Memories

Search memories within a project.

System returns the top K relevant memories matching the natural language query. The result is sorted by timestamp to help with context.

The filter field accepts the structured filter expression language. User-defined metadata keys must be referenced with the m. or metadata. prefix (for example, m.source = "chat_v3"). Unknown or unsupported fields are rejected instead of being ignored. The set_metadata field scopes semantic memories to matching semantic sets. The types field allows specifying which memory types to include in the search.

POST

api

memories

Search Memories

curl --request POST \
  --url http://localhost:8080/api/v2/memories/search \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "query": "What was the user's last conversation about finance?",
  "org_id": "MemVerge",
  "project_id": "memmachine",
  "top_k": 5,
  "filter": "metadata.user_id=123 AND metadata.session_id=abc",
  "set_metadata": {},
  "expand_context": 0,
  "score_threshold": 0,
  "types": [
    "episodic",
    "semantic"
  ],
  "agent_mode": false
}
EOF

import requests

url = "http://localhost:8080/api/v2/memories/search"

payload = {
    "query": "What was the user's last conversation about finance?",
    "org_id": "MemVerge",
    "project_id": "memmachine",
    "top_k": 5,
    "filter": "metadata.user_id=123 AND metadata.session_id=abc",
    "set_metadata": {},
    "expand_context": 0,
    "score_threshold": 0,
    "types": ["episodic", "semantic"],
    "agent_mode": False
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: 'What was the user\'s last conversation about finance?',
    org_id: 'MemVerge',
    project_id: 'memmachine',
    top_k: 5,
    filter: 'metadata.user_id=123 AND metadata.session_id=abc',
    set_metadata: {},
    expand_context: 0,
    score_threshold: 0,
    types: ['episodic', 'semantic'],
    agent_mode: false
  })
};

fetch('http://localhost:8080/api/v2/memories/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8080",
  CURLOPT_URL => "http://localhost:8080/api/v2/memories/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'query' => 'What was the user\'s last conversation about finance?',
    'org_id' => 'MemVerge',
    'project_id' => 'memmachine',
    'top_k' => 5,
    'filter' => 'metadata.user_id=123 AND metadata.session_id=abc',
    'set_metadata' => [
        
    ],
    'expand_context' => 0,
    'score_threshold' => 0,
    'types' => [
        'episodic',
        'semantic'
    ],
    'agent_mode' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:8080/api/v2/memories/search"

	payload := strings.NewReader("{\n  \"query\": \"What was the user's last conversation about finance?\",\n  \"org_id\": \"MemVerge\",\n  \"project_id\": \"memmachine\",\n  \"top_k\": 5,\n  \"filter\": \"metadata.user_id=123 AND metadata.session_id=abc\",\n  \"set_metadata\": {},\n  \"expand_context\": 0,\n  \"score_threshold\": 0,\n  \"types\": [\n    \"episodic\",\n    \"semantic\"\n  ],\n  \"agent_mode\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:8080/api/v2/memories/search")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"What was the user's last conversation about finance?\",\n  \"org_id\": \"MemVerge\",\n  \"project_id\": \"memmachine\",\n  \"top_k\": 5,\n  \"filter\": \"metadata.user_id=123 AND metadata.session_id=abc\",\n  \"set_metadata\": {},\n  \"expand_context\": 0,\n  \"score_threshold\": 0,\n  \"types\": [\n    \"episodic\",\n    \"semantic\"\n  ],\n  \"agent_mode\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:8080/api/v2/memories/search")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"What was the user's last conversation about finance?\",\n  \"org_id\": \"MemVerge\",\n  \"project_id\": \"memmachine\",\n  \"top_k\": 5,\n  \"filter\": \"metadata.user_id=123 AND metadata.session_id=abc\",\n  \"set_metadata\": {},\n  \"expand_context\": 0,\n  \"score_threshold\": 0,\n  \"types\": [\n    \"episodic\",\n    \"semantic\"\n  ],\n  \"agent_mode\": false\n}"

response = http.request(request)
puts response.read_body

{
  "content": {
    "episodic_memory": {
      "long_term_memory": {
        "episodes": [
          {
            "content": "<string>",
            "producer_id": "<string>",
            "producer_role": "<string>",
            "uid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "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": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "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": [
            "3c90c3cc-0d44-4b50-8888-8dd25736052a"
          ],
          "id": "<string>",
          "other": {}
        }
      }
    ]
  },
  "status": 0
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

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 | null

Optional metadata key-value pairs used to filter or identify semantic sets.

Show child attributes

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).

Show child attributes

status

integer

default:0

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

Example:

0

Introduction

MCP Tools

REST API

Typescript REST SDK

PythonSDK Client

Python SDK Server

Search Memories

Body

Response