fix: three cloud-testing bugs (#640, #641, #642)

🔧 #640 — LinkResolver selects worst match instead of best
Replace `min(results, key=lambda x: x.score)` with `results[0]`.
Both SQLite and Postgres return results sorted best-first in SQL,
so using `results[0]` is backend-agnostic and correct.

🔧 #641 — search_notes output_format="text" returns raw Pydantic model
Add `_format_search_markdown()` that formats SearchResponse as readable
markdown with title, permalink, score, and matched snippet per result.
Update prompts to use `output_format="json"` since they need structured
data for result counting and branching logic.

🔧 #642 — metadata_filters with `note_type` key returns empty results
Add `_METADATA_KEY_ALIASES` mapping at the tool level that aliases
`note_type` → `type` before passing metadata_filters to the search query.
The frontmatter field is `type`, not `note_type`.

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

Author: phernandez

src/basic_memory/mcp/prompts/continue_conversation.py

@@ -13,7 +13,6 @@
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.recent_activity import recent_activity
 from basic_memory.mcp.tools.search import search_notes
-from basic_memory.schemas.search import SearchResponse
 
 
 @mcp.prompt(
@@ -42,15 +41,12 @@ async def continue_conversation(
     logger.info(f"Continuing session, topic: {topic}, timeframe: {timeframe}")
 
     if topic:
-        # Search for the topic using the search tool directly
-        result = await search_notes(query=topic, after_date=timeframe)
+        # Use json format to get structured data for result counting and branching
+        result = await search_notes(query=topic, after_date=timeframe, output_format="json")
 
-        if isinstance(result, SearchResponse):
-            context_text = _format_continuation_results(result, topic)
-            result_count = len(result.results)
-        elif isinstance(result, dict):
+        if isinstance(result, dict):
             results = result.get("results", [])
-            context_text = str(result)
+            context_text = _format_continuation_results(results, topic)
             result_count = len(results)
         else:
             # Error string
@@ -111,23 +107,24 @@ async def continue_conversation(
     return prompt
 
 
-def _format_continuation_results(result: SearchResponse, topic: str) -> str:
-    """Format search results for conversation continuation context."""
-    if not result.results:
+def _format_continuation_results(results: list[dict], topic: str) -> str:
+    """Format search result dicts for conversation continuation context."""
+    if not results:
         return f"No previous context found for '{topic}'."
 
     lines = [f"## Previous Context for '{topic}'\n"]
 
-    for item in result.results:
-        title = item.title or "Untitled"
-        permalink = item.permalink or ""
+    for item in results:
+        title = item.get("title", "Untitled")
+        permalink = item.get("permalink", "")
 
         lines.append(f"### {title}")
         if permalink:
             lines.append(f"permalink: {permalink}")
             lines.append(f'Read with: `read_note("{permalink}")`')
-        if item.content:
-            content = item.content[:300] + "..." if len(item.content) > 300 else item.content
+        content = item.get("content")
+        if content:
+            content = content[:300] + "..." if len(content) > 300 else content
             lines.append(f"\n{content}")
         lines.append("")
 

src/basic_memory/mcp/prompts/search.py

@@ -11,7 +11,6 @@
 
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.search import search_notes
-from basic_memory.schemas.search import SearchResponse
 
 
 @mcp.prompt(
@@ -39,18 +38,14 @@ async def search_prompt(
     """
     logger.info(f"Searching knowledge base, query: {query}, timeframe: {timeframe}")
 
-    # Call the search tool directly — it returns SearchResponse, dict, or error string
-    result = await search_notes(query=query, after_date=timeframe)
+    # Use json format to get structured data for result counting and formatting
+    result = await search_notes(query=query, after_date=timeframe, output_format="json")
 
     # Format the tool output into a prompt with guidance
-    if isinstance(result, SearchResponse):
-        result_count = len(result.results)
-        result_text = _format_search_results(result, query)
-    elif isinstance(result, dict):
-        # json output format
+    if isinstance(result, dict):
         results = result.get("results", [])
         result_count = len(results)
-        result_text = str(result)
+        result_text = _format_search_results(results, query)
     else:
         # Error string from search tool
         result_count = 0
@@ -76,28 +71,27 @@ async def search_prompt(
     """)
 
 
-def _format_search_results(result: SearchResponse, query: str) -> str:
-    """Format SearchResponse into readable markdown."""
-    if not result.results:
+def _format_search_results(results: list[dict], query: str) -> str:
+    """Format search result dicts into readable markdown."""
+    if not results:
         return f"No results found for '{query}'."
 
-    lines = [f"Found {len(result.results)} results:\n"]
+    lines = [f"Found {len(results)} results:\n"]
 
-    for item in result.results:
-        title = item.title or "Untitled"
-        permalink = item.permalink or ""
-        score = f" (score: {item.score:.2f})" if item.score else ""
+    for item in results:
+        title = item.get("title", "Untitled")
+        permalink = item.get("permalink", "")
+        score = item.get("score")
+        score_text = f" (score: {score:.2f})" if score else ""
 
-        lines.append(f"- **{title}**{score}")
+        lines.append(f"- **{title}**{score_text}")
         if permalink:
             lines.append(f"  permalink: {permalink}")
-        if item.content:
+        content = item.get("content")
+        if content:
             # Truncate content snippet
-            content = item.content[:200] + "..." if len(item.content) > 200 else item.content
+            content = content[:200] + "..." if len(content) > 200 else content
             lines.append(f"  {content}")
         lines.append("")
 
-    if result.has_more:
-        lines.append("*More results available. Use page=2 to see next page.*")
-
     return "\n".join(lines)

src/basic_memory/mcp/tools/search.py

@@ -251,6 +251,46 @@ def _format_search_error_response(
 - **Patterns**: `tag:example`, `category:observation`"""
 
 
+def _format_search_markdown(result: SearchResponse, project: str, query: str | None) -> str:
+    """Format SearchResponse as compact markdown text.
+
+    Produces a human-readable markdown representation suitable for LLM
+    consumption when structured data isn't needed.
+    """
+    if not result.results:
+        return f"No results found for '{query or ''}' in project '{project}'."
+
+    parts = []
+
+    # --- Header ---
+    if query:
+        parts.append(f"# Search Results: {query}")
+    else:
+        parts.append("# Search Results")
+    parts.append(f"*project: {project}*")
+    parts.append("")
+
+    # --- Result blocks ---
+    for r in result.results:
+        parts.append(f"### {r.title}")
+        parts.append(f"- permalink: {r.permalink}")
+        parts.append(f"- score: {r.score:.4f}")
+        if r.matched_chunk:
+            parts.append(f"- match: {r.matched_chunk[:200]}")
+        parts.append("")
+
+    # --- Footer with pagination ---
+    parts.append("---")
+    count = len(result.results)
+    parts.append(
+        f"*{count} result{'s' if count != 1 else ''}"
+        f" | page {result.current_page}, page_size {result.page_size}"
+        f"{' | more available' if result.has_more else ''}*"
+    )
+
+    return "\n".join(parts)
+
+
 @mcp.tool(
     description="Search across all content in the knowledge base with advanced syntax support.",
     # TODO: re-enable once MCP client rendering is working
@@ -273,7 +313,7 @@ async def search_notes(
     status: Optional[str] = None,
     min_similarity: Optional[float] = None,
     context: Context | None = None,
-) -> SearchResponse | dict | str:
+) -> dict | str:
     """Search across all content in the knowledge base with comprehensive syntax support.
 
     This tool searches the knowledge base using full-text search, pattern matching,
@@ -373,7 +413,8 @@ async def search_notes(
         context: Optional FastMCP context for performance caching.
 
     Returns:
-        SearchResponse with results and pagination info, or helpful error guidance if search fails
+        Formatted markdown text (output_format="text"), dict (output_format="json"),
+        or helpful error guidance string if search fails
 
     Examples:
         # Basic text search
@@ -519,6 +560,13 @@ async def search_notes(
             if after_date:
                 search_query.after_date = after_date
             if metadata_filters:
+                # Alias common column/model names to their frontmatter key equivalents.
+                # Users often pass "note_type" (the entity model column) when the
+                # frontmatter field is actually "type".
+                _METADATA_KEY_ALIASES = {"note_type": "type"}
+                metadata_filters = {
+                    _METADATA_KEY_ALIASES.get(k, k): v for k, v in metadata_filters.items()
+                }
                 search_query.metadata_filters = metadata_filters
             if tags:
                 search_query.tags = tags
@@ -565,7 +613,7 @@ async def search_notes(
             if output_format == "json":
                 return result.model_dump(mode="json", exclude_none=True)
 
-            return result
+            return _format_search_markdown(result, active_project.name, query)
 
         except Exception as e:
             logger.error(

src/basic_memory/services/link_resolver.py

@@ -301,8 +301,10 @@ async def _resolve_in_project(
             )
 
             if results:
-                # Look for best match
-                best_match = min(results, key=lambda x: x.score)  # pyright: ignore
+                # Both SQLite and Postgres return results sorted best-first in SQL
+                # (SQLite: ORDER BY score ASC for negative BM25, Postgres: ORDER BY score DESC
+                # for positive ts_rank). Using results[0] is backend-agnostic and correct.
+                best_match = results[0]
                 logger.trace(
                     f"Selected best match from {len(results)} results: {best_match.permalink}"
                 )

test-int/mcp/test_delete_note_integration.py

@@ -105,11 +105,8 @@ async def test_delete_note_by_permalink(mcp_server, app, test_project):
             },
         )
 
-        # Should have no results
-        assert (
-            '"results": []' in search_result.content[0].text
-            or '"results":[]' in search_result.content[0].text
-        )
+        # Default text format returns "No results found" when empty
+        assert "No results found" in search_result.content[0].text
 
 
 @pytest.mark.asyncio
@@ -387,11 +384,8 @@ async def test_delete_multiple_notes_sequentially(mcp_server, app, test_project)
             },
         )
 
-        # Should have no results
-        assert (
-            '"results": []' in search_result.content[0].text
-            or '"results":[]' in search_result.content[0].text
-        )
+        # Default text format returns "No results found" when empty
+        assert "No results found" in search_result.content[0].text
 
 
 @pytest.mark.asyncio

test-int/mcp/test_search_integration.py

@@ -362,9 +362,9 @@ async def test_search_pagination(mcp_server, app, test_project):
         )
 
         result_text = search_result.content[0].text
-        # Should contain 5 results and pagination info
-        assert '"current_page":1' in result_text
-        assert '"page_size":5' in result_text
+        # Text format includes pagination info in footer
+        assert "page 1" in result_text
+        assert "page_size 5" in result_text
 
         # Search page 2
         search_result = await client.call_tool(
@@ -378,7 +378,7 @@ async def test_search_pagination(mcp_server, app, test_project):
         )
 
         result_text = search_result.content[0].text
-        assert '"current_page":2' in result_text
+        assert "page 2" in result_text
 
 
 @pytest.mark.asyncio
@@ -407,8 +407,9 @@ async def test_search_no_results(mcp_server, app, test_project):
             },
         )
 
+        # Default text format returns "No results found" when empty
         result_text = search_result.content[0].text
-        assert '"results": []' in result_text or '"results":[]' in result_text
+        assert "No results found" in result_text
 
 
 @pytest.mark.asyncio