feat: add filter for user and long-term memory

MemTensor · CaralHsi · Sep 16, 2025 · Sep 10, 2025 · Sep 10, 2025 · Sep 11, 2025
commit f2d275b55bb4880ef22f2979fda78028a511d18b
diff --git a/src/memos/graph_dbs/nebular.py b/src/memos/graph_dbs/nebular.py
@@ -972,6 +972,7 @@ def search_by_embedding(
         scope: str | None = None,
         status: str | None = None,
         threshold: float | None = None,
+        search_filter: dict | None = None,
         **kwargs,
     ) -> list[dict]:
         """
@@ -984,6 +985,8 @@ def search_by_embedding(
             status (str, optional): Node status filter (e.g., 'active', 'archived').
                             If provided, restricts results to nodes with matching status.
             threshold (float, optional): Minimum similarity score threshold (0 ~ 1).
+            search_filter (dict, optional): Additional metadata filters for search results.
+                            Keys should match node properties, values are the expected values.
 
         Returns:
             list[dict]: A list of dicts with 'id' and 'score', ordered by similarity.
@@ -993,6 +996,7 @@ def search_by_embedding(
             - If scope is provided, it restricts results to nodes with matching memory_type.
             - If 'status' is provided, only nodes with the matching status will be returned.
             - If threshold is provided, only results with score >= threshold will be returned.
+            - If search_filter is provided, additional WHERE clauses will be added for metadata filtering.
             - Typical use case: restrict to 'status = activated' to avoid
             matching archived or merged nodes.
         """
@@ -1012,6 +1016,14 @@ def search_by_embedding(
             else:
                 where_clauses.append(f'n.user_name = "{self.config.user_name}"')
 
+                # Add search_filter conditions
+                if search_filter:
+                    for key, value in search_filter.items():
+                        if isinstance(value, str):
+                            where_clauses.append(f'n.{key} = "{value}"')
+                        else:
+                            where_clauses.append(f"n.{key} = {value}")
+
         where_clause = f"WHERE {' AND '.join(where_clauses)}" if where_clauses else ""
 
         gql = f"""

diff --git a/src/memos/graph_dbs/neo4j.py b/src/memos/graph_dbs/neo4j.py
@@ -606,6 +606,7 @@ def search_by_embedding(
         scope: str | None = None,
         status: str | None = None,
         threshold: float | None = None,
+        search_filter: dict | None = None,
         **kwargs,
     ) -> list[dict]:
         """
@@ -618,6 +619,8 @@ def search_by_embedding(
             status (str, optional): Node status filter (e.g., 'active', 'archived').
                             If provided, restricts results to nodes with matching status.
             threshold (float, optional): Minimum similarity score threshold (0 ~ 1).
+            search_filter (dict, optional): Additional metadata filters for search results.
+                            Keys should match node properties, values are the expected values.
 
         Returns:
             list[dict]: A list of dicts with 'id' and 'score', ordered by similarity.
@@ -627,6 +630,7 @@ def search_by_embedding(
             - If scope is provided, it restricts results to nodes with matching memory_type.
             - If 'status' is provided, only nodes with the matching status will be returned.
             - If threshold is provided, only results with score >= threshold will be returned.
+            - If search_filter is provided, additional WHERE clauses will be added for metadata filtering.
             - Typical use case: restrict to 'status = activated' to avoid
             matching archived or merged nodes.
         """
@@ -639,6 +643,12 @@ def search_by_embedding(
         if not self.config.use_multi_db and self.config.user_name:
             where_clauses.append("node.user_name = $user_name")
 
+        # Add search_filter conditions
+        if search_filter:
+            for key, _ in search_filter.items():
+                param_name = f"filter_{key}"
+                where_clauses.append(f"node.{key} = ${param_name}")
+
         where_clause = ""
         if where_clauses:
             where_clause = "WHERE " + " AND ".join(where_clauses)
@@ -650,7 +660,8 @@ def search_by_embedding(
             RETURN node.id AS id, score
         """
 
-        parameters = {"embedding": vector, "k": top_k, "scope": scope}
+        parameters = {"embedding": vector, "k": top_k}
+
         if scope:
             parameters["scope"] = scope
         if status:
@@ -661,6 +672,12 @@ def search_by_embedding(
             else:
                 parameters["user_name"] = self.config.user_name
 
+        # Add search_filter parameters
+        if search_filter:
+            for key, value in search_filter.items():
+                param_name = f"filter_{key}"
+                parameters[param_name] = value
+
         with self.driver.session(database=self.db_name) as session:
             result = session.run(query, parameters)
             records = [{"id": record["id"], "score": record["score"]} for record in result]

diff --git a/src/memos/graph_dbs/neo4j_community.py b/src/memos/graph_dbs/neo4j_community.py
@@ -129,6 +129,7 @@ def search_by_embedding(
         scope: str | None = None,
         status: str | None = None,
         threshold: float | None = None,
+        search_filter: dict | None = None,
         **kwargs,
     ) -> list[dict]:
         """
@@ -140,6 +141,7 @@ def search_by_embedding(
             scope (str, optional): Memory type filter (e.g., 'WorkingMemory', 'LongTermMemory').
             status (str, optional): Node status filter (e.g., 'activated', 'archived').
             threshold (float, optional): Minimum similarity score threshold (0 ~ 1).
+            search_filter (dict, optional): Additional metadata filters to apply.
 
         Returns:
             list[dict]: A list of dicts with 'id' and 'score', ordered by similarity.
@@ -149,6 +151,7 @@ def search_by_embedding(
             - If 'scope' is provided, it restricts results to nodes with matching memory_type.
             - If 'status' is provided, it further filters nodes by status.
             - If 'threshold' is provided, only results with score >= threshold will be returned.
+            - If 'search_filter' is provided, it applies additional metadata-based filtering.
             - The returned IDs can be used to fetch full node data from Neo4j if needed.
         """
         # Build VecDB filter
@@ -163,6 +166,10 @@ def search_by_embedding(
         else:
             vec_filter["user_name"] = self.config.user_name
 
+        # Add search_filter conditions
+        if search_filter:
+            vec_filter.update(search_filter)
+
         # Perform vector search
         results = self.vec_db.search(query_vector=vector, top_k=top_k, filter=vec_filter)
 

diff --git a/src/memos/mem_os/core.py b/src/memos/mem_os/core.py
@@ -624,6 +624,7 @@ def add(
         doc_path: str | None = None,
         mem_cube_id: str | None = None,
         user_id: str | None = None,
+        **kwargs,
     ) -> None:
         """
         Add textual memories to a MemCube.

diff --git a/src/memos/memories/textual/tree_text_memory/retrieve/recall.py b/src/memos/memories/textual/tree_text_memory/retrieve/recall.py
@@ -193,16 +193,19 @@ def _vector_recall(
         search_filter: dict | None = None,
     ) -> list[TextualMemoryItem]:
         """
-        TODO: use search filter if exists
-        # TODO: tackle with post-filter and pre-filter(5.18+) better.
         Perform vector-based similarity retrieval using query embedding.
+        # TODO: tackle with post-filter and pre-filter(5.18+) better.
         """
         all_matches = []
 
         def search_single(vec):
             return (
                 self.graph_store.search_by_embedding(
-                    vector=vec, top_k=top_k, scope=memory_scope, cube_name=cube_name
+                    vector=vec,
+                    top_k=top_k,
+                    scope=memory_scope,
+                    cube_name=cube_name,
+                    search_filter=search_filter,
                 )
                 or []
             )