Recall

Recall is how an agent gets context before it answers. One hm_recall call searches your memory — and your organization’s — and returns the most relevant memories with the relationships around them.

The pipeline

1

Two searches at once

The query runs through semantic search (vector embeddings, for meaning) and keyword search (BM25, for exact names, terms and codes) in parallel. Each returns its best candidates.

2

Fusion

The two lists are merged with reciprocal-rank fusion, so a memory that ranks well in both rises to the top.

3

Re-ranking

A cross-encoder re-ranker reads the query and each candidate together and scores how well the memory actually answers it.

4

Relevance floor

Candidates below a relevance threshold are dropped. Recall returns fewer, better results rather than padding the list.

5

Graph context

Each result gets its strongest relationships attached (expansion_context), so the agent sees not just the memory but what it's connected to.

In parallel, if you belong to an organization, the same query runs against the organization’s graph and comes back under organization_memory.

Reading the result

Field	Meaning
score	The final relevance, after re-ranking.
scores.dense, scores.bm25	How the memory scored in each search.
scores.rrf	Its fused rank score.
expansion_context	The relationships connecting it to the rest of your graph.
_search_meta.below_threshold	How many candidates were dropped by the relevance floor.

Sessions

Pass the conversation’s id as session_id. HyperMemory records which memories the conversation touched, so they can be reloaded later with hm_get_chat_context.

Regular expressions

With force_regex: true, recall runs a bounded regular-expression scan over keys, descriptions and data instead of search — useful for IDs, ticket numbers and exact patterns.

Getting better recall

• Write descriptions that lead with the point, in the words people search with. See Nodes.
• Use the user’s own words in the query; keyword search rewards exact names.
• Connect your memories. Graph context only helps when nodes are linked; keep orphans down with hm_list_orphans.
• Fetch details separately. Recall returns enough to decide; hm_get_nodes returns everything about the nodes you pick.