API Reference

Search

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Search memory entries

client.search.memories(SearchMemoriesParams { q, aggregate, containerTag, 9 more } body, RequestOptionsoptions?): SearchMemoriesResponse { results, timing, total }

POST/v4/search

Search memory entries - Low latency for conversational

ParametersExpand Collapse

body: SearchMemoriesParams { q, aggregate, containerTag, 9 more }

q: string

Search query string

minLength1

aggregate?: boolean

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.

containerTag?: string

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

containerTags?: Array<string>

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

filepath?: string

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

filters?: Or { OR } | And { AND }

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

One of the following:

Or { OR }

OR: Array<FilterCondition { key, value, filterType, 3 more } | Or { OR } | And { AND } >

Array of OR filter expressions

One of the following:

FilterCondition { key, value, filterType, 3 more }

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

key: string

value: string

filterType?: "metadata" | "numeric" | "array_contains" | "string_contains"

One of the following:

"metadata"

"numeric"

"array_contains"

"string_contains"

ignoreCase?: boolean | "true" | "false"

One of the following:

boolean

"true" | "false"

"true"

"false"

negate?: boolean | "true" | "false"

One of the following:

boolean

"true" | "false"

"true"

"false"

numericOperator?: ">" | "<" | ">=" | 2 more

One of the following:

">"

"<"

">="

"<="

"="

Or { OR }

OR: Array<unknown>

OR: Array of conditions or nested expressions

And { AND }

AND: Array<unknown>

AND: Array of conditions or nested expressions

And { AND }

AND: Array<FilterCondition { key, value, filterType, 3 more } | Or { OR } | And { AND } >

Array of AND filter expressions

One of the following:

FilterCondition { key, value, filterType, 3 more }

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

key: string

value: string

filterType?: "metadata" | "numeric" | "array_contains" | "string_contains"

One of the following:

"metadata"

"numeric"

"array_contains"

"string_contains"

ignoreCase?: boolean | "true" | "false"

One of the following:

boolean

"true" | "false"

"true"

"false"

negate?: boolean | "true" | "false"

One of the following:

boolean

"true" | "false"

"true"

"false"

numericOperator?: ">" | "<" | ">=" | 2 more

One of the following:

">"

"<"

">="

"<="

"="

Or { OR }

OR: Array<unknown>

OR: Array of conditions or nested expressions

And { AND }

AND: Array<unknown>

AND: Array of conditions or nested expressions

include?: Include

Deprecatedchunks?: boolean

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

documents?: boolean

forgottenMemories?: boolean

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

relatedMemories?: boolean

summaries?: boolean

limit?: number

Maximum number of results to return

maximum100

minimum1

exclusiveMinimum0

rerank?: boolean

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

rewriteQuery?: boolean

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

searchMode?: "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?: number

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

SearchMemoriesResponse { results, timing, total }

results: Array<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: string

Memory entry ID or chunk ID

metadata: Record<string, unknown> | null

Memory metadata

similarity: number

Similarity score between the query and memory entry

maximum1

minimum0

updatedAt: string

Memory last update date

formatdatetime

chunk?: string

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

chunks?: Array<Chunk>

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

content: string

Content of the chunk

documentId: string

ID of the document this chunk belongs to

position: number

Position of chunk in the document (0-indexed)

context?: Context { children, parents, related }

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

children?: Array<Child>

memory: string

The contextual memory content

relation: "updates" | "extends" | "derives"

Relation type between this memory and its parent/child

One of the following:

"updates"

"extends"

"derives"

updatedAt: string

Contextual memory last update date

formatdatetime

metadata?: Record<string, unknown> | null

Contextual memory metadata

version?: number | null

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

parents?: Array<Parent>

memory: string

The contextual memory content

relation: "updates" | "extends" | "derives"

Relation type between this memory and its parent/child

One of the following:

"updates"

"extends"

"derives"

updatedAt: string

Contextual memory last update date

formatdatetime

metadata?: Record<string, unknown> | null

Contextual memory metadata

version?: number | null

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

related?: Array<Related>

memory: string

The related memory content

relation: "extends" | "derives"

Relation type

One of the following:

"extends"

"derives"

updatedAt: string

Related memory last update date

metadata?: Record<string, unknown> | null

Related memory metadata

documents?: Array<Document>

Associated documents for this memory entry

id: string

Document ID

createdAt: string

Document creation date

formatdatetime

updatedAt: string

Document last update date

formatdatetime

metadata?: Record<string, unknown> | null

Document metadata (only included when documents=true)

summary?: string | null

Document summary (only included when summaries=true)

title?: string

Document title (only included when documents=true)

type?: string

Document type (only included when documents=true)

filepath?: string | null

Filepath of the source document this memory or chunk came from

isAggregated?: boolean

Indicates if this memory was created by aggregating multiple source memories

memory?: string

The memory content (only present for memory results)

rootMemoryId?: string | null

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?: number | null

Version number of this memory entry

timing: number

Search execution time in milliseconds

total: number

Total number of results returned

Search memory entries

TypeScript

HTTP

TypeScript

Python

import Supermemory from 'supermemory';

const client = new Supermemory({
  apiKey: process.env['SUPERMEMORY_API_KEY'], // This is the default and can be omitted
});

const response = await client.search.memories({ q: 'what are the API rate limits' });

console.log(response.results);

200 example

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

200 example

{
  "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
}