memory.retrieve

Retrieve the most relevant memories for a query. Combines cosine similarity with temporal recency, importance, and access frequency to return a ranked list.

POST /v1/memory/retrieve

Request

curl -X POST https://api.mnemexa.com/v1/memory/retrieve \
  -H "Authorization: Bearer mnx_ws_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "communication preferences for standups",
    "top_k": 5,
    "min_score": 0.35
  }'

Body

Field	Type	Required	Default	Description
`query`	string	yes	—	Natural-language search query. 1–1,000 characters.
`top_k`	integer	no	`5`	Number of memories to return. Range `1–50`.
`min_score`	number	no	`0.35`	Minimum cosine similarity threshold (0.0–1.0). Memories below this are filtered before hybrid re-ranking.

Response

{
  "memories": [
    {
      "id": 8421,
      "text": "Client prefers async standups on Tuesdays at 9am IST…",
      "score": 0.812,
      "similarity": 0.694,
      "importance": 5,
      "meta": {
        "source": "kickoff_meeting",
        "temporal": {
          "type": "persistent",
          "valid_until": null
        }
      }
    }
  ]
}

Fields

Field	Type	Description
`id`	integer	Memory ID.
`text`	string	The stored content.
`score`	number	Hybrid score (0.0–1.0). The ranking value. Combines `similarity` with recency, importance, and frequency — not raw cosine distance.
`similarity`	number	Raw cosine similarity (0.0–1.0). The semantic-match component of the hybrid score.
`importance`	integer	LLM-assigned importance from when the memory was stored.
`meta`	object	Free-form metadata supplied at store time, plus the temporal classification.

score and similarity are different by design. similarity is what cosine distance would give you. score is what Mnemexa actually ranked by — a fresher, more important, more-accessed memory will rank above a cosine-closer-but-stale one.

See Hybrid Scoring for the four-factor breakdown.

Side effects

Returned memories have their access counters updated — frequent retrieval boosts a memory’s score on future queries. There’s no client-visible field for this; it’s pure background bookkeeping.

Errors

Status	Cause
401	Missing or invalid `Authorization` header.
403	Workspace deleted or client account suspended.
422	`query` empty or too long, `top_k` out of range, `min_score` outside `[0,1]`.
429	Rate limit exceeded, or plan unit limit reached.

SDKs

import mnemexa

client = mnemexa.Client()
result = client.memory.retrieve(
    query="communication preferences for standups",
    top_k=5,
)
for m in result.memories:
    print(f"[{m.score:.3f}] {m.text}")

The MCP adapter exposes this as brain.recall. See Python SDK and MCP Adapter.

← Previous memory.store Next optimize.health →