Search

Search is how you pull memories back out at the moment you need them. You send a natural-language query and FishMem returns the most relevant memories, each with a relevance score. This is the read you'll wire into your prompt-building step — see recall for the pattern.

Query and scope

Always pass a query. Almost always pass a scope (user_id, agent_id, or run_id) so you only search one person's or one session's memories rather than everything. Search ranks by semantic similarity, not keyword match, so phrasing the query the way the answer would be stated tends to work best.

curl -X POST https://fishmem.com/v1/memories/search \
  -H "Authorization: Bearer fm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what are the user dietary preferences?",
    "user_id": "alice",
    "top_k": 5
  }'

const client = new MemoryClient({ apiKey, host: "https://fishmem.com" });

const { results } = await client.search("what are the user dietary preferences?", {
  user_id: "alice",
  top_k: 5,
});

top_k

top_k controls how many results come back. It defaults to 10 and accepts values from 1 to 50. If you build a fixed-size context window, set top_k to fit it. The alias limit is accepted if your client uses that name.

Parameters

Response

Each result is a full memory object plus a score:

{
  "results": [
    {
      "id": "mem_124",
      "memory": "Is vegetarian",
      "memory_type": "fact",
      "importance": 0.8,
      "user_id": "alice",
      "agent_id": null,
      "run_id": null,
      "metadata": {},
      "created_at": "2026-06-13T10:00:00Z",
      "updated_at": "2026-06-13T10:00:00Z",
      "event_date": "2026-06-13T10:00:00Z",
      "valid_from": "2026-06-13T10:00:00Z",
      "valid_to": null,
      "score": 0.91
    }
  ]
}

Higher score means a closer match. Results are returned best-first.

Credits

Search costs 1 credit per call, regardless of top_k. (1000 credits ≈ $1.)

See the full contract at /api-reference/search and the ranking model at /open-source/concepts/recall.