docs: update AI assistant guides for v0.19.0, fix multi-tag search parsing

Update both the compact and extended AI assistant guides with v0.19.0 changes:
- 📝 write_note overwrite guard: callout, edit_note examples, overwrite=True
- 🔍 Expanded search section: all search types, tag: shorthand, filter-only
  searches, metadata_filters operators, min_similarity
- ⚠️ "Note already exists" error handling pattern
- 📋 Tool quick reference: updated params, added list_workspaces
- 🔗 memory:// URL: added cross-project format
- ✏️ Best practice: prefer edit_note for updates

Fix tag: shorthand parsing to handle multiple tags anywhere in the query.
Old parser only handled queries starting with "tag:" and broke on
"tag:coffee AND tag:brewing". New parser uses re.findall to extract all
tag:value tokens, strips boolean connectors, and preserves remaining text.

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

Author: phernandez

docs/ai-assistant-guide-extended.md

@@ -427,6 +427,8 @@ await write_note(
 )
 ```
 
+> **Important**: `write_note` errors if the note already exists. Use `edit_note` for incremental changes, or pass `overwrite=True` to replace.
+
 **Well-structured note**:
 
 ```python
@@ -760,6 +762,9 @@ notes = await read_note(
     identifier="memory://specs/*",
     project="main"
 )
+
+# Cross-project URL (auto-routes to the correct project)
+note = await read_note(identifier="memory://research/specs/api-design")
 ```
 
 ```python
@@ -1069,7 +1074,10 @@ results = await search_notes(
 
 ### Search Types
 
-**Text search (default)**:
+Available types: `"text"`, `"title"`, `"permalink"`, `"vector"`/`"semantic"`, `"hybrid"`.
+Default is `"hybrid"` when semantic search is enabled, `"text"` otherwise.
+
+**Text search**:
 
 ```python
 # Full-text search across all content
@@ -1080,17 +1088,52 @@ results = await search_notes(
 )
 ```
 
-**Semantic search**:
+**Title and permalink search**:
+
+```python
+# Search by title only
+results = await search_notes(query="API Design", search_type="title", project="main")
+
+# Search by permalink
+results = await search_notes(query="specs/api-design", search_type="permalink", project="main")
+```
+
+**Semantic/vector search**:
 
 ```python
 # Semantic/vector search (if enabled)
+results = await search_notes(
+    query="user login security",
+    search_type="semantic",  # or "vector"
+    project="main"
+)
+
+# Override similarity threshold
 results = await search_notes(
     query="user login security",
     search_type="semantic",
+    min_similarity=0.5,
     project="main"
 )
 ```
 
+**Hybrid search** (combines text + semantic):
+
+```python
+results = await search_notes(
+    query="authentication best practices",
+    search_type="hybrid",
+    project="main"
+)
+```
+
+**Tag shorthand in query**:
+
+```python
+# Use tag: prefix as shorthand
+results = await search_notes(query="tag:security", project="main")
+```
+
 ### Search Response
 
 **Result structure**:
@@ -2161,6 +2204,31 @@ active_project = projects[0]["name"]
 results = await search_notes(query="test", project=active_project)
 ```
 
+### Note Already Exists
+
+**Error**: `write_note` called for a note that already exists
+
+**Solution**:
+
+```python
+# Preferred: use edit_note for incremental updates
+await edit_note(
+    identifier="Existing Topic",
+    operation="append",
+    content="\n- [update] new information",
+    project="main"
+)
+
+# Alternative: replace the entire note
+await write_note(
+    title="Existing Topic",
+    content="# Existing Topic\n...",
+    folder="notes",
+    overwrite=True,
+    project="main"
+)
+```
+
 ### Entity Not Found
 
 **Error**: Note doesn't exist
@@ -2716,14 +2784,15 @@ await write_note(
 
 ### Content Management
 
-**write_note(title, content, folder, tags, note_type, project)**
-- Create or update markdown notes
+**write_note(title, content, folder, tags, note_type, overwrite, project)**
+- Create new markdown notes (errors if note already exists unless overwrite=True)
 - Parameters:
   - `title` (required): Note title
   - `content` (required): Markdown content
   - `folder` (required): Destination folder
   - `tags` (optional): List of tags
   - `note_type` (optional): Type of note (stored in frontmatter). Can be "note", "person", "meeting", "guide", etc.
+  - `overwrite` (optional): Set to True to replace an existing note (default: error if exists)
   - `project` (required unless default_project_mode): Target project
 - Returns: Created/updated entity with permalink
 - Example:
@@ -2890,19 +2959,20 @@ contents = await list_directory(
 
 ### Search & Discovery
 
-**search_notes(query, page, page_size, search_type, types, entity_types, after_date, metadata_filters, tags, status, project)**
+**search_notes(query, page, page_size, search_type, types, entity_types, after_date, metadata_filters, tags, status, min_similarity, project)**
 - Search across knowledge base
 - Parameters:
-  - `query` (required): Search query
+  - `query` (optional): Search query (not required for filter-only searches)
   - `page` (optional): Page number (default: 1)
   - `page_size` (optional): Results per page (default: 10)
-  - `search_type` (optional): "text" or "semantic"
+  - `search_type` (optional): "text", "title", "permalink", "vector"/"semantic", "hybrid" (default: "hybrid" when semantic enabled, "text" otherwise)
   - `types` (optional): Entity type filter
   - `entity_types` (optional): Observation category filter
   - `after_date` (optional): Date filter (ISO format)
-  - `metadata_filters` (optional): Structured frontmatter filters (dict)
-  - `tags` (optional): Frontmatter tags filter (list)
+  - `metadata_filters` (optional): Structured frontmatter filters (dict, supports `$in`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` operators)
+  - `tags` (optional): Frontmatter tags filter (list); also available via `tag:` query shorthand
   - `status` (optional): Frontmatter status filter (string)
+  - `min_similarity` (optional): Override similarity threshold for vector/hybrid search
   - `project` (required unless default_project_mode): Target project
 - Returns: Matching entities with scores
 - Example:
@@ -2971,6 +3041,15 @@ await delete_project(project_name="old-project")
 status = await sync_status(project="main")
 ```
 
+**list_workspaces()**
+- List available workspaces (cloud)
+- Parameters: None
+- Returns: List of workspaces with metadata
+- Example:
+```python
+workspaces = await list_workspaces()
+```
+
 ### Visualization
 
 **canvas(nodes, edges, title, folder, project)**
@@ -3239,8 +3318,8 @@ await edit_note(
     project="main"
 )
 
-# Avoid: Complete rewrite
-# (unless necessary for major restructuring)
+# When full rewrite is needed, use overwrite=True
+await write_note(title="Note", content="...", folder="notes", overwrite=True)
 ```
 
 ### 14. Tagging Strategy

src/basic_memory/mcp/resources/ai_assistant_guide.md

@@ -57,6 +57,16 @@ await write_note(
 )
 ```
 
+> **Important**: `write_note` errors if the note already exists. Use `edit_note` for incremental changes, or pass `overwrite=True` to replace.
+
+```python
+# Preferred: update an existing note incrementally
+await edit_note(identifier="Topic", operation="append", content="\n- [category] new fact")
+
+# Alternative: replace the entire note
+await write_note(title="Topic", content="...", folder="notes", overwrite=True)
+```
+
 ### Reading Knowledge
 
 ```python
@@ -70,11 +80,27 @@ content = await read_note("memory://folder/topic", project="main")
 ### Searching
 
 ```python
+# Basic text search
+results = await search_notes(query="authentication", project="main")
+
+# Search types: "text" (default), "title", "permalink", "vector"/"semantic", "hybrid"
+# Default is "hybrid" when semantic search is enabled, "text" otherwise
+results = await search_notes(query="auth flow", search_type="hybrid")
+
+# Tag shorthand in query (multiple tags: "tag:x AND tag:y" or "tag:x tag:y")
+results = await search_notes(query="tag:security")
+results = await search_notes(query="tag:coffee AND tag:brewing")
+
+# Filter-only search (no query needed)
+results = await search_notes(tags=["security", "auth"], status="active")
+
+# Metadata filters with operators: $in, $gt, $gte, $lt, $lte, $between
 results = await search_notes(
-    query="authentication",
-    project="main",
-    page_size=10
+    metadata_filters={"priority": {"$in": ["high", "critical"]}}
 )
+
+# Override similarity threshold for vector/hybrid search
+results = await search_notes(query="auth", search_type="hybrid", min_similarity=0.5)
 ```
 
 ### Building Context
@@ -162,6 +188,8 @@ activity = await recent_activity(project="main")
 - 2-3 relations per note
 - Meaningful categories and relation types
 
+**Prefer `edit_note` for updates** — use `write_note` only for new notes.
+
 **Search before creating:**
 ```python
 # Find existing entities to reference
@@ -201,6 +229,14 @@ except:
     results = await search_notes(query="test", project=projects[0].name)
 ```
 
+**Note already exists:**
+```python
+# write_note returns an error if the note exists — use edit_note or overwrite
+await edit_note(identifier="Existing Topic", operation="append", content="\n- [update] new info")
+# Or replace entirely:
+await write_note(title="Existing Topic", content="...", folder="notes", overwrite=True)
+```
+
 **Forward references:**
 ```python
 # Check response for unresolved relations
@@ -256,20 +292,22 @@ context = await build_context(url=f"memory://{results[0].permalink}", project="m
 
 | Tool | Purpose | Key Params |
 |------|---------|------------|
-| `write_note` | Create/update | title, content, folder, project |
+| `write_note` | Create new | title, content, folder, project, overwrite |
 | `read_note` | Read content | identifier, project |
 | `edit_note` | Modify existing | identifier, operation, content, project |
-| `search_notes` | Find notes | query, project |
+| `search_notes` | Find notes | query, search_type, tags, metadata_filters, project |
 | `build_context` | Graph traversal | url, depth, project |
 | `recent_activity` | Recent changes | timeframe, project |
 | `list_memory_projects` | Show projects | (none) |
+| `list_workspaces` | Show workspaces | (none) |
 
 ## memory:// URL Format
 
 - `memory://title` - By title
 - `memory://folder/title` - By folder + title
 - `memory://permalink` - By permalink
 - `memory://folder/*` - All in folder
+- `memory://project-name/folder/title` - Cross-project (auto-routes to the correct project)
 
 For full documentation: https://docs.basicmemory.com
 

src/basic_memory/mcp/tools/search.py

@@ -440,14 +440,20 @@ async def search_notes(
     entity_types = entity_types or []
 
     # Parse tag:<value> shorthand at tool level so it works with all search modes.
+    # Handles "tag:security", "tag:coffee tag:brewing", "tag:coffee AND tag:brewing".
     # Without this, hybrid/vector modes fail because they require non-empty text,
     # but the service-layer tag: parser clears the text after the mode is set.
-    if query and query.strip().lower().startswith("tag:"):
-        tag_values = [t for t in re.split(r"[,\s]+", query.strip()[4:].strip()) if t]
+    if query and "tag:" in query.lower():
+        # Extract tag values, splitting comma-separated lists (e.g. "tag:coffee,brewing")
+        raw_values = re.findall(r"tag:(\S+)", query, flags=re.IGNORECASE)
+        tag_values = [v for raw in raw_values for v in raw.split(",") if v]
         if tag_values:
             # Merge with any explicitly provided tags
             tags = list(set((tags or []) + tag_values))
-            query = None
+            # Remove tag: tokens and boolean connectors, keep remaining text as query
+            remainder = re.sub(r"tag:\S+", "", query, flags=re.IGNORECASE)
+            remainder = re.sub(r"\b(AND|OR|NOT)\b", "", remainder).strip()
+            query = remainder or None
 
     # Detect project from memory URL prefix before routing
     if project is None and query is not None:

tests/mcp/test_tool_search.py

@@ -1202,3 +1202,88 @@ async def search(self, payload, page, page_size):
     assert isinstance(result, SearchResponse)
     assert set(captured_payload["tags"]) == {"security", "oauth"}
     assert captured_payload.get("text") is None
+
+
+@pytest.mark.asyncio
+async def test_search_notes_multiple_tag_prefixes(monkeypatch):
+    """query='tag:coffee AND tag:brewing' should extract both tags."""
+    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())
+
+    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(clients_mod, "SearchClient", MockSearchClient)
+
+    result = await search_mod.search_notes(
+        project="test-project",
+        query="tag:coffee AND tag:brewing",
+    )
+
+    assert isinstance(result, SearchResponse)
+    assert set(captured_payload["tags"]) == {"coffee", "brewing"}
+    # Boolean connector AND should be stripped, leaving no text query
+    assert captured_payload.get("text") is None
+
+
+@pytest.mark.asyncio
+async def test_search_notes_tag_prefix_with_remaining_text(monkeypatch):
+    """query='authentication tag:security' should keep text and extract tag."""
+    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())
+
+    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)
+
+    # Remaining text query triggers resolve_project_and_path, so stub it too
+    async def fake_resolve(client, query, project, context):
+        return project, query, False
+
+    monkeypatch.setattr(search_mod, "get_project_client", fake_get_project_client)
+    monkeypatch.setattr(search_mod, "resolve_project_and_path", fake_resolve)
+    monkeypatch.setattr(clients_mod, "SearchClient", MockSearchClient)
+
+    result = await search_mod.search_notes(
+        project="test-project",
+        query="authentication tag:security",
+    )
+
+    assert isinstance(result, SearchResponse)
+    assert captured_payload["tags"] == ["security"]
+    # Remaining text should be preserved as the query
+    assert captured_payload["text"] == "authentication"