---
title: "Search memories (V3)"
method: POST
path: "/v3/memories/search/"
tags: ["memories"]
---

# Search memories (V3)

`POST /v3/memories/search/`

Relevance-ranked search across stored memories. V3 uses hybrid retrieval and can also apply temporal reasoning for time-aware queries. Entity IDs **must** be passed inside the `filters` object. Top-level `user_id` / `agent_id` / `run_id` are rejected with 400. At least one entity ID is required.

## Request body

- object
  - `query` string, required — Natural-language search query.
  - `filters` object, required — Entity and metadata filters. Must include at least one entity ID (`user_id`, `agent_id`, `app_id`, or `run_id`). Supports `AND`, `OR`, `NOT`, and comparison operators (`in`, `gte`, `lte`, `gt`, `lt`, `contains`, `icontains`, `ne`).
  - `show_expired` boolean — When true, include memories whose `expiration_date` has passed. Expired memories are hidden by default.
  - `top_k` integer — Number of results to return.
  - `threshold` number — Minimum semantic relevance score. Pass `0.0` to disable filtering.
  - `rerank` boolean — Apply the managed reranker for better ordering (adds latency).
  - `reference_date` union — Date and time to simulate the search from. Accepts a Unix epoch, YYYY-MM-DD, or ISO datetime.
    - integer
    - number
    - string
  - `fields` string[] — Restrict the fields returned per memory.
  - `categories` string[] — Filter results to memories tagged with any of these categories.
  - `metadata` object — Filter results to memories matching this metadata.

## Response `200`

Ranked search results.

- object
  - `results` object[], required
    - `id` string, uuid, required — Unique memory identifier.
    - `memory` string, required — The extracted memory fact.
    - `user_id` string, nullable — User the memory is scoped to.
    - `score` number, float — Combined multi-signal relevance score in [0, 1] (search responses only).
    - `score_breakdown` object — Per-signal breakdown of the relevance score.
      - `semantic` number
      - `bm25` number
      - `entity` number
    - `agent_id` string, nullable
    - `app_id` string, nullable
    - `run_id` string, nullable — Run/session the memory is scoped to. Note: this endpoint returns this field as `run_id`, while `POST /v3/memories/` returns the same value as `session_id`.
    - `expiration_date` string, date, nullable — Date after which the memory is hidden from search unless `show_expired` is true.
    - `metadata` object, nullable — User-supplied metadata attached to the memory.
    - `categories` string[]
    - `created_at` string, date-time, required
    - `updated_at` string, date-time

## Other responses

- `400` — Validation error, e.g. empty `query`, missing `filters`, or no positively-scoped entity ID.
- `401` — Unauthorized: missing or invalid API key.

---

[API](https://skmtc.net/mem0/apis/mem0-api-docs.md) · [All operations](https://skmtc.net/mem0/apis/mem0-api-docs/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mem0/mem0-api-docs/revisions/c86fe9831e7e/schema)