Memory
hm_recall
Search memory with hybrid semantic, keyword and graph retrieval — including organization memory
hm_recall is the tool agents call first, before composing a reply. It searches your memory graph — and, if you belong to an organization, that organization’s memory in parallel — and returns the most relevant nodes with their nearest relationships.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
query | string | required | What to look for, in natural language. With force_regex, a regular expression. |
max_results | integer | 10 | How many results to return (1–50). |
organization_id | string | — | Which organization’s memory to search alongside yours: an organization id from hm_get_overview, or "none" for personal memory only. Omit it if you belong to exactly one organization. |
session_id | string | "default" | The conversation’s id. Records what the conversation touched, for hm_get_chat_context. |
force_regex | boolean | false | Treat query as a regular expression over keys, descriptions and data. |
How search works
Each recall runs two searches at once and combines them:
| Search | What it finds |
|---|---|
| Semantic | Memories whose meaning is close to the query, using vector embeddings. |
| Keyword (BM25) | Exact words and names: product names, error codes, people. |
The two result lists are merged with reciprocal-rank fusion, re-ranked by a cross-encoder, and cut at a relevance floor, so weak matches are dropped instead of padding the list. Finally each result gets its graph context: the strongest relationships that connect it to the rest of your graph, in expansion_context.
See Recall for the full pipeline.
Response
| Field | Description |
|---|---|
results | Ranked nodes. Each has key, node_type, description, data, score, per-leg scores (dense, bm25, rrf, relevance), enrichment_status and expansion_context. |
count | Number of results. |
organization_memory | Results from your organization’s graph, searched in parallel. See below. |
_search_meta | Diagnostics: which searches ran, their hit counts and timings, the fusion and re-rank details, and how many candidates fell below the relevance floor. |
organization_memory
status | Meaning |
|---|---|
included | Results from the organization’s graph are attached, labelled with the organization’s name. |
selection_required | You belong to several organizations and sent no organization_id. Ask which organization the project uses, then send its id. |
excluded | You sent "none". |
selected_graph | The credential’s own graph is the organization graph, so the main results already are its memory. |
failed | The organization search failed. Your own results are still valid. |
Organization memory is read-only for members. See Organization memory.
Example
{
"query": "how do we authenticate the public API",
"max_results": 5,
"session_id": "chat_7f3a"
}{
"count": 2,
"results": [
{
"key": "decision_jwt_auth",
"node_type": "decision",
"description": "Chose JWT access tokens over server sessions for the public API so it can scale statelessly across regions.",
"score": 0.81,
"scores": { "dense": 0.62, "bm25": 21.4, "relevance": 0.81 },
"expansion_context": [
{
"direction": "outgoing",
"key": "project_public_api",
"relationship": "authentication decision for the public API project"
}
]
}
],
"organization_memory": {
"status": "included",
"name": "Acme",
"count": 1,
"results": [ ... ]
}
}Tips
- Recall before you store. It is the cheapest way to avoid duplicates.
- Recall with the user’s own words. Keyword search rewards the exact names and terms they use.
- Know the key already? Use
hm_get_nodesto fetch full, untruncated details instead of searching. - Need “when”, not “what”? Use
hm_timeline.