Bug: Tag search syntax 'tag:tagname' returns empty results

[phernandez]

Summary

Tag-specific search syntax tag:tagname returns empty results even when notes with those tags exist in the knowledge base.

Severity

Medium - Reduces tag-based discoverability but text search workaround is available

Reproduction Steps

1. Create notes with tags (e.g., tags: ["tier1", "test"])
2. Verify notes exist via text search: search_notes(query="tier1") ✓ Returns results
3. Execute search with tag syntax: search_notes(query="tag:tier1")
4. Observe empty results: {"results":[],"current_page":1,"page_size":10}

Expected Behavior

search_notes(query="tag:tier1") should return all notes that have "tier1" in their tags array

Actual Behavior

Query returns empty results even though 3+ notes with the tag exist

Test Evidence

# Created 3 notes with tier1 tag:
# - Test Note Basic Functionality
# - Test Note Unicode 📝✨🚀  
# - Test Root Folder Note

# Text search works:
search_notes(query="tier1", project="test-project")
# Returns results ✓

# Tag search fails:
search_notes(query="tag:tier1", project="test-project")
# Returns [] ✗

Environment

• Version: 0.15.0
• Platform: macOS Darwin 24.6.0
• Discovered during: Live comprehensive testing session 2025-10-13
• Test project: basic-memory-testing-2025-10-13-073211

Impact

• User Experience: Medium - Reduces tag-based discoverability
• Functionality: Text search workaround available (see below)
• Data Integrity: No impact
• Production Blocking: No

Workaround

Use text search for tag names instead of tag-specific syntax:

# Instead of: search_notes(query="tag:tier1", project="my-project")
# Use: search_notes(query="tier1", project="my-project")

Recommended Fix

Review tag search query parsing in the search endpoint. Check if the tag: prefix is being stripped/parsed correctly before querying the tags field in the database.

Related Code Locations

• Likely: src/basic_memory/api/routers/search.py
• Database: SQLite FTS5 configuration for tags field
• Schema: Tag indexing in src/basic_memory/models/

Additional Context

• Discovered during comprehensive v0.15.0 testing
• Part of 19-test suite with 95% pass rate
• Does not block production deployment
• All other search functionality working correctly
• Documentation: Test project contains full bug report at bug-reports/Bug Report - Tag Search Not Working.md

[claude]

Claude finished @phernandez's task —— View job

---

Issue #354 Triage Complete ✓

Task List

• Review search implementation code
• Search for duplicate issues
• Classify issue type, priority, component, and complexity
• Add appropriate labels
• Provide triage analysis
• Investigate root cause and propose fix

---

Triage Analysis

Classification:

• Type: Enhancement (not a bug - feature doesn't exist)
• Priority: Low - Workaround is the intended behavior
• Component: Database/Search
• Complexity: Medium
• Label Added: bug (though this is really an enhancement request)

Status: No duplicates found

---

Root Cause

The tag:tagname syntax is not a supported feature in Basic Memory. When you search for tag:tier1, the system treats it as a literal text search. The colon (:) is identified as a special character in _prepare_search_term() (search_repository.py:296), causing the entire string to be quoted for FTS5 safety. This results in searching for the literal string "tag:tier1" in the content.

Current Design

Tags ARE properly indexed (search_service.py:242-245) and searchable - they're added to content_stems as plain text. The existing tests (test_search_service.py:504-554) confirm the intended behavior:

# This is the correct way to search by tags:
search_notes(query="tier1", project="my-project")  # ✓ Works

# This syntax is not supported:
search_notes(query="tag:tier1", project="my-project")  # ✗ Not implemented

---

Recommendation

This issue is actually a feature request, not a bug. The "workaround" mentioned in the issue report is actually the intended behavior. However, implementing tag: prefix syntax could improve user experience.

Two possible paths:

1. Document current behavior (Low effort)

   • Update search documentation to clarify that tag search uses plain text: "tagname"
   • Add examples showing how to search by tags
   • Close this issue as "working as intended"

2. Implement special syntax (Medium effort)

   • Parse search queries for tag: prefix before FTS5 processing
   • Extract tag qualifiers and build appropriate WHERE clauses
   • Update search_repository.py to handle qualified searches
   • Add tests for the new syntax
   • Document the new feature

My suggestion: Path 1 (documentation) makes the most sense, since the current behavior already works well and is simpler. The tag: syntax doesn't provide any functionality advantage over plain text search - it's just a different interface to the same underlying search.

What would you like to do? I can implement either approach.

---

[phernandez]

Triage update: this works now. The tag: shorthand was implemented in #535 (service layer), with MCP-level parsing and Postgres support following, so search_notes(query="tag:tier1") maps to a structured tags filter instead of falling through to literal FTS text. Multiple tags (tag:a,b, tag:a AND tag:b) and mixed free-text + tag queries are covered by tests in tests/services/test_search_service.py and tests/mcp/test_tool_search.py, including the exact tag:tier1 example from this issue.

Closing as fixed — please reopen if you still see empty results on a current release.