API Reference
hm_recall
Hybrid search across the knowledge graph
hm_recall
Search the hypergraph using a hybrid search pipeline that combines multiple retrieval strategies for high-quality results.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
query | str | required | Search query (natural language or regex pattern) |
session_id | str | "default" | Session scope for ranking and context expansion |
max_results | int | 10 | Max nodes returned (1–50) |
force_regex | bool | false | Treat query as a regex pattern |
Search pipeline
The search pipeline runs four candidate generation strategies in parallel:
| Strategy | Description |
|---|---|
| BM25 on node descriptions | Full-text keyword matching against node description fields |
| Qdrant vector similarity | Cosine similarity with a threshold of 0.35 |
| BM25 on edge labels | Full-text matching against relationship labels |
| Regex fallback | Pattern matching for exact or regex queries |
Session awareness
A Redis sorted set tracks recently accessed nodes. These receive a decayed boost (half-life of 1800 seconds) so that contextually relevant nodes from the current session rank higher.
Scoring
Results are scored using a weighted fusion of three signals:
| Signal | Description |
|---|---|
| General score | Raw relevance from the search strategies |
| Topical score | Graph distance from recently accessed (“hot”) nodes |
| Session score | Recency boost from the Redis session tracker |
The weights shift across search phases (early, mid, deep) to balance exploration and exploitation.
Context expansion
After scoring, the pipeline traverses from top results to add relationship context — connected nodes and edges that provide additional context for the agent.
Response
Returns ranked nodes with scores, connected edges, and metadata about the search including phase, weights, and tier breakdown.
Example
{
"query": "JWT authentication decisions"
}CLI equivalent
hm recall "JWT authentication decisions"REST endpoint
POST /api/v1/memory/recall