5.4.1 Inputs ¶

query

Required string. The natural-language question or topic to search for.

limit

Integer. Optional, default DEFAULT_RECALL_LIMIT (8), capped at MAX_RECALL_LIMIT (50).

min_score

Number, 0–1. Optional. Filter out matches below this score.

tags

Array of strings. Optional. Filter to memories with at least one matching tag.

5.4.2 Output ¶

{
  "ok": true,
  "matches": [
    {
      "id": 123,
      "text": "The user's son Colby lives in Los Angeles.",
      "score": 0.8421,
      "created_at": "2026-05-05T12:00:00Z",
      "updated_at": "2026-05-05T12:00:00Z",
      "last_confirmed_at": "2026-05-05T12:00:00Z",
      "tags": ["family"],
      "source_provider": "openai",
      "capture_mode": "explicit"
    },
    ...
  ]
}

The tool description instructs the calling LLM to prefer the most recently confirmed match when multiple results look contradictory: compare last_confirmed_at first, then updated_at, then created_at.

Each match also carries the learned salience (a double) and use_count (and context_count when it has learned context). Results are ordered by a blend of cosine similarity, salience, and learned per-query context — cosine * (1 + w*salience + w*context_match) — with recency as a tiebreaker. Crucially the reported score stays the raw cosine similarity, so min_score and the contradiction heuristic above keep their original meaning; the learning affects order, not the reported score. See The reinforce tool for how salience and context are taught, and Background intelligence for the bigger picture.

5.4.3 Errors ¶

INVALID_INPUT, EMBEDDING_ERROR, DATABASE_ERROR.

5.4.4 Example ¶

{
  "name": "recall",
  "arguments": {
    "query": "where does my son live",
    "limit": 5,
    "tags": ["family"]
  }
}