Search documents

client.search.execute(, ?): SearchExecuteResponse { results, timing, total }

POST/v3/search

Search memories with advanced filtering

ParametersExpand Collapse

body: SearchExecuteParams { q, categoriesFilter, chunkThreshold, 12 more }

q: string

Search query string

minLength1

DeprecatedcategoriesFilter?: Array<string>

DEPRECATED: Optional category filters

chunkThreshold?: number

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

maximum1

minimum0

containerTag?: string

Optional single container tag. Use this or containerTags.

maxLength100

containerTags?: Array<string>

Optional tags 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 documents.

docId?: string

Optional document ID to search within. You can use this to find chunks in a very large document.

maxLength255

DeprecateddocumentThreshold?: number

DEPRECATED: This field is no longer used in v3 search. The search now uses chunkThreshold only. This parameter will be ignored.

maximum1

minimum0

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

includeFullDocs?: boolean

If true, include full document in the response. This is helpful if you want a chatbot to know the full context of the document.

includeSummary?: boolean

If true, include document summary in the response. This is helpful if you want a chatbot to know the full context of the document.

limit?: number

Maximum number of results to return

maximum100

minimum1

exclusiveMinimum0

onlyMatchingChunks?: boolean

If true, only return matching chunks without context. Normally, we send the previous and next chunk to provide more context for LLMs. If you only want the matching chunk, set this to true.

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

ReturnsExpand Collapse

SearchExecuteResponse { results, timing, total }

results: Array<Result>

chunks: Array<Chunk>

Matching content chunks from the document

content: string

Content of the matching chunk

isRelevant: boolean

Whether this chunk is relevant to the query

position: number

Position of this chunk within the source document (0-indexed). Use it to order chunks and to locate surrounding context chunks (isRelevant=false) relative to the matching ones.

score: number

Similarity score for this chunk

maximum1

minimum0

createdAt: string

Document creation date

formatdatetime

documentId: string

ID of the matching document

metadata: Record<string, unknown> | null

Document metadata

score: number

Relevance score of the match

maximum1

minimum0

title: string | null

Document title

type: string | null

Document type

updatedAt: string

Document last update date

formatdatetime

content?: string | null

Full document content (only included when includeFullDocs=true)

summary?: string | null

Document summary

timing: number

total: number

Search documents

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.execute({ q: 'what are the API rate limits' });

console.log(response.results);

{
  "results": [
    {
      "chunks": [
        {
          "content": "Rate limit headers are included in every response. Clients should implement exponential backoff when receiving 429 responses.",
          "isRelevant": true,
          "position": 3,
          "score": 0.85
        }
      ],
      "createdAt": "1970-01-01T00:00:00.000Z",
      "documentId": "doc_xyz789",
      "metadata": {
        "source": "bar",
        "language": "bar"
      },
      "score": 0.95,
      "title": "API Rate Limiting Policy",
      "type": "web",
      "updatedAt": "1970-01-01T00:00:00.000Z",
      "content": "Our API rate limits are 100 req/min on free and 1000 on pro. Clients should use exponential backoff on 429s.",
      "summary": "API rate limit policy: 100 req/min free, 1000 req/min pro."
    }
  ],
  "timing": 0,
  "total": 0
}

Returns Examples

{
  "results": [
    {
      "chunks": [
        {
          "content": "Rate limit headers are included in every response. Clients should implement exponential backoff when receiving 429 responses.",
          "isRelevant": true,
          "position": 3,
          "score": 0.85
        }
      ],
      "createdAt": "1970-01-01T00:00:00.000Z",
      "documentId": "doc_xyz789",
      "metadata": {
        "source": "bar",
        "language": "bar"
      },
      "score": 0.95,
      "title": "API Rate Limiting Policy",
      "type": "web",
      "updatedAt": "1970-01-01T00:00:00.000Z",
      "content": "Our API rate limits are 100 req/min on free and 1000 on pro. Clients should use exponential backoff on 429s.",
      "summary": "API rate limit policy: 100 req/min free, 1000 req/min pro."
    }
  ],
  "timing": 0,
  "total": 0
}