Search memory entries

search.memories() -> SearchMemoriesResponse

POST/v4/search

Search memory entries - Low latency for conversational

ParametersExpand Collapse

q: str

Search query string

minLength1

aggregate: Optional[bool]

If true, aggregates information from multiple memories to create new synthesized memories. The result will be a mix of aggregated and non-aggregated memories, reranked by relevance to the query. Works in conjunction with reranking.

container_tag: Optional[str]

Optional tag this search should be containerized by. This can be an ID for your user, a project ID, or any other identifier you wish to use to filter memories.

maxLength100

container_tags: Optional[Sequence[str]]

Optional tags this search should be containerized by. Search is scoped to memories under these tags.

filepath: Optional[str]

Filter search results by filepath. Exact match for full paths, prefix match if ending with /

filters: Optional[Filters]

Optional filters to apply to the search. Can be a JSON string or Query object.

One of the following:

class FiltersOr: …

or_: Iterable[FiltersOrOr]

Array of OR filter expressions

One of the following:

class FiltersOrOrFilterCondition: …

A single filter condition based on metadata, numeric values, array contents, or string matching

key: str

value: str

filter_type: Optional[Literal["metadata", "numeric", "array_contains", "string_contains"]]

One of the following:

"metadata"

"numeric"

"array_contains"

"string_contains"

ignore_case: Optional[Union[bool, Literal["true", "false"]]]

One of the following:

bool

Literal["true", "false"]

One of the following:

"true"

"false"

negate: Optional[Union[bool, Literal["true", "false"]]]

One of the following:

bool

Literal["true", "false"]

One of the following:

"true"

"false"

numeric_operator: Optional[Literal[">", "<", ">=", 2 more]]

One of the following:

">"

"<"

">="

"<="

"="

class FiltersOrOrOr: …

or_: Iterable[object]

OR: Array of conditions or nested expressions

class FiltersOrOrAnd: …

and_: Iterable[object]

AND: Array of conditions or nested expressions

class FiltersAnd: …

and_: Iterable[FiltersAndAnd]

Array of AND filter expressions

One of the following:

class FiltersAndAndFilterCondition: …

A single filter condition based on metadata, numeric values, array contents, or string matching

key: str

value: str

filter_type: Optional[Literal["metadata", "numeric", "array_contains", "string_contains"]]

One of the following:

"metadata"

"numeric"

"array_contains"

"string_contains"

ignore_case: Optional[Union[bool, Literal["true", "false"]]]

One of the following:

bool

Literal["true", "false"]

One of the following:

"true"

"false"

negate: Optional[Union[bool, Literal["true", "false"]]]

One of the following:

bool

Literal["true", "false"]

One of the following:

"true"

"false"

numeric_operator: Optional[Literal[">", "<", ">=", 2 more]]

One of the following:

">"

"<"

">="

"<="

"="

class FiltersAndAndOr: …

or_: Iterable[object]

OR: Array of conditions or nested expressions

class FiltersAndAndAnd: …

and_: Iterable[object]

AND: Array of conditions or nested expressions

include: Optional[Include]

Deprecatedchunks: Optional[bool]

DEPRECATED: Use searchMode=‘hybrid’ instead. If true, automatically switches to hybrid mode. This field is kept for backward compatibility only.

documents: Optional[bool]

forgotten_memories: Optional[bool]

If true, include forgotten memories in search results. Forgotten memories are memories that have been explicitly forgotten or have passed their expiration date.

related_memories: Optional[bool]

summaries: Optional[bool]

limit: Optional[int]

Maximum number of results to return

maximum100

minimum1

exclusiveMinimum0

rerank: Optional[bool]

If true, rerank the results based on the query. This is helpful if you want to ensure the most relevant results are returned.

rewrite_query: Optional[bool]

If true, rewrites the query to make it easier to find documents. This increases the latency by about 400ms

search_mode: Optional[Literal["memories", "hybrid", "documents"]]

Search mode. ‘memories’ searches only memory entries (default). ‘hybrid’ searches both memories and document chunks. ‘documents’ searches only document chunks.

One of the following:

"memories"

"hybrid"

"documents"

threshold: Optional[float]

Threshold / sensitivity for memories selection. 0 is least sensitive (returns most memories, more results), 1 is most sensitive (returns lesser memories, accurate results)

maximum1

minimum0

ReturnsExpand Collapse

class SearchMemoriesResponse: …

results: List[Result]

Array of matching memory entries and chunks with similarity scores. Contains memory results when searchMode=‘memories’, both memory and chunk results when searchMode=‘hybrid’, or only chunk results when searchMode=‘documents’. Memory results have ‘memory’ field, chunk results have ‘chunk’ field. BACKWARD COMPATIBILITY: When using deprecated include.chunks=true, only memory results are returned with chunks embedded in them (old format).

id: str

Memory entry ID or chunk ID

metadata: Optional[Dict[str, object]]

Memory metadata

similarity: float

Similarity score between the query and memory entry

maximum1

minimum0

updated_at: str

Memory last update date

formatdatetime

chunk: Optional[str]

The chunk content (only present for chunk results from hybrid search)

chunks: Optional[List[ResultChunk]]

Relevant chunks from associated documents (only included when chunks=true)

content: str

Content of the chunk

document_id: str

ID of the document this chunk belongs to

position: float

Position of chunk in the document (0-indexed)

context: Optional[ResultContext]

Object containing version history (parents/children via updates) and related memories (extends/derives)

children: Optional[List[ResultContextChild]]

memory: str

The contextual memory content

relation: Literal["updates", "extends", "derives"]

Relation type between this memory and its parent/child

One of the following:

"updates"

"extends"

"derives"

updated_at: str

Contextual memory last update date

formatdatetime

metadata: Optional[Dict[str, object]]

Contextual memory metadata

version: Optional[float]

Relative version distance from the primary memory (+1 for direct child, +2 for grand-child, etc.)

parents: Optional[List[ResultContextParent]]

memory: str

The contextual memory content

relation: Literal["updates", "extends", "derives"]

Relation type between this memory and its parent/child

One of the following:

"updates"

"extends"

"derives"

updated_at: str

Contextual memory last update date

formatdatetime

metadata: Optional[Dict[str, object]]

Contextual memory metadata

version: Optional[float]

Relative version distance from the primary memory (-1 for direct parent, -2 for grand-parent, etc.)

One of the following:

documents: Optional[List[ResultDocument]]

Associated documents for this memory entry

id: str

Document ID

created_at: str

Document creation date

formatdatetime

updated_at: str

Document last update date

formatdatetime

metadata: Optional[Dict[str, object]]

Document metadata (only included when documents=true)

summary: Optional[str]

Document summary (only included when summaries=true)

title: Optional[str]

Document title (only included when documents=true)

type: Optional[str]

Document type (only included when documents=true)

filepath: Optional[str]

Filepath of the source document this memory or chunk came from

is_aggregated: Optional[bool]

Indicates if this memory was created by aggregating multiple source memories

memory: Optional[str]

The memory content (only present for memory results)

root_memory_id: Optional[str]

ID of the root (first version) memory entry this one descends from. Null for memories that have never been superseded. Only present on memory results, not on standalone chunk results.

version: Optional[float]

Version number of this memory entry

timing: float

Search execution time in milliseconds

total: float

Total number of results returned

Search memory entries

import os
from supermemory import Supermemory

client = Supermemory(
    api_key=os.environ.get("SUPERMEMORY_API_KEY"),  # This is the default and can be omitted
)
response = client.search.memories(
    q="what are the API rate limits",
)
print(response.results)

{
  "results": [
    {
      "id": "mem_abc123",
      "metadata": {
        "source": "bar",
        "confidence": "bar"
      },
      "similarity": 0.89,
      "updatedAt": "updatedAt",
      "chunk": "This is a chunk of content from a document...",
      "chunks": [
        {
          "content": "This is a chunk of content from the document...",
          "documentId": "doc_xyz789",
          "position": 0
        }
      ],
      "context": {
        "children": [
          {
            "memory": "Later version: API rate limit increased to 100 req/min on the free tier.",
            "relation": "extends",
            "updatedAt": "updatedAt",
            "metadata": {
              "foo": "bar"
            },
            "version": 1
          }
        ],
        "parents": [
          {
            "memory": "Earlier version: API rate limit is 50 req/min on the free tier.",
            "relation": "updates",
            "updatedAt": "updatedAt",
            "metadata": {
              "foo": "bar"
            },
            "version": -1
          }
        ],
        "related": [
          {
            "memory": "memory",
            "relation": "extends",
            "updatedAt": "updatedAt",
            "metadata": {
              "foo": "bar"
            }
          }
        ]
      },
      "documents": [
        {
          "id": "doc_xyz789",
          "createdAt": "createdAt",
          "updatedAt": "updatedAt",
          "metadata": {
            "source": "bar",
            "language": "bar"
          },
          "summary": "API rate limit policy: 100 req/min free, 1000 req/min pro.",
          "title": "API Rate Limiting Policy",
          "type": "web"
        }
      ],
      "filepath": "filepath",
      "isAggregated": false,
      "memory": "The user prefers detailed API responses over minimal ones.",
      "rootMemoryId": "mem_abc123",
      "version": 3
    }
  ],
  "timing": 245,
  "total": 5
}

Returns Examples

{
  "results": [
    {
      "id": "mem_abc123",
      "metadata": {
        "source": "bar",
        "confidence": "bar"
      },
      "similarity": 0.89,
      "updatedAt": "updatedAt",
      "chunk": "This is a chunk of content from a document...",
      "chunks": [
        {
          "content": "This is a chunk of content from the document...",
          "documentId": "doc_xyz789",
          "position": 0
        }
      ],
      "context": {
        "children": [
          {
            "memory": "Later version: API rate limit increased to 100 req/min on the free tier.",
            "relation": "extends",
            "updatedAt": "updatedAt",
            "metadata": {
              "foo": "bar"
            },
            "version": 1
          }
        ],
        "parents": [
          {
            "memory": "Earlier version: API rate limit is 50 req/min on the free tier.",
            "relation": "updates",
            "updatedAt": "updatedAt",
            "metadata": {
              "foo": "bar"
            },
            "version": -1
          }
        ],
        "related": [
          {
            "memory": "memory",
            "relation": "extends",
            "updatedAt": "updatedAt",
            "metadata": {
              "foo": "bar"
            }
          }
        ]
      },
      "documents": [
        {
          "id": "doc_xyz789",
          "createdAt": "createdAt",
          "updatedAt": "updatedAt",
          "metadata": {
            "source": "bar",
            "language": "bar"
          },
          "summary": "API rate limit policy: 100 req/min free, 1000 req/min pro.",
          "title": "API Rate Limiting Policy",
          "type": "web"
        }
      ],
      "filepath": "filepath",
      "isAggregated": false,
      "memory": "The user prefers detailed API responses over minimal ones.",
      "rootMemoryId": "mem_abc123",
      "version": 3
    }
  ],
  "timing": 245,
  "total": 5
}