feat: Implement boolean search (#18)

Author: phernandez

src/basic_memory/mcp/tools/search.py

@@ -23,6 +23,7 @@ async def search(query: SearchQuery, page: int = 1, page_size: int = 10) -> Sear
     Args:
         query: SearchQuery object with search parameters including:
             - text: Full-text search (e.g., "project planning")
+              Supports boolean operators: AND, OR, NOT and parentheses for grouping
             - title: Search only in titles (e.g., "Meeting notes")
             - permalink: Exact permalink match (e.g., "docs/meeting-notes")
             - permalink_match: Pattern matching for permalinks (e.g., "docs/*-notes")
@@ -33,22 +34,24 @@ async def search(query: SearchQuery, page: int = 1, page_size: int = 10) -> Sear
         page_size: The number of results to return per page (default 10)
 
     Returns:
-        SearchResponse with:
-            - results: List of matching SearchResult objects with:
-                - id: Internal ID
-                - title: Document/entity title
-                - type: Content type (entity, observation, relation)
-                - score: Relevance score (higher = more relevant)
-                - permalink: Permalink for accessing the content
-                - file_path: File path on disk
-                - metadata: Additional metadata about the result
-            - current_page: Current page number
-            - page_size: Number of results per page
+        SearchResponse with results and pagination info
 
     Examples:
         # Basic text search
         results = await search(SearchQuery(text="project planning"))
 
+        # Boolean AND search (both terms must be present)
+        results = await search(SearchQuery(text="project AND planning"))
+
+        # Boolean OR search (either term can be present)
+        results = await search(SearchQuery(text="project OR meeting"))
+
+        # Boolean NOT search (exclude terms)
+        results = await search(SearchQuery(text="project NOT meeting"))
+
+        # Boolean search with grouping
+        results = await search(SearchQuery(text="(project OR planning) AND notes"))
+
         # Search with type filter
         results = await search(SearchQuery(
             text="meeting notes",

src/basic_memory/repository/search_repository.py

@@ -94,10 +94,16 @@ def _prepare_search_term(self, term: str, is_prefix: bool = True) -> str:
         For FTS5:
         - Special characters and phrases need to be quoted
         - Terms with spaces or special chars need quotes
+        - Boolean operators (AND, OR, NOT) and parentheses are preserved
         """
         if "*" in term:
             return term
 
+        # Check for boolean operators - if present, return the term as is
+        boolean_operators = [" AND ", " OR ", " NOT ", "(", ")"]
+        if any(op in f" {term} " for op in boolean_operators):
+            return term
+
         # List of special characters that need quoting (excluding *)
         special_chars = ["/", "-", ".", " ", "(", ")", "[", "]", '"', "'"]
 
@@ -130,9 +136,20 @@ async def search(
 
         # Handle text search for title and content
         if search_text:
-            search_text = self._prepare_search_term(search_text.strip())
-            params["text"] = search_text
-            conditions.append("(title MATCH :text OR content_stems MATCH :text)")
+            has_boolean = any(
+                op in f" {search_text} " for op in [" AND ", " OR ", " NOT ", "(", ")"]
+            )
+
+            if has_boolean:
+                # If boolean operators are present, use the raw query
+                # No need to prepare it, FTS5 will understand the operators
+                params["text"] = search_text
+                conditions.append("(title MATCH :text OR content_stems MATCH :text)")
+            else:
+                # Standard search with term preparation
+                processed_text = self._prepare_search_term(search_text.strip())
+                params["text"] = processed_text
+                conditions.append("(title MATCH :text OR content_stems MATCH :text)")
 
         # Handle title match search
         if title:

src/basic_memory/schemas/search.py

@@ -28,18 +28,24 @@ class SearchQuery(BaseModel):
     Use ONE of these primary search modes:
     - permalink: Exact permalink match
     - permalink_match: Path pattern with *
-    - text: Full-text search of title/content
+    - text: Full-text search of title/content (supports boolean operators: AND, OR, NOT)
 
     Optionally filter results by:
     - types: Limit to specific item types
     - entity_types: Limit to specific entity types
     - after_date: Only items after date
+
+    Boolean search examples:
+    - "python AND flask" - Find items with both terms
+    - "python OR django" - Find items with either term
+    - "python NOT django" - Find items with python but not django
+    - "(python OR flask) AND web" - Use parentheses for grouping
     """
 
     # Primary search modes (use ONE of these)
     permalink: Optional[str] = None  # Exact permalink match
     permalink_match: Optional[str] = None  # Glob permalink match
-    text: Optional[str] = None  # Full-text search
+    text: Optional[str] = None  # Full-text search (now supports boolean operators)
     title: Optional[str] = None  # title only search
 
     # Optional filters
@@ -66,6 +72,17 @@ def no_criteria(self) -> bool:
             and self.entity_types is None
         )
 
+    def has_boolean_operators(self) -> bool:
+        """Check if the text query contains boolean operators (AND, OR, NOT)."""
+        if not self.text:  # pragma: no cover
+            return False
+
+        # Check for common boolean operators with correct word boundaries
+        # to avoid matching substrings like "GRAND" containing "AND"
+        boolean_patterns = [" AND ", " OR ", " NOT ", "(", ")"]
+        text = f" {self.text} "  # Add spaces to ensure we match word boundaries
+        return any(pattern in text for pattern in boolean_patterns)
+
 
 class SearchResult(BaseModel):
     """Search result with score and metadata."""
@@ -93,13 +110,3 @@ class SearchResponse(BaseModel):
     results: List[SearchResult]
     current_page: int
     page_size: int
-
-
-# Schema for future advanced search endpoint
-class AdvancedSearchQuery(BaseModel):
-    """Advanced full-text search with explicit FTS5 syntax."""
-
-    query: str  # Raw FTS5 query (e.g., "foo AND bar")
-    types: Optional[List[SearchItemType]] = None
-    entity_types: Optional[List[str]] = None
-    after_date: Optional[Union[datetime, str]] = None

tests/schemas/test_search.py

@@ -7,7 +7,6 @@
     SearchQuery,
     SearchResult,
     SearchResponse,
-    AdvancedSearchQuery,
 )
 
 
@@ -118,12 +117,3 @@ def test_search_response():
     response = SearchResponse(results=results, current_page=1, page_size=1)
     assert len(response.results) == 2
     assert response.results[0].score > response.results[1].score
-
-
-def test_advanced_search():
-    """Test advanced search query."""
-    query = AdvancedSearchQuery(
-        query="title:search AND content:implementation", types=[SearchItemType.ENTITY]
-    )
-    assert query.query == "title:search AND content:implementation"
-    assert query.types == [SearchItemType.ENTITY]

tests/services/test_search_service.py

@@ -220,3 +220,119 @@ async def test_update_index(search_service, full_entity):
     # Search for new title
     results = await search_service.search(SearchQuery(text="OMG I AM UPDATED"))
     assert len(results) > 1
+
+
+@pytest.mark.asyncio
+async def test_boolean_and_search(search_service, test_graph):
+    """Test boolean AND search."""
+    # Create an entity with specific terms for testing
+    # This assumes the test_graph fixture already has entities with relevant terms
+
+    # Test AND operator - both terms must be present
+    results = await search_service.search(SearchQuery(text="Root AND Entity"))
+    assert len(results) >= 1
+
+    # Verify the result contains both terms
+    found = False
+    for result in results:
+        if (result.title and "Root" in result.title and "Entity" in result.title) or (
+            result.content_snippet
+            and "Root" in result.content_snippet
+            and "Entity" in result.content_snippet
+        ):
+            found = True
+            break
+    assert found, "Boolean AND search failed to find items containing both terms"
+
+    # Verify that items with only one term are not returned
+    results = await search_service.search(SearchQuery(text="NonexistentTerm AND Root"))
+    assert len(results) == 0, "Boolean AND search returned results when it shouldn't have"
+
+
+@pytest.mark.asyncio
+async def test_boolean_or_search(search_service, test_graph):
+    """Test boolean OR search."""
+    # Test OR operator - either term can be present
+    results = await search_service.search(SearchQuery(text="Root OR Connected"))
+
+    # Should find both "Root Entity" and "Connected Entity"
+    assert len(results) >= 2
+
+    # Verify we find items with either term
+    root_found = False
+    connected_found = False
+
+    for result in results:
+        if result.permalink == "test/root":
+            root_found = True
+        elif "connected" in result.permalink.lower():
+            connected_found = True
+
+    assert root_found, "Boolean OR search failed to find 'Root' term"
+    assert connected_found, "Boolean OR search failed to find 'Connected' term"
+
+
+@pytest.mark.asyncio
+async def test_boolean_not_search(search_service, test_graph):
+    """Test boolean NOT search."""
+    # Test NOT operator - exclude certain terms
+    results = await search_service.search(SearchQuery(text="Entity NOT Connected"))
+
+    # Should find "Root Entity" but not "Connected Entity"
+    for result in results:
+        assert "connected" not in result.permalink.lower(), (
+            "Boolean NOT search returned excluded term"
+        )
+
+
+@pytest.mark.asyncio
+async def test_boolean_group_search(search_service, test_graph):
+    """Test boolean grouping with parentheses."""
+    # Test grouping - (A OR B) AND C
+    results = await search_service.search(SearchQuery(title="(Root OR Connected) AND Entity"))
+
+    # Should find both entities that contain "Entity" and either "Root" or "Connected"
+    assert len(results) >= 2
+
+    for result in results:
+        # Each result should contain "Entity" and either "Root" or "Connected"
+        contains_entity = "entity" in result.title.lower()
+        contains_root_or_connected = (
+            "root" in result.title.lower() or "connected" in result.title.lower()
+        )
+
+        assert contains_entity and contains_root_or_connected, (
+            "Boolean grouped search returned incorrect results"
+        )
+
+
+@pytest.mark.asyncio
+async def test_boolean_operators_detection(search_service):
+    """Test detection of boolean operators in query."""
+    # Test various queries that should be detected as boolean
+    boolean_queries = [
+        "term1 AND term2",
+        "term1 OR term2",
+        "term1 NOT term2",
+        "(term1 OR term2) AND term3",
+        "complex (nested OR grouping) AND term",
+    ]
+
+    for query_text in boolean_queries:
+        query = SearchQuery(text=query_text)
+        assert query.has_boolean_operators(), f"Failed to detect boolean operators in: {query_text}"
+
+    # Test queries that should not be detected as boolean
+    non_boolean_queries = [
+        "normal search query",
+        "brand name",  # Should not detect "AND" within "brand"
+        "understand this concept",  # Should not detect "AND" within "understand"
+        "command line",
+        "sandbox testing",
+    ]
+
+    for query_text in non_boolean_queries:
+        query = SearchQuery(text=query_text)
+        assert not query.has_boolean_operators(), (
+            f"Incorrectly detected boolean operators in: {query_text}"
+        )