claude-mem/test-results/test-22-decisions-endpoint.json

[{"type":"text","text":"## Apply semantic naming principle to clarify FTS5 as degraded fallback\n*Source: claude-mem://observation/10742*\n\n**Rename FTS5 functions to explicitly communicate fallback status per CLAUDE.md semantic naming guidelines.**\n\nThe fix requires applying the semantic naming principle from CLAUDE.md to all FTS5-related code. Instead of ambiguous names like `escapeFTS5()` that hide architectural intent, functions should use verbose descriptive names like `escapeFTS5_fallback_for_missing_chroma()` that explicitly communicate FTS5's role as a degraded fallback mode for users without Python/uvx/Chroma dependencies. This naming strategy extends to all search functions - they should reveal whether they use Chroma semantic search, FTS5 keyword fallback, or direct SQLite filtering. The semantic naming approach ensures that anyone reading the code immediately understands FTS5 is not a primary feature but exists only as a backup when the preferred Chroma system is unavailable. This prevents future developers from treating FTS5 as an equal alternative to Chroma.\n\n---\nType: decision | Facts: CLAUDE.md semantic naming principle requires verbose names that reveal intent; Current name `escapeFTS5()` hides that FTS5 is fallback for missing Chroma; Proposed naming like `escapeFTS5_fallback_for_missing_chroma()` makes degraded mode explicit; All FTS5-related functions need renaming to state \"degraded fallback for users without Python\"; Search function names should reveal which mechanism they use: Chroma, FTS5, or direct filtering; Semantic naming prevents future confusion about FTS5 architectural role | Concepts: pattern, why-it-exists, how-it-works, trade-off | Files: CLAUDE.md\n\n---\nDate: 11/17/2025, 11:47:00 PM\n\n---\n\n## Semantic Naming Strategy for FTS5 Functions Due to UVX Dependency\n*Source: claude-mem://observation/10741*\n\n**FTS5-related functions, variables renamed to indicate temporary usage pending UVX availability for semantic search.**\n\nThe team has decided to implement a semantic naming convention for all FTS5-related code to clearly communicate that FTS5 is a temporary workaround. The naming pattern \"fts5_only_because_uvx_is_disabled\" will be applied to functions and variables that currently implement full-text search using FTS5. This decision stems from the understanding that UVX (which would enable proper semantic search) is currently disabled, forcing reliance on SQLite's FTS5 for text search capabilities. By embedding this context directly in function names, the codebase self-documents the temporary nature of the implementation and the intended migration path. This naming strategy was recently documented in CLAUDE.md and represents a deliberate choice to maintain clarity about technical debt and future refactoring needs despite the increased verbosity.\n\n---\nType: decision | Facts: FTS5 is being used as a temporary solution because UVX is currently disabled; Functions related to FTS5 will be renamed with semantic suffix \"_only_because_uvx_is_disabled\"; The naming convention makes the temporary nature of FTS5 usage explicit in the codebase; This decision was recently added to CLAUDE.md documentation; The renaming applies to all FTS5 functions and related variables throughout the codebase | Concepts: why-it-exists, pattern, trade-off, what-changed\n\n---\nDate: 11/17/2025, 11:46:49 PM\n\n---\n\n## Unified search handler fix requires five-step query routing logic\n*Source: claude-mem://observation/10739*\n\n**Route by query presence, error-based FTS5 fallback only, remove zero-results fallback check.**\n\nThe fix for the unified search handler requires restructuring the query routing logic into five distinct steps. First, check whether the query parameter exists at the top of the handler. If query is undefined, bypass Chroma entirely and invoke a new filter-only path in SessionSearch that performs direct SQLite filtering. If query exists, proceed with Chroma semantic search. The FTS5 fallback logic must change fundamentally - it should only trigger when Chroma throws an error (caught at line 465), not when Chroma successfully returns zero results. When Chroma returns zero results, that is the correct answer since FTS5 contains identical data and would also return zero. This requires removing the zero-results check from line 472's fallback condition, fixing the current incorrect fallback behavior.\n\n---\nType: decision | Facts: Step 1: Check if query parameter exists at beginning of unified search handler; Step 2: If query is undefined, skip Chroma and call new filter-only path in SessionSearch; Step 3: If query exists, attempt Chroma semantic search; Step 4: If Chroma throws error (line 465 catch block), fall back to FTS5; Step 5: If Chroma succeeds with zero results, accept zero as correct answer without FTS5 fallback; Line 472 condition must be modified to remove zero-results check | Concepts: problem-solution, how-it-works, pattern, trade-off | Files: src/servers/search-server.ts\n\n---\nDate: 11/17/2025, 11:42:18 PM\n\n---\n\n## Query Routing Architecture: ChromaDB, SQLite, and FTS5 Fallback Strategy\n*Source: claude-mem://observation/10736*\n\n**Defined three distinct query paths based on query presence and ChromaDB availability to prevent incorrect fallback logic.**\n\nThe proper query routing architecture requires three distinct paths based on query presence and ChromaDB availability. Path 1: When a semantic query exists and ChromaDB is available, route to queryChroma with both query and filters. If ChromaDB errors (service failure), fall back to FTS5. However, if ChromaDB successfully returns zero results, accept that as the final answer without falling back - empty results indicate no semantic match, which is more accurate than FTS5. Path 2: When the query parameter is undefined (filter-only operations), skip ChromaDB entirely and route directly to SQLite filtering using SessionStore, not SessionSearch. This path handles metadata queries like retrieving last decisions. Path 3: When a query exists but ChromaDB is unavailable, use FTS5 as a degraded fallback. The current implementation incorrectly mixes these paths, leading to inappropriate fallback behavior and inefficient routing of filter-only queries through vector search systems.\n\n---\nType: decision | Facts: When query exists and ChromaDB is available, call queryChroma with query and filters; ChromaDB errors should trigger FTS5 fallback, but ChromaDB returning zero results is final and should not trigger fallback; Filter-only queries (undefined query parameter) should skip ChromaDB entirely and use direct SQLite filtering via SessionStore; Filter-only queries should use SessionStore for direct SQLite access, not SessionSearch which involves vector operations; When query exists but ChromaDB is unavailable, FTS5 serves as degraded fallback mode; The current code incorrectly mixes these three query routing paths | Concepts: pattern, how-it-works, problem-solution, trade-off\n\n---\nDate: 11/17/2025, 11:41:54 PM\n\n---\n\n## FTS5 demoted to fallback-only search mechanism\n*Source: claude-mem://observation/10729*\n\n**FTS5 search recognized as redundant when Chroma vector database contains 1:1 SQLite copy.**\n\nThe architectural decision clarifies that FTS5 full-text search, while technically implemented, is essentially redundant in normal operation. Since Chroma vector database maintains a complete 1:1 copy of the SQLite data and provides superior search results, FTS5 exists only as a degraded fallback mode for users who cannot install Python dependencies. In practical deployment, the application requires Chroma to function properly, making FTS5 a legacy accommodation rather than a primary feature. This understanding positions FTS5 as \"Chroma search with shitty results\" - functional but not the intended search mechanism.\n\n---\nType: decision | Facts: FTS5 full-text search produces inferior results compared to Chroma vector search; Chroma database maintains a 1:1 copy of all SQLite data; FTS5 serves only as fallback for users without Python dependencies; Application functionality depends primarily on Chroma, making FTS5 nearly vestigial | Concepts: why-it-exists, trade-off, pattern, how-it-works\n\n---\nDate: 11/17/2025, 11:37:41 PM"}]