Search memories

`POST /v1/memories/search`

Returns the most relevant memories for a query, ranked by score. Scope the search with user_id, agent_id, and/or run_id.

Parameters

Field	Type	Required	Description
`query`	string	yes	Search query
`user_id`	string	no	User scope
`agent_id`	string	no	Agent scope
`run_id`	string	no	Run scope
`top_k`	number	no	Max results (default `10`, range `1`–`50`; alias `limit`)

Request

curl https://fishmem.com/v1/memories/search \
  -H "Authorization: Bearer fm_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "what does alex like?", "user_id": "alex", "top_k": 5}'

Response

{
  "results": [
    {
      "id": "mem_…",
      "memory": "Prefers dark mode",
      "memory_type": "fact",
      "importance": 0.7,
      "user_id": "alex",
      "agent_id": null,
      "run_id": null,
      "metadata": null,
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "event_date": null,
      "valid_from": null,
      "valid_to": null,
      "score": 0.83
    }
  ]
}

Credits

1 credit per search.

Errors

Returns the standard error shape. A missing or invalid key returns 401 with "error": "INVALID_API_KEY".