Fuzzy vs Semantic Search in the Egonex AI Dashboard: What's the Difference?

Fuzzy search uses token-based text matching on node names, summaries, and tags for immediate results, while semantic search is designed to use vector embeddings for meaning-based similarity but currently falls back to the same fuzzy engine.

The Egonex AI dashboard in the Understand-Anything repository provides two distinct search modes accessible from the top-right search box. While users can toggle between fuzzy and semantic search in the UI, these modes differ fundamentally in their underlying algorithms, performance characteristics, and implementation status. This guide examines the technical architecture, source code paths, and current limitations of both search strategies.

How Fuzzy Search Works

Token-Based Matching Strategy

Fuzzy search implements simple text-based matching that tokenizes the query and scores nodes by counting token overlaps in the name, summary, and tags fields. This approach provides immediate, deterministic results using only string operations against a small in-memory index.

Core Implementation

The fuzzy logic resides in packages/core/src/search.ts, where the search() function dispatches to the fuzzy matcher. When the mode is set to 'fuzzy', the system calls fuzzyMatch(query) to execute the search:

// packages/core/src/search.ts (simplified)
export async function search(query: string, opts: { mode: 'fuzzy' | 'semantic' }) {
  if (opts.mode === 'semantic') {
    // Intended path – call embedding-search (not yet wired)
    return embeddingSearch(query);
  }
  // Fuzzy fallback
  return fuzzyMatch(query);
}

The UI tooltip defined in packages/dashboard/src/locales/en.ts at line 289 explains that fuzzy search "fuzzy-matches node name / summary / tags," confirming the fields checked against the query tokens.

How Semantic Search Works (Planned Implementation)

Vector-Based Similarity Architecture

Semantic search is architected to use vector-based similarity rather than text tokenization. According to the source in packages/core/src/embedding-search.ts, the query would be embedded via embedText(query) and compared against pre-computed embeddings using nearest-neighbor lookup:

// packages/core/src/embedding-search.ts
export async function embeddingSearch(query: string) {
  const queryVec = await embedText(query);      // call LLM embedding model
  return findNearestNeighbors(queryVec, index); // vector similarity
}

This approach returns nodes whose concepts are similar to the query, even when exact wording differs.

Current Fallback Behavior

Despite the UI toggle existing in the dashboard, semantic search is not yet fully active. A comment at line 527 of packages/dashboard/src/store.ts explicitly states: "Currently both modes use the same fuzzy engine." When users select semantic mode, the search routine still invokes fuzzyMatch() while the embedding pipeline awaits full integration.

Switching Between Search Modes

Global State Management

The search mode state lives in the global store at packages/dashboard/src/store.ts. The SearchState interface declares the two modes and their setter:

// packages/dashboard/src/store.ts
interface SearchState {
  searchMode: 'fuzzy' | 'semantic';
  setSearchMode: (mode: 'fuzzy' | 'semantic') => void;
}

The default configuration at line 298 initializes the mode to 'fuzzy':

const useSearchStore = create<SearchState>()(set => ({
  searchMode: 'fuzzy',
  setSearchMode: mode => set({ searchMode: mode }),
}));

Programmatic Mode Control

You can switch modes programmatically using the store's setter method:

// Switch to fuzzy mode (default)
store.setSearchMode('fuzzy');

// Switch to semantic mode (currently falls back to fuzzy)
store.setSearchMode('semantic');

// Perform a search (same function called for both modes)
const results = await search(query, {
  mode: store.searchMode,   // 'fuzzy' | 'semantic'
});

Performance and User Experience Comparison

Fuzzy Search Performance

Fuzzy search operates entirely on string operations against an in-memory index, making it extremely fast and suitable for real-time dashboard filtering. The deterministic scoring based on token overlap produces consistent results instantly.

Semantic Search Resource Requirements

When fully implemented, semantic search will require additional computational steps to embed the query and perform vector similarity lookups. While slightly heavier than string matching, the findNearestNeighbors() approach in embedding-search.ts uses pre-computed vectors to maintain responsive performance for concept-based matching.

Summary

• Fuzzy search is the active, default mode using token-based text matching in packages/core/src/search.ts — it is fast, deterministic, and matches against node names, summaries, and tags.
• Semantic search is the planned vector-based approach using packages/core/src/embedding-search.ts with embedText() and findNearestNeighbors(), but currently falls back to the fuzzy matching engine.
• The global store in packages/dashboard/src/store.ts manages both modes via setSearchMode(), defaulting to 'fuzzy' at line 298 as noted in the source.
• Users can toggle between modes in the UI, though both currently use the same underlying fuzzy engine until the embedding pipeline is fully wired.

Frequently Asked Questions

Why does semantic search return the same results as fuzzy search?

Currently, both modes invoke the same fuzzy matching engine. A comment at line 527 of packages/dashboard/src/store.ts explicitly notes that the semantic mode falls back to fuzzy matching while the embedding pipeline awaits full integration. The vector-based search using embeddingSearch() in packages/core/src/embedding-search.ts is defined but not yet connected to the active code path.

How do I switch between fuzzy and semantic search programmatically?

Use the setSearchMode() method from the global store defined in packages/dashboard/src/store.ts. Pass either 'fuzzy' or 'semantic' as the argument. The store updates the searchMode state, which the search() function in packages/core/src/search.ts receives via the options parameter to determine which algorithm to run.

What fields does fuzzy search check against?

The fuzzy matcher tokenizes queries and scores nodes based on token appearance in the name, summary, and tags fields. This is confirmed by the UI tooltip text in packages/dashboard/src/locales/en.ts at line 289, which describes fuzzy-matching against these specific node attributes.

Will semantic search be slower than fuzzy search?

When fully implemented, semantic search will require additional overhead to embed the query and perform vector similarity lookups against pre-computed embeddings. However, the embedding-search.ts implementation uses pre-computed vectors and efficient nearest-neighbor algorithms, so the performance difference should remain minimal for dashboard-scale datasets.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}