Hybrid Search

Advanced

Combine semantic similarity with knowledge graph proximity for more relevant search results

How Hybrid Search Works

Two signals, one ranked result

Hybrid search combines two ranking signals to find the most relevant results:

Semantic Search (60%)

Finds entities by meaning using vector embeddings. "authentication bug" matches "login error in JWT validation" even without shared keywords.

Graph Proximity (40%)

Boosts results that are closely connected in the knowledge graph. A decision linked to the issue you're searching for ranks higher.

0.6 × semantic_score + 0.4 × graph_proximity = final_score

Using Hybrid Search

REST API

curl -X POST http://localhost:7777/api/v1/my-namespace/hybrid-search \
  -H "Authorization: Bearer $ACE_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "authentication performance issues",
    "limit": 10
  }'

# Response:
# {
#   "results": [
#     {
#       "entity_type": "issue",
#       "entity_id": 42,
#       "title": "JWT validation timeout under load",
#       "semantic_score": 0.89,
#       "graph_score": 0.75,
#       "combined_score": 0.834
#     },
#     ...
#   ]
# }

Custom Weights

Tune the balance between semantic and graph signals

Adjust the weighting to suit your use case. Higher semantic weight for broad concept searches, higher graph weight when relationship context matters most.

# Heavy semantic weighting (concept search)
curl -X POST http://localhost:7777/api/v1/my-namespace/hybrid-search \
  -H "Authorization: Bearer $ACE_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "database optimization strategies",
    "semantic_weight": 0.8,
    "graph_weight": 0.2,
    "limit": 10
  }'

# Heavy graph weighting (relationship-focused)
curl -X POST http://localhost:7777/api/v1/my-namespace/hybrid-search \
  -H "Authorization: Bearer $ACE_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "auth service dependencies",
    "semantic_weight": 0.3,
    "graph_weight": 0.7,
    "limit": 10
  }'

When to Use Hybrid Search

Use Hybrid Search

When relationships between entities matter for relevance
Impact analysis: "what depends on this component?"
Root cause investigation across entity types
When you have a rich knowledge graph

Use Regular Search

-Simple keyword or concept lookups
-When you don't have many relationships yet
-Quick recall of specific memories
-When speed matters more than relationship context