---
title: "Search memory entries"
method: POST
path: "/v4/search"
tags: ["Recall (Search)"]
---

# Search memory entries

`POST /v4/search`

Search memory entries - Low latency for conversational

## Request body

- object
  - `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.
  - `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)
  - `filters` union — Optional filters to apply to the search. Can be a JSON string or Query object.
    - object
      - `OR` union[], required — Array of OR filter expressions
        - union — A logical filter expression that can combine conditions using AND/OR operations. Supports up to 5 levels of nesting.
          - object — A single filter condition based on metadata, numeric values, array contents, or string matching
            - `filterType` 'metadata' | 'numeric' | 'array_contains' | 'string_contains'
            - `key` string, required
            - `negate` union
              - …
            - `ignoreCase` union
              - …
            - `numericOperator` '>' | '<' | '>=' | '<=' | '='
            - `value` string, required
          - object
            - `OR` union[], required — OR: Array of conditions or nested expressions
              - …
          - object
            - `AND` union[], required — AND: Array of conditions or nested expressions
              - …
    - object
      - `AND` union[], required — Array of AND filter expressions
        - union — A logical filter expression that can combine conditions using AND/OR operations. Supports up to 5 levels of nesting.
          - object — A single filter condition based on metadata, numeric values, array contents, or string matching
            - `filterType` 'metadata' | 'numeric' | 'array_contains' | 'string_contains'
            - `key` string, required
            - `negate` union
              - …
            - `ignoreCase` union
              - …
            - `numericOperator` '>' | '<' | '>=' | '<=' | '='
            - `value` string, required
          - object
            - `OR` union[], required — OR: Array of conditions or nested expressions
              - …
          - object
            - `AND` union[], required — AND: Array of conditions or nested expressions
              - …
  - `include` object
    - `documents` boolean
    - `summaries` boolean
    - `relatedMemories` 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.
    - `chunks` boolean — DEPRECATED: Use searchMode='hybrid' instead. If true, automatically switches to hybrid mode. This field is kept for backward compatibility only.
  - `limit` integer — Maximum number of results to return
  - `q` string, required — Search query string
  - `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.
  - `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.
  - `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.
  - `filepath` string — Filter search results by filepath. Exact match for full paths, prefix match if ending with /

## Response `200`

Memory search results

- object
  - `results` object[], required — 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, required — Memory entry ID or chunk ID
    - `memory` string — The memory content (only present for memory results)
    - `chunk` string — The chunk content (only present for chunk results from hybrid search)
    - `metadata` object, nullable, required — Memory metadata
    - `updatedAt` string, datetime, required — Memory last update date
    - `similarity` number, required — Similarity score between the query and memory entry
    - `filepath` string, nullable — Filepath of the source document this memory or chunk came from
    - `version` number, nullable — Version number of this memory entry
    - `context` object — Object containing version history (parents/children via updates) and related memories (extends/derives)
      - `parents` object[]
        - `relation` 'updates' | 'extends' | 'derives', required — Relation type between this memory and its parent/child
        - `version` number, nullable — Relative version distance from the primary memory (-1 for direct parent, -2 for grand-parent, etc.)
        - `memory` string, required — The contextual memory content
        - `metadata` object, nullable — Contextual memory metadata
        - `updatedAt` string, datetime, required — Contextual memory last update date
      - `children` object[]
        - `relation` 'updates' | 'extends' | 'derives', required — Relation type between this memory and its parent/child
        - `version` number, nullable — Relative version distance from the primary memory (+1 for direct child, +2 for grand-child, etc.)
        - `memory` string, required — The contextual memory content
        - `metadata` object, nullable — Contextual memory metadata
        - `updatedAt` string, datetime, required — Contextual memory last update date
      - `related` object[]
        - `relation` 'extends' | 'derives', required — Relation type
        - `memory` string, required — The related memory content
        - `metadata` object, nullable — Related memory metadata
        - `updatedAt` string, required — Related memory last update date
    - `documents` object[] — Associated documents for this memory entry
      - `id` string, required — Document ID
      - `title` string — Document title (only included when documents=true)
      - `type` string — Document type (only included when documents=true)
      - `metadata` object, nullable — Document metadata (only included when documents=true)
      - `summary` string, nullable — Document summary (only included when summaries=true)
      - `createdAt` string, datetime, required — Document creation date
      - `updatedAt` string, datetime, required — Document last update date
    - `chunks` object[] — Relevant chunks from associated documents (only included when chunks=true)
      - `content` string, required — Content of the chunk
      - `score` number, required — Similarity score between the query and chunk
      - `position` number, required — Position of chunk in the document (0-indexed)
      - `documentId` string, required — ID of the document this chunk belongs to
    - `isAggregated` boolean — Indicates if this memory was created by aggregating multiple source memories
  - `timing` number, required — Search execution time in milliseconds
  - `total` number, required — Total number of results returned

## Other responses

- `400` — Invalid request parameters
- `401` — Unauthorized
- `402` — Search query limit reached
- `500` — Server error

## Changes

- **2026-04-25** `f979eba02e97` — 1 info
  - added the optional property `results/items/context/related` to the response with the `200` status
- **2026-04-17** `f09b91ede978` — 2 info
  - added the new optional request property `filepath`
  - added the optional property `results/items/filepath` to the response with the `200` status
- **2026-04-07** `b5edd97adf4a` — 2 info
  - api tag `Recall (Search)` added
  - api tag `Memories` removed
- **2026-04-06** `cb825424a780` — 2 info
  - api tag `Memories` added
  - api tag `Search` removed
- **2026-04-06** `008c99427a24` — 2 info
  - added the new optional request property `aggregate`
  - added the optional property `results/items/isAggregated` to the response with the `200` status

[Full history](https://skmtc.dev/supermemoryai/apis/supermemory-api/changes/v4/search/post.md)

---

[API](https://skmtc.dev/supermemoryai/apis/supermemory-api.md) · [All operations](https://skmtc.dev/supermemoryai/apis/supermemory-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/supermemoryai/supermemory-api/revisions/f979eba02e97/schema)