Documentation menu

Recall and the confidence gate

How Retrack finds the right playbook for a task: hybrid search, a confidence gate that blocks wrong memory, warnings, plan replay and fail-open timeouts.

Updated

Wrong memory is worse than no memory. A playbook from a different kind of task can push an agent down the wrong path, so Retrack only injects a playbook when it clearly applies.

Calling recall

memory = retrack.recall(task)                  # before the task
prompt = memory.as_prompt()                    # "" when there is nothing to add

Options: max_playbooks (default 3, up to 10), timeout (seconds, default 1.5), model_id and tool_versions to override what you set in retrack.init.

Recall fails open: on a timeout, a network error or a missing key it returns empty memory and logs a warning. It never raises, so it can never stop your agent.

How candidates are found

Retrack searches your agent's active playbooks two ways at once, by meaning (embeddings of the task) and by keywords, and merges the results. If embeddings are slow or unavailable, recall falls back to keywords alone rather than waiting. Each playbook is matched against its own task and the other wordings it was verified on.

The confidence gate

Every candidate gets a score:

score = similarity × confidence × success_rate × freshness × version_match
FactorWhat it measures
similarityHow close the task is to the playbook's kind of task
confidenceHow strong the evidence was for the runs that taught it
success_rateHow often runs that used it succeeded
freshnessDecays with time since its last success (30-day half-life)
version_match1.0 when validated on your current model and tool versions; lower when only tools match; 0 after a breaking tool version change

Only playbooks above your agent's threshold (0.72 by default) are returned, near-copies are dropped, and a playbook whose similarity is below the embedding model's floor is never returned, whatever its other factors.

What you get back

FieldMeaning
memory.playbooksGated playbooks, best first
memory.warningsUp to 5 relevant failure signatures
memory.holdoutTrue when this run is in the holdout group and gets no memory
memory.replay_planSet only when plan replay is allowed (below)

Linking recall to the run

retrack.recall(task) links itself to the next run automatically, so Retrack can count whether the playbook helped. With the explicit client, pass the same run_id to rt.recall(...) and to the graph's config (see the Python SDK).

Plan replay

For very well-proven playbooks, recall can offer a plan to follow directly, skipping planning. It is offered only when the task is a near-exact match, the playbook has at least 20 uses with at least 90% success, and it was validated on your exact model and tool versions. Playbooks with conditional steps are never replayed. A run that follows the plan reports it with rt.callback(replay_of=playbook_id); if it fails, the playbook goes back to candidate for review.

Speed

Measured from Vercel's Mumbai region, recalls that search by meaning took about 370 to 530 ms of server time; keyword-only recalls take a few tens of milliseconds. Your agent never waits longer than the timeout you set.