fix(mcp): use fixed lookup size for read_note title fallback

The title-search fallback in read_note used the caller's page_size for
the lookup window, so a small suggestion page could let a higher-ranked
fuzzy title displace the exact title match: with notes "Foo Bar Foo
Bar" and "Foo Bar", read_note("Foo Bar", page_size=1) returned
not-found/suggestions even though the note exists. The page=1 pin from
9e8436f had the same problem on the page_size axis.

Pin the title lookup to a fixed _TITLE_LOOKUP_PAGE_SIZE window; caller
page/page_size keep applying only to the text-search suggestion path.
Updates the docstring and decision-point comment to cover both axes,
and adds a regression test for the small-page_size displacement.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/mcp/tools/read_note.py

@@ -21,6 +21,11 @@
 from basic_memory.schemas.memory import memory_url_path
 from basic_memory.utils import validate_project_path
 
+# The title-match fallback exists to find THE note by exact title, so it always
+# scans a fixed-size first page of title results instead of the caller's
+# page/page_size (which apply only to the text-search suggestion listing).
+_TITLE_LOOKUP_PAGE_SIZE = 10
+
 
 def _is_exact_title_match(identifier: str, title: str) -> bool:
     """Return True when identifier exactly matches a title (case-insensitive)."""
@@ -118,8 +123,8 @@ async def read_note(
         page: Page of fallback-search results to use when the identifier does not
             resolve to a note directly (default: 1). A direct or exact-title match
             always returns the full note content — page/page_size never chunk the
-            note itself, and the title-match lookup always checks the first page
-            of title results regardless of this value.
+            note itself, and the title-match lookup always checks a fixed-size
+            first page of title results regardless of page or page_size.
         page_size: Number of fallback-search results per page (default: 10). When no
             match is found, this caps how many related-note suggestions are listed.
         output_format: "text" returns markdown content or guidance text.
@@ -296,17 +301,21 @@ async def _search_candidates(
                 # Trigger: title_only — the title search exists to find THE note by
                 #          exact title, not to page through suggestions.
                 # Why: paginating it by the caller's page would skip an exact match
-                #      sitting on page 1 (read_note("Exact Title", page=2)) and
-                #      return unrelated suggestions instead of the note.
-                # Outcome: title lookup is pinned to page 1; caller paging applies
-                #          only to the text-search suggestion listing.
+                #      sitting on page 1 (read_note("Exact Title", page=2)), and a
+                #      small caller page_size could let a higher-ranked fuzzy title
+                #      displace the exact match out of the lookup window
+                #      (read_note("Foo Bar", page_size=1) when "Foo Bar Foo Bar"
+                #      ranks first) — both returning suggestions instead of the note.
+                # Outcome: title lookup is pinned to page 1 with a fixed lookup
+                #          size; caller page/page_size apply only to the
+                #          text-search suggestion listing.
                 response = await search_notes(
                     project=active_project.name,
                     project_id=active_project.external_id,
                     query=identifier_text,
                     search_type=search_type,
                     page=1 if title_only else page,
-                    page_size=page_size,
+                    page_size=_TITLE_LOOKUP_PAGE_SIZE if title_only else page_size,
                     output_format="json",
                     context=context,
                 )

tests/mcp/test_tool_read_note.py

@@ -176,9 +176,10 @@ async def resolve_entity(self, identifier: str, *, strict: bool = False) -> str:
 
     result = await read_note("missing-note", project=test_project.name, page=2, page_size=3)
 
-    # Title lookup is pinned to page 1 (it exists to find THE note by exact
-    # title); caller paging applies only to the text-search suggestions.
-    assert captured_pages == [("title", 1, 3), ("text", 2, 3)]
+    # Title lookup is pinned to page 1 with a fixed lookup size (it exists to
+    # find THE note by exact title); caller page/page_size apply only to the
+    # text-search suggestions.
+    assert captured_pages == [("title", 1, 10), ("text", 2, 3)]
     assert "Note Not Found" in result
 
 
@@ -219,6 +220,50 @@ async def resolve_entity(self, identifier: str, *, strict: bool = False) -> str:
     assert "paged title content" in content
 
 
+@pytest.mark.asyncio
+async def test_read_note_title_fallback_finds_exact_match_with_small_page_size(
+    monkeypatch, app, test_project
+):
+    """An exact title match is returned even when the caller asks for a tiny page_size.
+
+    The title-match lookup uses a fixed lookup size; without it, a higher-ranked
+    fuzzy title ("Foo Bar Foo Bar") would displace the exact title ("Foo Bar")
+    out of a page_size=1 window and read_note("Foo Bar", page_size=1) would
+    return suggestions instead of the note.
+    """
+    await write_note(
+        project=test_project.name,
+        title="Foo Bar Foo Bar",
+        directory="test",
+        content="fuzzy decoy content",
+    )
+    await write_note(
+        project=test_project.name,
+        title="Foo Bar",
+        directory="test",
+        content="exact title content",
+    )
+
+    import importlib
+    from basic_memory.schemas.memory import memory_url_path
+
+    clients_mod = importlib.import_module("basic_memory.mcp.clients")
+    OriginalKnowledgeClient = clients_mod.KnowledgeClient
+    direct_identifier = memory_url_path("Foo Bar")
+
+    class SelectiveKnowledgeClient(OriginalKnowledgeClient):
+        async def resolve_entity(self, identifier: str, *, strict: bool = False) -> str:
+            # Fail on the direct identifier to force fallback to title search
+            if identifier == direct_identifier:
+                raise RuntimeError("force direct lookup failure")
+            return await super().resolve_entity(identifier, strict=strict)
+
+    monkeypatch.setattr(clients_mod, "KnowledgeClient", SelectiveKnowledgeClient)
+
+    content = await read_note("Foo Bar", project=test_project.name, page_size=1)
+    assert "exact title content" in content
+
+
 @pytest.mark.asyncio
 async def test_read_note_related_results_list_full_search_page(monkeypatch, app, test_project):
     """Suggestions list the whole returned search page instead of a hardcoded cap of 5."""