Search Modes

search_memories supports three modes via the search_type field: semantic, keyword, and hybrid. Note the default differs by interface: the MCP search_memories tool defaults to hybrid, while the REST POST /api/v1/memories/search endpoint defaults to semantic if search_type is omitted.

Semantic

Embeds the query and finds the nearest memories in the HNSW index by cosine similarity.

curl -X POST http://localhost:4545/api/v1/memories/search \
  -H "Content-Type: application/json" \
  -d '{"query": "user communication preferences", "search_type": "semantic", "limit": 10}'

Best for: natural language queries where meaning matters more than exact terms. Handles synonyms and paraphrase well.

Keyword

Queries the inverted keyword index.

curl -X POST http://localhost:4545/api/v1/memories/search \
  -H "Content-Type: application/json" \
  -d '{"query": "bullet points", "search_type": "keyword", "limit": 10}'

Best for: exact term matching — names, identifiers, technical terms that semantic embeddings may distort.

Hybrid

Combines semantic and keyword scoring. This is the recommended default for most queries, since it catches both paraphrased meaning and exact-term matches.

curl -X POST http://localhost:4545/api/v1/memories/search \
  -H "Content-Type: application/json" \
  -d '{"query": "how should I format responses?", "search_type": "hybrid", "limit": 10}'

Filtering

REST (POST /api/v1/memories/search) accepts filter fields directly on the request body:

{
  "query": "...",
  "search_type": "hybrid",
  "limit": 10,
  "memory_type": "long_term",
  "tags": ["preference"],
  "min_importance": 0.5,
  "max_importance": 1.0,
  "related_to": "mem_abc"
}

MCP (search_memories tool) nests the same kind of filters under a filters object, using importance_min/importance_max instead of min_importance/max_importance:

{
  "query": "...",
  "search_type": "hybrid",
  "limit": 10,
  "filters": {
    "memory_type": "long_term",
    "tags": ["preference"],
    "importance_min": 0.5,
    "importance_max": 1.0
  }
}

related_to (a memory UUID) is available on both interfaces and boosts memories connected to that memory in the graph.

Via MCP

{
  "tool": "search_memories",
  "arguments": {
    "query": "user communication style",
    "search_type": "hybrid",
    "limit": 5
  }
}