Support keyword and hybrid memory search

Author: abrookins

agent-memory-client/agent-memory-client-java/src/main/java/com/redis/agentmemory/models/longtermemory/MemoryRecordResult.java

@@ -6,6 +6,8 @@
 public class MemoryRecordResult extends MemoryRecord {
 
     private double dist;
+    private Double score;
+    private String scoreType;
 
     public MemoryRecordResult() {
         super();
@@ -19,10 +21,29 @@ public void setDist(double dist) {
         this.dist = dist;
     }
 
+    public Double getScore() {
+        return score;
+    }
+
+    public void setScore(Double score) {
+        this.score = score;
+    }
+
+    public String getScoreType() {
+        return scoreType;
+    }
+
+    @com.fasterxml.jackson.annotation.JsonProperty("score_type")
+    public void setScoreType(String scoreType) {
+        this.scoreType = scoreType;
+    }
+
     @Override
     public String toString() {
         return "MemoryRecordResult{" +
                 "dist=" + dist +
+                ", score=" + score +
+                ", scoreType='" + scoreType + '\'' +
                 ", " + super.toString() +
                 '}';
     }

agent-memory-client/agent-memory-client-java/src/main/java/com/redis/agentmemory/models/longtermemory/SearchRequest.java

@@ -15,6 +15,16 @@ public class SearchRequest {
     @Nullable
     private String text;
 
+    @Nullable
+    @JsonProperty("search_mode")
+    private String searchMode;
+
+    @JsonProperty("hybrid_alpha")
+    private double hybridAlpha = 0.7;
+
+    @JsonProperty("text_scorer")
+    private String textScorer = "BM25STD";
+
     @Nullable
     @JsonProperty("session_id")
     private String sessionId;
@@ -85,6 +95,32 @@ public void setText(@Nullable String text) {
         this.text = text;
     }
 
+    @Nullable
+    public String getSearchMode() {
+        return searchMode;
+    }
+
+    public void setSearchMode(@Nullable String searchMode) {
+        this.searchMode = searchMode;
+    }
+
+    public double getHybridAlpha() {
+        return hybridAlpha;
+    }
+
+    public void setHybridAlpha(double hybridAlpha) {
+        this.hybridAlpha = hybridAlpha;
+    }
+
+    @Nullable
+    public String getTextScorer() {
+        return textScorer;
+    }
+
+    public void setTextScorer(@Nullable String textScorer) {
+        this.textScorer = textScorer;
+    }
+
     @Nullable
     public String getSessionId() {
         return sessionId;
@@ -231,6 +267,9 @@ public void setServerSideRecency(@Nullable Boolean serverSideRecency) {
     public String toString() {
         return "SearchRequest{" +
                 "text='" + text + '\'' +
+                ", searchMode='" + searchMode + '\'' +
+                ", hybridAlpha=" + hybridAlpha +
+                ", textScorer='" + textScorer + '\'' +
                 ", sessionId='" + sessionId + '\'' +
                 ", namespace='" + namespace + '\'' +
                 ", topics=" + topics +
@@ -269,6 +308,21 @@ public Builder text(@Nullable String text) {
             return this;
         }
 
+        public Builder searchMode(@Nullable String searchMode) {
+            request.searchMode = searchMode;
+            return this;
+        }
+
+        public Builder hybridAlpha(double hybridAlpha) {
+            request.hybridAlpha = hybridAlpha;
+            return this;
+        }
+
+        public Builder textScorer(@Nullable String textScorer) {
+            request.textScorer = textScorer;
+            return this;
+        }
+
         public Builder sessionId(@Nullable String sessionId) {
             request.sessionId = sessionId;
             return this;

agent-memory-client/agent-memory-client-java/src/main/java/com/redis/agentmemory/services/LongTermMemoryService.java

@@ -74,6 +74,9 @@ public MemoryRecordResults searchLongTermMemories(@NotNull SearchRequest request
         // Build payload
         Map<String, Object> payload = new HashMap<>();
         payload.put("text", request.getText());
+        payload.put("search_mode", request.getSearchMode() != null ? request.getSearchMode() : "semantic");
+        payload.put("hybrid_alpha", request.getHybridAlpha());
+        payload.put("text_scorer", request.getTextScorer() != null ? request.getTextScorer() : "BM25STD");
         payload.put("limit", request.getLimit());
         payload.put("offset", request.getOffset());
 

agent-memory-client/agent-memory-client-js/src/client.test.ts

@@ -577,6 +577,21 @@ describe("MemoryAPIClient", () => {
       expect(callBody.distance_threshold).toBe(0.5);
     });
 
+    it("should include search mode parameters in request body", async () => {
+      mockFetch = createMockFetch({ memories: [], total: 0 });
+      client["fetchFn"] = mockFetch;
+      await client.searchLongTermMemory({
+        text: "test",
+        searchMode: "hybrid",
+        hybridAlpha: 0.55,
+        textScorer: "BM25",
+      });
+      const callBody = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(callBody.search_mode).toBe("hybrid");
+      expect(callBody.hybrid_alpha).toBe(0.55);
+      expect(callBody.text_scorer).toBe("BM25");
+    });
+
     it("should handle SessionId filter class", async () => {
       const { SessionId } = await import("./filters");
       mockFetch = createMockFetch({ memories: [], total: 0 });

agent-memory-client/agent-memory-client-js/src/client.ts

@@ -71,6 +71,9 @@ export interface MemoryClientConfig {
  */
 export interface SearchOptions {
   text: string;
+  searchMode?: "semantic" | "keyword" | "hybrid";
+  hybridAlpha?: number;
+  textScorer?: string;
   sessionId?: SessionId | { eq?: string; in_?: string[]; not_eq?: string; not_in?: string[] };
   namespace?: Namespace | { eq?: string; in_?: string[]; not_eq?: string; not_in?: string[] };
   topics?: Topics | { any?: string[]; all?: string[]; none?: string[] };
@@ -382,6 +385,9 @@ export class MemoryAPIClient {
   async searchLongTermMemory(options: SearchOptions): Promise<MemoryRecordResults> {
     const body: Record<string, unknown> = {
       text: options.text,
+      search_mode: options.searchMode ?? "semantic",
+      hybrid_alpha: options.hybridAlpha ?? 0.7,
+      text_scorer: options.textScorer ?? "BM25STD",
       limit: options.limit,
       offset: options.offset,
       distance_threshold: options.distanceThreshold,

agent-memory-client/agent-memory-client-js/src/models.ts

@@ -202,6 +202,10 @@ export interface SessionListResponse {
 export interface MemoryRecordResult extends MemoryRecord {
   /** Distance/similarity score */
   dist: number;
+  /** Normalized relevance score for the selected search mode */
+  score?: number | null;
+  /** Search mode used to produce the normalized score */
+  score_type?: "semantic" | "keyword" | "hybrid" | null;
 }
 
 /**
@@ -267,6 +271,9 @@ export interface MemoryPromptRequest {
  */
 export interface SearchRequestParams {
   text?: string;
+  search_mode?: "semantic" | "keyword" | "hybrid";
+  hybrid_alpha?: number;
+  text_scorer?: string;
   session_id?: SessionIdFilter | null;
   namespace?: NamespaceFilter | null;
   topics?: TopicsFilter | null;

agent-memory-client/agent_memory_client/client.py

@@ -48,6 +48,7 @@
     MemoryTypeEnum,
     ModelNameLiteral,
     RecencyConfig,
+    SearchModeEnum,
     SessionListResponse,
     SummaryView,
     SummaryViewPartitionResult,
@@ -1033,6 +1034,9 @@ async def get_task(self, task_id: str) -> Task | None:
     async def search_long_term_memory(
         self,
         text: str,
+        search_mode: SearchModeEnum | str = SearchModeEnum.SEMANTIC,
+        hybrid_alpha: float = 0.7,
+        text_scorer: str = "BM25STD",
         session_id: SessionId | dict[str, Any] | None = None,
         namespace: Namespace | dict[str, Any] | None = None,
         topics: Topics | dict[str, Any] | None = None,
@@ -1048,10 +1052,13 @@ async def search_long_term_memory(
         optimize_query: bool = False,
     ) -> MemoryRecordResults:
         """
-        Search long-term memories using semantic search and filters.
+        Search long-term memories using semantic, keyword, or hybrid search.
 
         Args:
-            text: Query for vector search - will be used for semantic similarity matching
+            text: Query text used for semantic, keyword, or hybrid search
+            search_mode: Search strategy to use
+            hybrid_alpha: Weight assigned to vector similarity in hybrid search
+            text_scorer: Redis full-text scoring algorithm for keyword and hybrid search
             session_id: Optional session ID filter
             namespace: Optional namespace filter
             topics: Optional topics filter
@@ -1141,6 +1148,13 @@ async def search_long_term_memory(
             payload["memory_type"] = memory_type.model_dump(exclude_none=True)
         if distance_threshold is not None:
             payload["distance_threshold"] = distance_threshold
+        payload["search_mode"] = (
+            search_mode.value
+            if isinstance(search_mode, SearchModeEnum)
+            else str(search_mode)
+        )
+        payload["hybrid_alpha"] = hybrid_alpha
+        payload["text_scorer"] = text_scorer
 
         # Add recency config if provided
         if recency is not None:
@@ -1185,6 +1199,7 @@ async def search_long_term_memory(
     async def search_memory_tool(
         self,
         query: str,
+        search_mode: SearchModeEnum | str = SearchModeEnum.SEMANTIC,
         topics: Sequence[str] | None = None,
         entities: Sequence[str] | None = None,
         memory_type: str | None = None,
@@ -1258,6 +1273,7 @@ async def search_memory_tool(
 
         results = await self.search_long_term_memory(
             text=query,
+            search_mode=search_mode,
             topics=topics_filter,
             entities=entities_filter,
             memory_type=memory_type_filter,
@@ -1281,9 +1297,13 @@ async def search_memory_tool(
                     "created_at": memory.created_at.isoformat()
                     if memory.created_at
                     else None,
-                    "relevance_score": 1.0 - memory.dist
-                    if hasattr(memory, "dist") and memory.dist is not None
-                    else None,
+                    "relevance_score": memory.score
+                    if hasattr(memory, "score") and memory.score is not None
+                    else (
+                        1.0 - memory.dist
+                        if hasattr(memory, "dist") and memory.dist is not None
+                        else None
+                    ),
                 }
             )
 

agent-memory-client/agent_memory_client/models.py

@@ -56,6 +56,22 @@ class MemoryTypeEnum(str, Enum):
     MESSAGE = "message"
 
 
+class SearchModeEnum(str, Enum):
+    """Enum for supported search strategies."""
+
+    SEMANTIC = "semantic"
+    KEYWORD = "keyword"
+    HYBRID = "hybrid"
+
+
+class SearchScoreTypeEnum(str, Enum):
+    """Enum describing how the normalized score field was produced."""
+
+    SEMANTIC = "semantic"
+    KEYWORD = "keyword"
+    HYBRID = "hybrid"
+
+
 class MemoryStrategyConfig(BaseModel):
     """Configuration for memory extraction strategy."""
 
@@ -352,6 +368,14 @@ class MemoryRecordResult(MemoryRecord):
     """Result from a memory search"""
 
     dist: float
+    score: float | None = Field(
+        default=None,
+        description="Normalized relevance score for the selected search mode (0-1)",
+    )
+    score_type: SearchScoreTypeEnum | None = Field(
+        default=None,
+        description="Search mode used to produce the normalized score",
+    )
 
 
 class RecencyConfig(BaseModel):

agent-memory-client/tests/test_client.py

@@ -21,6 +21,7 @@
     MemoryRecordResults,
     MemoryTypeEnum,
     RecencyConfig,
+    SearchModeEnum,
     WorkingMemoryResponse,
 )
 
@@ -345,6 +346,31 @@ async def test_recency_config_descriptive_parameters(self, enhanced_test_client)
             assert body["recency_half_life_created_days"] == 30
             assert body["server_side_recency"] is True
 
+    @pytest.mark.asyncio
+    async def test_search_mode_parameters_are_sent_to_api(self, enhanced_test_client):
+        """Test that keyword/hybrid search parameters are sent to the API."""
+        with patch.object(enhanced_test_client._client, "post") as mock_post:
+            mock_response = Mock()
+            mock_response.raise_for_status.return_value = None
+            mock_response.json.return_value = MemoryRecordResults(
+                total=0, memories=[], next_offset=None
+            ).model_dump()
+            mock_post.return_value = mock_response
+
+            await enhanced_test_client.search_long_term_memory(
+                text="alpha beta",
+                search_mode=SearchModeEnum.HYBRID,
+                hybrid_alpha=0.55,
+                text_scorer="BM25",
+                limit=5,
+            )
+
+            _, kwargs = mock_post.call_args
+            body = kwargs["json"]
+            assert body["search_mode"] == "hybrid"
+            assert body["hybrid_alpha"] == 0.55
+            assert body["text_scorer"] == "BM25"
+
 
 class TestClientSideValidation:
     """Tests for client-side validation methods."""

agent_memory_server/api.py

@@ -645,7 +645,7 @@ async def search_long_term_memory(
     current_user: UserInfo = Depends(get_current_user),
 ):
     """
-    Run a semantic search on long-term memory with filtering options.
+    Run a long-term memory search with semantic, keyword, or hybrid options.
 
     Args:
         payload: Search payload with filter objects for precise queries
@@ -663,6 +663,9 @@ async def search_long_term_memory(
     logger.debug(f"Long-term search filters: {filters}")
 
     kwargs = {
+        "search_mode": payload.search_mode,
+        "hybrid_alpha": payload.hybrid_alpha,
+        "text_scorer": payload.text_scorer,
         "distance_threshold": payload.distance_threshold,
         "limit": payload.limit,
         "offset": payload.offset,