feat: merge search_by_metadata into search_notes with optional query

Make `query` optional in `search_notes` so it becomes the single search tool.
Remove `search_by_metadata` entirely — it was unreleased and redundant since
`search_notes` already supports `metadata_filters`, `tags`, and `status`.

- 🔧 `query` param is now `Optional[str] = None`
- 🛡️ Added None guards for project detection and URL resolution
- ✅ Added `no_criteria()` validation with helpful error message
- 🗑️ Deleted `search_by_metadata` tool, imports, tests, and contract entry
- 📝 Updated docs, README, and v0.19.0 release notes

Closes #605

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

Author: phernandez

README.md

@@ -438,8 +438,7 @@ list_directory(dir_name, depth) - Browse directory contents with filtering
 **Search & Discovery:**
 ```
 search(query, page, page_size) - Search across your knowledge base
-search_notes(query, page, page_size, search_type, types, entity_types, after_date, metadata_filters, tags, status, project) - Search with filters
-search_by_metadata(filters, limit, offset, project) - Structured frontmatter search
+search_notes(query, page, page_size, search_type, types, entity_types, after_date, metadata_filters, tags, status, project) - Search with filters (query is optional for filter-only searches)
 ```
 
 **Project Management:**

docs/ai-assistant-guide-extended.md

@@ -1060,9 +1060,9 @@ results = await search_notes(
     project="main"
 )
 
-# Metadata-only search
-results = await search_by_metadata(
-    filters={"type": "spec", "status": "in-progress"},
+# Metadata-only search (no query needed)
+results = await search_notes(
+    metadata_filters={"type": "spec", "status": "in-progress"},
     project="main"
 )
 ```
@@ -2915,18 +2915,11 @@ results = await search_notes(
 )
 ```
 
-**search_by_metadata(filters, limit, offset, project)**
-- Metadata-only search using structured frontmatter
-- Parameters:
-  - `filters` (required): Dict of field -> value (supports $in, $gt/$gte/$lt/$lte, $between)
-  - `limit` (optional): Max results (default: 20)
-  - `offset` (optional): Pagination offset (default: 0)
-  - `project` (required unless default_project_mode): Target project
-- Returns: Matching entities
-- Example:
+**Metadata-only search (via search_notes)**
+- Use `search_notes` with `metadata_filters` and no `query` for metadata-only searches:
 ```python
-results = await search_by_metadata(
-    filters={"type": "spec", "status": "in-progress"},
+results = await search_notes(
+    metadata_filters={"type": "spec", "status": "in-progress"},
     project="main"
 )
 ```

docs/metadata-search.md

@@ -2,14 +2,9 @@
 
 Basic Memory automatically indexes custom frontmatter fields so you can query them with structured filters. Any YAML key in a note's frontmatter beyond the standard set (`title`, `type`, `tags`, `permalink`, `schema`) is stored as `entity_metadata` and becomes searchable.
 
-## Two Ways to Query
+## Querying with `search_notes`
 
-| Tool | Use When |
-|------|----------|
-| `search_by_metadata` | You only need metadata filters (no text query) |
-| `search_notes` | You want to combine a text query with metadata filters |
-
-Both tools accept the same filter syntax.
+`search_notes` is the single search tool for all queries — text, metadata filters, or both. The `query` parameter is optional, so you can use metadata filters alone without passing an empty string.
 
 ## Filter Syntax
 
@@ -88,45 +83,16 @@ This queries the `version` key inside a `schema` object in frontmatter.
 - `$in` and array-contains require non-empty lists.
 - `$between` requires exactly two values `[min, max]`.
 
-## MCP Tools
-
-### `search_by_metadata` — metadata-only search
-
-Searches entities by structured frontmatter metadata without a text query. Results are scoped to entity-level items.
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `filters` | dict | Yes | Metadata filter dictionary (see syntax above) |
-| `project` | string | No | Project to search in (uses default if omitted) |
-| `limit` | int | No | Max results (default 20) |
-| `offset` | int | No | Skip N results for pagination (default 0) |
-
-**Example:**
-
-```python
-# Find all notes with status "in-progress"
-await search_by_metadata({"status": "in-progress"})
-
-# Find high-priority specs in the research project
-await search_by_metadata(
-    {"type": "spec", "priority": {"$in": ["high", "critical"]}},
-    project="research",
-    limit=10,
-)
-```
-
-### `search_notes` with metadata — combined text + metadata
+## MCP Tool — `search_notes`
 
-The `search_notes` tool accepts `metadata_filters`, `tags`, and `status` parameters alongside the text `query`. This lets you combine full-text search with structured filtering.
+`search_notes` is the single search tool for text queries, metadata filters, or both. The `query` parameter is optional.
 
 **Relevant parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `query` | string | Text search query (can be empty when using only filters) |
-| `metadata_filters` | dict | Structured filter dict (same syntax as `search_by_metadata`) |
+| `query` | string (optional) | Text search query. Omit for filter-only searches. |
+| `metadata_filters` | dict | Structured filter dict (see syntax above) |
 | `tags` | list[str] | Convenience shorthand — merged into `metadata_filters["tags"]` |
 | `status` | string | Convenience shorthand — merged into `metadata_filters["status"]` |
 
@@ -138,8 +104,8 @@ The `search_notes` tool accepts `metadata_filters`, `tags`, and `status` paramet
 # Text search filtered by metadata
 await search_notes("authentication", metadata_filters={"status": "draft"})
 
-# Filter-only search (empty query)
-await search_notes("", metadata_filters={"type": "spec"})
+# Filter-only search (no query needed)
+await search_notes(metadata_filters={"type": "spec"})
 
 # Combine text, tags shortcut, and metadata
 await search_notes(
@@ -150,7 +116,7 @@ await search_notes(
 
 # Convenience shortcuts
 await search_notes("planning", status="active")
-await search_notes("", tags=["tier1", "alpha"])
+await search_notes(tags=["tier1", "alpha"])
 ```
 
 ## Tag Search Shortcuts
@@ -260,19 +226,19 @@ confidence: 0.6
 
 ```python
 # Find all in-progress specs
-await search_by_metadata({"status": "in-progress", "type": "spec"})
+await search_notes(metadata_filters={"status": "in-progress", "type": "spec"})
 # → Auth Design
 
 # Find high-confidence specs
-await search_by_metadata({"confidence": {"$gt": 0.7}})
+await search_notes(metadata_filters={"confidence": {"$gt": 0.7}})
 # → Auth Design (confidence: 0.85)
 
 # Find specs with priority high or medium
-await search_by_metadata({"priority": {"$in": ["high", "medium"]}})
+await search_notes(metadata_filters={"priority": {"$in": ["high", "medium"]}})
 # → Auth Design, Search Redesign
 
 # Find specs in a confidence range
-await search_by_metadata({"confidence": {"$between": [0.5, 0.9]}})
+await search_notes(metadata_filters={"confidence": {"$between": [0.5, 0.9]}})
 # → Auth Design (0.85), Search Redesign (0.6)
 
 # Find notes tagged with security

docs/releases/v0.19.0.md

@@ -94,13 +94,16 @@ All MCP tools now support `output_format="json"` for machine-readable responses.
 
 ### Structured Metadata Search
 
-New `search_by_metadata` tool for searching by frontmatter fields.
+`search_notes` now supports filter-only searches — `query` is optional, so you can search
+purely by frontmatter metadata without passing an empty string.
 
 ```
-search_by_metadata({"status": "in-progress"})
-search_by_metadata({"tags": ["security", "oauth"]})
-search_by_metadata({"priority": {"$in": ["high", "critical"]}})
-search_by_metadata({"schema.confidence": {"$gt": 0.7}})
+search_notes(metadata_filters={"status": "in-progress"})
+search_notes(metadata_filters={"tags": ["security", "oauth"]})
+search_notes(metadata_filters={"priority": {"$in": ["high", "critical"]}})
+search_notes(metadata_filters={"schema.confidence": {"$gt": 0.7}})
+search_notes(tags=["security"])  # convenience shorthand
+search_notes(status="draft")     # convenience shorthand
 ```
 
 ### `tag:` Search Shorthand

src/basic_memory/cli/commands/tool.py

@@ -485,7 +485,7 @@ def search_notes(
         with force_routing(local=local, cloud=cloud):
             result = run_with_cleanup(
                 mcp_search(
-                    query=query or "",
+                    query=query or None,
                     project=project,
                     workspace=workspace,
                     search_type=search_type,

src/basic_memory/mcp/tools/__init__.py

@@ -18,7 +18,7 @@
 from basic_memory.mcp.tools.write_note import write_note
 from basic_memory.mcp.tools.cloud_info import cloud_info
 from basic_memory.mcp.tools.release_notes import release_notes
-from basic_memory.mcp.tools.search import search_notes, search_by_metadata
+from basic_memory.mcp.tools.search import search_notes
 from basic_memory.mcp.tools.canvas import canvas
 from basic_memory.mcp.tools.list_directory import list_directory
 from basic_memory.mcp.tools.edit_note import edit_note
@@ -58,7 +58,6 @@
     "schema_infer",
     "schema_validate",
     "search",
-    "search_by_metadata",
     "search_notes",
     # "search_notes_ui",
     "view_note",