---
title: "Recall facts by meaning"
method: POST
path: "/v1/memory/search"
tags: ["Memory"]
---

# Recall facts by meaning

`POST /v1/memory/search`

## Request

- Base URL: `https://api.zavu.dev`
- URL: `https://api.zavu.dev/v1/memory/search`
- Auth: HTTP bearer

Embed the query and return the closest facts in the scope, ranked by cosine similarity.

**Scope goes in the body**, like `POST /v1/memory`: `scope` plus the matching id.

Without `minScore`, a scope always answers with its `limit` closest facts however distant they are — a search that found nothing relevant is indistinguishable from one that found the right thing. Set `minScore` when your code branches on "did I know this?".

## Request body

- MemorySearchRequest: Retrieve facts by meaning. The query is embedded and compared against every fact in the scope.
  - `query` string, required: What to recall. Max 8,192 bytes. Phrase it as the fact you hope to find, not as a keyword: the match is semantic.
  - `scope` 'project' | 'contact' | 'conversation': Which namespace a memory belongs to. Scopes are isolated: a search in one never returns a memory from another. - `project`: shared by the whole project. What the agent knows in general. - `contact`: what the agent knows about one person, across every conversation with them. - `conversation`: what the agent knows about one inbox thread. Defaults to `project` everywhere. `contact` and `conversation` require the matching id.
  - `contactId` string: Required when `scope` is `contact`.
  - `conversationId` string: Required when `scope` is `conversation`.
  - `limit` integer: Maximum hits to return, closest first.
  - `minScore` number: Drop hits below this similarity. Without it every scope returns its `limit` closest facts, however far away they are — an empty-handed search still answers with something. Set it (0.3 or above is a reasonable floor) when "nothing relevant" must be distinguishable from "the least irrelevant thing I hold".

## Response `200`

Matching facts, closest first. An empty `items` means nothing cleared `minScore`.

- object
  - `items` Memory[], required
    - `id` string, required
    - `text` string: The remembered text.
    - `metadata` object
    - `score` number: Cosine similarity to the query, 0 to 1, higher being closer. Present on search results only — a list or a single read has no query to score against.
    - `createdAt` string, date-time, required
    - `expiresAt` string, date-time

## Other responses

- `400`: Invalid body or a scope without its id.
- `401`: Unauthorized.

## Changes

> 80 revisions in range; 1 not diffed.

- **2026-08-26** `6e8c555e1104`: 1 info
  - removed the non-success response with the status `403`
- **2026-08-26** `83caf7165722`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/changes/v1/memory/search/post.md)

---

[API](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api.md) - [All operations](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zavudev/apis/zavu-unified-messaging-layer-api/revisions/75bc777b0ffb?raw)