fix: stabilize semantic search defaults, FTS fallback, and postgres project sync

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

.github/workflows/test.yml

@@ -102,6 +102,41 @@ jobs:
           uv pip install pytest pytest-cov
           just test-postgres
 
+  test-semantic:
+    name: Test Semantic (Python 3.12)
+    timeout-minutes: 45
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - uses: extractions/setup-just@v3
+
+      - name: Create virtual env
+        run: |
+          uv venv
+
+      - name: Install dependencies
+        run: |
+          uv pip install -e ".[dev,semantic]"
+
+      - name: Run tests (Semantic)
+        run: |
+          uv pip install pytest pytest-cov
+          just test-semantic
+
   coverage:
     name: Coverage Summary (combined, Python 3.12)
     timeout-minutes: 30

justfile

@@ -209,6 +209,9 @@ update-deps:
 # Run all code quality checks and tests
 check: lint format typecheck test
 
+# Run all code quality checks and all test suites, including semantic benchmarks
+check-all: lint format typecheck test test-semantic
+
 # Generate Alembic migration with descriptive message
 migration message:
     cd src/basic_memory/alembic && alembic revision --autogenerate -m "{{message}}"

src/basic_memory/config.py

@@ -1,5 +1,6 @@
 """Configuration management for basic-memory."""
 
+import importlib.util
 import json
 import os
 from dataclasses import dataclass
@@ -38,6 +39,11 @@ class DatabaseBackend(str, Enum):
     POSTGRES = "postgres"
 
 
+def _default_semantic_search_enabled() -> bool:
+    """Enable semantic search by default when semantic extras are installed."""
+    return importlib.util.find_spec("fastembed") is not None
+
+
 @dataclass
 class ProjectConfig:
     """Configuration for a specific basic-memory project."""
@@ -138,7 +144,7 @@ class BasicMemoryConfig(BaseSettings):
 
     # Semantic search configuration
     semantic_search_enabled: bool = Field(
-        default=False,
+        default_factory=_default_semantic_search_enabled,
         description="Enable semantic search (vector/hybrid retrieval). Works on both SQLite and Postgres backends. Requires semantic extras.",
     )
     semantic_embedding_provider: str = Field(

src/basic_memory/mcp/clients/knowledge.py

@@ -224,11 +224,12 @@ async def delete_directory(self, directory: str) -> DirectoryDeleteResult:
 
     # --- Resolution ---
 
-    async def resolve_entity(self, identifier: str) -> str:
+    async def resolve_entity(self, identifier: str, *, strict: bool = False) -> str:
         """Resolve a string identifier to an entity external_id.
 
         Args:
             identifier: The identifier to resolve (permalink, title, or path)
+            strict: If True, require exact matching (no fuzzy fallback)
 
         Returns:
             The resolved entity external_id (UUID)
@@ -239,7 +240,7 @@ async def resolve_entity(self, identifier: str) -> str:
         response = await call_post(
             self.http_client,
             f"{self._base_path}/resolve",
-            json={"identifier": identifier},
+            json={"identifier": identifier, "strict": strict},
         )
         data = response.json()
         return data["external_id"]

src/basic_memory/mcp/tools/read_note.py

@@ -14,6 +14,11 @@
 from basic_memory.utils import validate_project_path
 
 
+def _is_exact_title_match(identifier: str, title: str) -> bool:
+    """Return True when identifier exactly matches a title (case-insensitive)."""
+    return identifier.strip().casefold() == title.strip().casefold()
+
+
 @mcp.tool(
     description="Read a markdown note by title or permalink.",
     # TODO: re-enable once MCP client rendering is working
@@ -118,7 +123,7 @@ async def read_note(
 
         try:
             # Try to resolve identifier to entity ID
-            entity_id = await knowledge_client.resolve_entity(entity_path)
+            entity_id = await knowledge_client.resolve_entity(entity_path, strict=True)
 
             # Fetch content using entity ID
             response = await resource_client.read(entity_id, page=page, page_size=page_size)
@@ -148,17 +153,29 @@ async def read_note(
 
         # Handle both SearchResponse object and error strings
         if title_results and hasattr(title_results, "results") and title_results.results:
-            result = title_results.results[0]  # Get the first/best match
-            if result.permalink:
+            # Trigger: direct resolution failed and title search returned candidates.
+            # Why: avoid returning unrelated notes when search yields only fuzzy matches.
+            # Outcome: fetch content only when a true exact title match exists.
+            result = next(
+                (
+                    candidate
+                    for candidate in title_results.results
+                    if _is_exact_title_match(identifier, candidate.title)
+                ),
+                None,
+            )
+            if not result:
+                logger.info(f"No exact title match found for: {identifier}")
+            elif result.permalink:
                 try:
                     # Resolve the permalink to entity ID
-                    entity_id = await knowledge_client.resolve_entity(result.permalink)
+                    entity_id = await knowledge_client.resolve_entity(result.permalink, strict=True)
 
                     # Fetch content using the entity ID
                     response = await resource_client.read(entity_id, page=page, page_size=page_size)
 
                     if response.status_code == 200:
-                        logger.info(f"Found note by title search: {result.permalink}")
+                        logger.info(f"Found note by exact title search: {result.permalink}")
                         if output_format in ("ascii", "ansi"):
                             return format_note_preview_ascii(
                                 response.text,

src/basic_memory/mcp/tools/search.py

@@ -6,6 +6,7 @@
 from loguru import logger
 from fastmcp import Context
 
+from basic_memory.config import ConfigManager
 from basic_memory.mcp.container import get_container
 from basic_memory.mcp.project_context import get_project_client, resolve_project_and_path
 from basic_memory.mcp.formatting import format_search_results_ascii
@@ -18,6 +19,17 @@
 )
 
 
+def _semantic_search_enabled_for_text_search() -> bool:
+    """Resolve semantic-search enablement in both MCP and CLI invocation paths."""
+    try:
+        return get_container().config.semantic_search_enabled
+    except RuntimeError:
+        # Trigger: MCP container is not initialized (e.g., `bm tool search-notes` direct call).
+        # Why: CLI path still needs the same semantic-default behavior as MCP server path.
+        # Outcome: load config directly and keep text-mode retrieval behavior consistent.
+        return ConfigManager().config.semantic_search_enabled
+
+
 def _format_search_error_response(
     project: str, error_message: str, query: str, search_type: str = "text"
 ) -> str:
@@ -268,7 +280,8 @@ async def search_notes(
     - `search_notes("work-docs", "'exact phrase'")` - Search for exact phrase match
 
     ### Advanced Boolean Searches
-    - `search_notes("my-project", "term1 term2")` - Find content with both terms (implicit AND)
+    - `search_notes("my-project", "term1 term2")` - Strict implicit-AND first; retries with
+      relaxed OR terms only if strict search returns no results
     - `search_notes("my-project", "term1 AND term2")` - Explicit AND search (both terms required)
     - `search_notes("my-project", "term1 OR term2")` - Either term can be present
     - `search_notes("my-project", "term1 NOT term2")` - Include term1 but exclude term2
@@ -282,7 +295,8 @@ async def search_notes(
     ### Search Type Examples
     - `search_notes("my-project", "Meeting", search_type="title")` - Search only in titles
     - `search_notes("work-docs", "docs/meeting-*", search_type="permalink")` - Pattern match permalinks
-    - `search_notes("research", "keyword", search_type="text")` - Full-text search (default)
+    - `search_notes("research", "keyword", search_type="text")` - Text search (default; auto-upgrades
+      to hybrid when semantic search is enabled)
 
     ### Filtering Options
     - `search_notes("my-project", "query", types=["entity"])` - Search only entities
@@ -325,7 +339,8 @@ async def search_notes(
         page: The page number of results to return (default 1)
         page_size: The number of results to return per page (default 10)
         search_type: Type of search to perform, one of:
-                    "text", "title", "permalink", "vector", "semantic", "hybrid" (default: "text")
+                    "text", "title", "permalink", "vector", "semantic", "hybrid" (default: "text";
+                    text mode auto-upgrades to hybrid when semantic search is enabled)
         output_format: "default" returns structured data, "ascii" returns a plain text table,
             "ansi" returns a colorized table for TUI clients.
         types: Optional list of note types to search (e.g., ["note", "person"])
@@ -345,6 +360,7 @@ async def search_notes(
     Examples:
         # Basic text search
         results = await search_notes("project planning")
+        # Plain multi-term text uses strict matching first, then relaxed OR fallback if needed
 
         # Boolean AND search (both terms must be present)
         results = await search_notes("project AND planning")
@@ -424,12 +440,8 @@ async def search_notes(
                 search_query.text = query
                 # Upgrade to hybrid when semantic search is available —
                 # combines FTS keyword matching with vector similarity for better results
-                try:
-                    container = get_container()
-                    if container.config.semantic_search_enabled:
-                        search_query.retrieval_mode = SearchRetrievalMode.HYBRID
-                except RuntimeError:
-                    pass  # Container not initialized (e.g., CLI context) — stay with FTS
+                if _semantic_search_enabled_for_text_search():
+                    search_query.retrieval_mode = SearchRetrievalMode.HYBRID
             elif search_type in ("vector", "semantic"):
                 search_query.text = query
                 search_query.retrieval_mode = SearchRetrievalMode.VECTOR

src/basic_memory/services/project_service.py

@@ -205,9 +205,9 @@ async def add_project(self, name: str, path: str, set_default: bool = False) ->
                         f"Projects cannot share directory trees."
                     )
 
-        if self.config_manager.config.database_backend != DatabaseBackend.POSTGRES:
-            # First add to config file (this will validate the project doesn't exist)
-            self.config_manager.add_project(name, resolved_path)
+        # First add to config file (this validates project uniqueness and keeps
+        # config + database aligned for all backends).
+        self.config_manager.add_project(name, resolved_path)
 
         # Then add to database
         project_data = {
@@ -307,9 +307,8 @@ async def set_default_project(self, name: str) -> None:
         # Update database
         await self.repository.set_as_default(project.id)
 
-        # Update config file only in local mode (cloud mode uses database only)
-        if self.config_manager.config.database_backend != DatabaseBackend.POSTGRES:
-            self.config_manager.set_default_project(name)
+        # Keep config and database default project in sync for all backends.
+        self.config_manager.set_default_project(name)
 
         logger.info(f"Project '{name}' set as default in configuration and database")