fix: default search_notes to entity-level results (#31)

search_notes was returning individual observations and relations as
separate top-level results, wasting the result limit and creating
confusing UX. Default entity_types to ["entity"] when the caller
doesn't specify it — the entity row already indexes full file content,
so no matches are lost. Users can still override with explicit
entity_types=["observation"] etc.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/mcp/tools/search.py

@@ -518,6 +518,13 @@ async def search_notes(
                     "`tags`, `status`, `note_types`, `entity_types`, or `after_date`."
                 )
 
+            # Default to entity-level results to avoid returning individual
+            # observations/relations as separate search results (see issue #31).
+            # Applied after no_criteria() so that the implicit default doesn't
+            # mask a truly empty search request.
+            if not search_query.entity_types:
+                search_query.entity_types = [SearchItemType("entity")]
+
             logger.debug(f"Searching for {search_query} in project {active_project.name}")
             # Import here to avoid circular import (tools → clients → utils → tools)
             from basic_memory.mcp.clients import SearchClient

tests/mcp/test_tool_search.py

@@ -1023,3 +1023,99 @@ def raise_runtime_error():
 
     assert captured_payload["retrieval_mode"] == "fts"
     assert captured_payload["text"] == "test query"
+
+
+# --- Tests for default entity_types (issue #31) --------------------------------
+
+
+@pytest.mark.asyncio
+async def test_search_notes_defaults_entity_types_to_entity(monkeypatch):
+    """search_notes defaults entity_types to ['entity'] when not explicitly provided.
+
+    This prevents individual observations/relations from appearing as separate
+    search results, since the entity row already indexes full file content.
+    """
+    import importlib
+
+    search_mod = importlib.import_module("basic_memory.mcp.tools.search")
+    clients_mod = importlib.import_module("basic_memory.mcp.clients")
+
+    class StubProject:
+        name = "test-project"
+        external_id = "test-external-id"
+
+    @asynccontextmanager
+    async def fake_get_project_client(*args, **kwargs):
+        yield (object(), StubProject())
+
+    async def fake_resolve_project_and_path(
+        client, identifier, project=None, context=None, headers=None
+    ):
+        return StubProject(), identifier, False
+
+    captured_payload: dict = {}
+
+    class MockSearchClient:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        async def search(self, payload, page, page_size):
+            captured_payload.update(payload)
+            return SearchResponse(results=[], current_page=page, page_size=page_size)
+
+    monkeypatch.setattr(search_mod, "get_project_client", fake_get_project_client)
+    monkeypatch.setattr(search_mod, "resolve_project_and_path", fake_resolve_project_and_path)
+    monkeypatch.setattr(clients_mod, "SearchClient", MockSearchClient)
+
+    await search_mod.search_notes(
+        project="test-project",
+        query="test",
+    )
+
+    # entity_types should default to ["entity"]
+    assert captured_payload["entity_types"] == ["entity"]
+
+
+@pytest.mark.asyncio
+async def test_search_notes_explicit_entity_types_overrides_default(monkeypatch):
+    """Explicit entity_types parameter overrides the default ['entity'] filter."""
+    import importlib
+
+    search_mod = importlib.import_module("basic_memory.mcp.tools.search")
+    clients_mod = importlib.import_module("basic_memory.mcp.clients")
+
+    class StubProject:
+        name = "test-project"
+        external_id = "test-external-id"
+
+    @asynccontextmanager
+    async def fake_get_project_client(*args, **kwargs):
+        yield (object(), StubProject())
+
+    async def fake_resolve_project_and_path(
+        client, identifier, project=None, context=None, headers=None
+    ):
+        return StubProject(), identifier, False
+
+    captured_payload: dict = {}
+
+    class MockSearchClient:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        async def search(self, payload, page, page_size):
+            captured_payload.update(payload)
+            return SearchResponse(results=[], current_page=page, page_size=page_size)
+
+    monkeypatch.setattr(search_mod, "get_project_client", fake_get_project_client)
+    monkeypatch.setattr(search_mod, "resolve_project_and_path", fake_resolve_project_and_path)
+    monkeypatch.setattr(clients_mod, "SearchClient", MockSearchClient)
+
+    await search_mod.search_notes(
+        project="test-project",
+        query="test",
+        entity_types=["observation"],
+    )
+
+    # Explicit entity_types should be used, not the default
+    assert captured_payload["entity_types"] == ["observation"]