Link Search Menu Expand Document Documentation Menu
Documentation

Hybrid search memory API

Introduced 3.6

Use this API to search long-term memories using a combination of BM25 keyword matching and semantic search. This is useful when your query benefits from both exact keyword precision and semantic understanding.

Hybrid search combines two search methods in a single query:

  1. BM25 keyword search: A match query on the memory field for exact keyword matching.
  2. Neural vector search: A neural query (or neural_sparse for SPARSE_ENCODING models) on the memory_embedding field for semantic similarity.

Results are combined using an inline normalization processor pipeline using min_max normalization and arithmetic_mean combination. The bm25_weight and neural_weight parameters control the relative importance of each search method. No preconfigured search pipeline is required.

The memory container must have an embedding model and at least one memory strategy configured.

Endpoints

POST /_plugins/_ml/memory_containers/{memory_container_id}/memories/long-term/_hybrid_search
GET /_plugins/_ml/memory_containers/{memory_container_id}/memories/long-term/_hybrid_search

Path parameters

The following table lists the available path parameters.

Parameter Data type Required/Optional Description
memory_container_id String Required The ID of the memory container.

Request fields

The following table lists the available request fields.

Field Data type Required/Optional Default Description
query String Required N/A A natural language search query used for both BM25 keyword matching and semantic search.
k Integer Optional 10 The number of results to return. Valid values are 1–10000, inclusive.
namespace Object Optional N/A Filters results by namespace fields. For example, {"user_id": "alice"}.
tags Object Optional N/A Filters results by tag fields. For example, {"topic": "food"}.
min_score Float Optional N/A The minimum relevance score threshold. Results below this score are excluded.
filter Object Optional N/A An additional Query DSL filter applied alongside the hybrid query.
bm25_weight Float Optional 0.5 The weight for the BM25 keyword search component. Valid values are 0.0–1.0. The sum of bm25_weight and neural_weight must equal 1.0.
neural_weight Float Optional 0.5 The weight for the neural vector search component. Valid values are 0.0–1.0. The sum of bm25_weight and neural_weight must equal 1.0. 
POST /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/_hybrid_search
{
  "query": "retirement timeline five years portfolio rebalancing",
  "k": 10,
  "namespace": {
    "user_id": "bob"
  }
}

Example request: Custom weights

You can adjust the balance between keyword and semantic search for each request. Increasing neural_weight prioritizes semantic similarity, while increasing bm25_weight higher prioritizes exact keyword matches:

POST /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/_hybrid_search
{
  "query": "machine learning outdoor activities",
  "k": 5,
  "namespace": {
    "user_id": "alice"
  },
  "bm25_weight": 0.3,
  "neural_weight": 0.7
}

Example request: Minimum score and tags filter

POST /_plugins/_ml/memory_containers/HudqiJkB1SltqOcZusVU/memories/long-term/_hybrid_search
{
  "query": "LGBTQ workshop therapeutic methods",
  "k": 10,
  "namespace": {
    "user_id": "caroline"
  },
  "tags": {
    "topic": "wellness"
  },
  "min_score": 0.3
}

Example response

{
  "took": 15,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 1.0,
    "hits": [
      {
        "_index": "test-memory-long-term",
        "_id": "abc123",
        "_score": 1.0,
        "_source": {
          "memory": "Caroline attended an LGBTQ+ counseling workshop focused on therapeutic methods",
          "strategy_type": "SEMANTIC",
          "namespace": {
            "user_id": "caroline"
          },
          "memory_container_id": "HudqiJkB1SltqOcZusVU",
          "created_time": 1700000000000,
          "last_updated_time": 1700000000000
        }
      },
      {
        "_index": "test-memory-long-term",
        "_id": "def456",
        "_score": 0.52,
        "_source": {
          "memory": "Caroline attended an LGBTQ conference on community building",
          "strategy_type": "SEMANTIC",
          "namespace": {
            "user_id": "caroline"
          },
          "memory_container_id": "HudqiJkB1SltqOcZusVU",
          "created_time": 1700000000000,
          "last_updated_time": 1700000000000
        }
      }
    ]
  }
}

Response fields

The response uses the standard OpenSearch search response format. For field descriptions, see Semantic search memory response fields.

The memory_embedding field is excluded from the response.

350 characters left

Have a question? .

Want to contribute? or .