recall

const { payload, tokensSaved } = await hm.recall({
  q: "how often can we deploy?",
  budget: 2000,
});

payload is ready to put in a prompt. It is not a list of hits, selection, ordering and formatting are the point, and reassembling them yourself would throw all three away.

Parameters

Result

{
  payload: string;          // ready for a prompt
  memoryIds: string[];
  memories?: Memory[];      // with include.memories
  threadId: string | null;
  candidateCount: number;   // considered
  droppedCount: number;     // discarded as too weak
  tokensSaved: number;      // against sending everything found
  latencyMs: number;
}

An empty payload is a real answer

const { memoryIds } = await hm.recall({ q: "what is the capital of Peru" });
// memoryIds.length === 0

If nothing is relevant enough, nothing comes back. Check memoryIds.length rather than assuming there is always something to inject, a memory layer that always finds something buries the answer in noise.

Filtering

await hm.recall({
  q: "database migrations",
  filters: {
    AND: [
      { key: "team", value: "platform" },
      { key: "priority", value: 5, comparator: "gte", numeric: true },
    ],
  },
});

Comparators: eq, ne, gt, gte, lt, lte, contains, in. Nest with AND and OR; add negate: true to invert; add numeric: true to compare as numbers rather than text.

Formatting for the receiving tool

await hm.recall({ q: "…", targetTool: "claude-code" });

The same memories are shaped differently for a client that expects structured context than for one that expects prose. If you are assembling a prompt yourself, leave it unset.

Tuning

Getting too little. Lower threshold, or set rewriteQuery: true if queries are terse, "db for invoicing" and "which database does billing use" should find the same thing.

Getting too much. Raise threshold, or set a limit.

Right results, wrong order. rerank: true. It costs about 100ms and helps most when several results are genuinely close.