# POST /memory/search

**Resource:** [Agent Memory](./memory.md)  
**Scopes:** `memory:read`  
**Write operation:** no

Semantic search over agent memories. Embeds the query and returns the top-K most similar memories by cosine similarity. Use for fuzzy/topic-based lookup ("have I discussed pricing with this contact?"). Use GET /memory for exact key lookup.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `query` | body | string | yes | Natural language query. |
| `subject_type` | body | string | no | Restrict search to a subject type. |
| `subject_id` | body | uuid | no | Restrict to a specific subject. |
| `kind` | body | string | no | Restrict to a memory kind. |
| `agent_registry_id` | body | uuid | no | Restrict to a specific agent. |
| `visibility` | body | string | no | "private" or "shared". |
| `limit` | body | number | no | Max results (default 10, max 50). |
| `threshold` | body | number | no | Cosine similarity floor 0.0-1.0 (default 0.15). Most useful results fall in 0.1-0.4 with Voyage-3 embeddings. |

## Notes

- Returns {results: [...], count: N}. Each result includes all standard memory fields plus a similarity score.
- Embeddings use Voyage-3 (1024 dimensions). Voyage-3 cosine scores are lower-magnitude than OpenAI -- raise threshold to 0.3+ for stricter matching.
- Returns an error (not empty results) if the embedding service is unavailable.

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`