# Recall facts by meaning

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

`POST https://api.zavu.dev/v1/memory/search`

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?".

## Body

- `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` (string): 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. One of: `project`, `contact`, `conversation`.
- `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".

## Responses

### 200

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

- `items` (object[], required)
  - `id` (string, required)
  - `text` (string): The remembered text.
  - `metadata` (object)
    - `{key}` (string)
  - `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>)

### 400

Invalid body or a scope without its id.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 401

Unauthorized.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

## Example

```bash
curl -X POST "https://api.zavu.dev/v1/memory/search" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "how do they prefer to be contacted",
  "scope": "contact",
  "contactId": "jd7x2k3m4n5p6q7r8s9t0abc",
  "limit": 5,
  "minScore": 0.3
}'
```

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY });

const result = await zavu.memory.search({
  query: "how do they prefer to be contacted",
  scope: "contact",
  contactId: "jd7x2k3m4n5p6q7r8s9t0abc",
  limit: 5,
  minScore: 0.3,
});

console.log(result);
```