How Understand-Anything Implements Fuzzy and Semantic Search Using Fuse.js

The Understand-Anything knowledge graph indexes every node as a GraphNode object and leverages the SearchEngine class in packages/core/src/search.ts to wrap Fuse.js, enabling weighted field matching with a 0.4 threshold and returning scored results for fast, fuzzy retrieval.

Understand-Anything provides intelligent code exploration by treating files, classes, and functions as searchable entities within a unified knowledge graph. The repository implements its search capabilities through a dedicated SearchEngine class that configures Fuse.js for weighted field matching and fuzzy token logic. This approach delivers lightweight semantic behavior without requiring external language models or vector databases.

Fuse.js Configuration and Field Weighting

The search engine initializes a single Fuse instance with carefully tuned options designed to balance fuzzy matching precision with recall.

Weighted Search Fields

According to the source code in packages/core/src/search.ts, the FUSE_OPTIONS object defines four searchable fields with descending priority weights:

• name: 0.4
• tags: 0.4
• summary: 0.2
• languageNotes: 0.1

This weighting schema ensures that matches in node names and tags contribute significantly more to relevance scoring than matches in supplementary documentation fields.

Fuzzy Matching Threshold

The configuration sets a threshold of 0.4, which controls the fuzziness distance for string matching. Values closer to 0.0 require exact matches, while 1.0 matches anything. The 0.4 setting enables typo tolerance and partial matches while filtering out distant, irrelevant results.

Additional critical flags include:

• includeScore: true – Returns similarity scores where 0 represents exact matches and 1 represents worst matches
• ignoreLocation: true – Makes searches location-agnostic across the text
• useExtendedSearch: true – Enables complex token query syntax

Query Processing and Token Logic

The engine transforms raw user input into Fuse-compatible extended search syntax to simulate semantic behavior without neural networks.

Extended Token Handling

When processing queries, the search method in packages/core/src/search.ts splits input on whitespace and joins tokens with the | operator. This converts a query like "auth contrl" into "auth | contrl", instructing Fuse to match nodes containing either token.

As implemented in lines 44-47, this transformation provides OR-logic matching without requiring full-text search infrastructure or embeddings.

Lightweight Semantic Matching

The | operator functions as Fuse.js's built-in OR logical operator. By automatically inserting this operator between whitespace-separated terms, Understand-Anything achieves semantic-like search where users can find AuthenticationController despite typing fragmented or partially correct terms like "auth contrl", as demonstrated in the test suite at packages/core/src/__tests__/search.test.ts.

Result Filtering and Scoring

After Fuse returns raw matches, the engine applies business logic filtering before returning results to the UI.

Type Filtering and Limits

The search method accepts an options.types parameter (lines 50-53) that filters results to specific node categories such as function, class, or file. It also applies a default limit of 50 results (lines 55-58), preventing UI overload while preserving the highest-scored matches.

Score Exposure

Each result maps to a SearchResult object containing:

• nodeId: The identifier for the matched graph node
• score: The Fuse-computed relevance score between 0.0 and 1.0

The test suite in packages/core/src/__tests__/search.test.ts verifies that returned scores always fall within this normalized range, allowing interfaces to rank or highlight the most relevant matches.

Dynamic Index Updates

When the knowledge graph changes—such as when new files are analyzed—the updateNodes method (lines 61-64) rebuilds the underlying Fuse index. This guarantees that subsequent searches immediately reflect the latest graph state without requiring application restarts or manual cache invalidation.

Practical Implementation Examples

Creating and Querying the Search Engine

import { SearchEngine } from "@understand-anything/core";
import type { GraphNode } from "@understand-anything/core/types";

// Initialize with graph nodes
const engine = new SearchEngine(graphNodes);

// Fuzzy search with typo tolerance
const results = engine.search("auth contrl");

// Filter by node type with result limiting
const funcResults = engine.search("auth", {
  types: ["function"],
  limit: 5,
});

// Update index after graph modifications
engine.updateNodes(updatedGraphNodes);

Dashboard Store Integration

In packages/dashboard/src/store.ts, the dashboard initializes the engine from the graph state:

import { SearchEngine } from "@understand-anything/core";
import type { Graph } from "./types";

let searchEngine: SearchEngine;

export function initSearch(graph: Graph) {
  searchEngine = new SearchEngine(graph.nodes);
}

export function performSearch(query: string) {
  return searchEngine.search(query);
}

Summary

• Weighted Field Configuration: The SearchEngine configures Fuse.js with fields weighted from 0.4 (name/tags) to 0.1 (languageNotes) to prioritize relevant matches.
• Fuzzy Threshold: A 0.4 threshold balances typo tolerance with precision, while ignoreLocation ensures text position does not affect scoring.
• Token OR Logic: Queries automatically transform into extended Fuse syntax using the | operator, enabling multi-term semantic-like matching.
• Runtime Updates: The updateNodes method rebuilds the Fuse index dynamically when the knowledge graph changes, ensuring real-time accuracy.
• Scored Results: Each match includes a normalized score between 0 and 1, allowing UIs to rank and filter results by relevance.

Frequently Asked Questions

How does Understand-Anything handle typos in search queries?

Understand-Anything leverages Fuse.js's fuzzy matching capability through a threshold setting of 0.4 in packages/core/src/search.ts. This configuration allows the engine to match strings with typographical errors or partial inputs—such as "contrl" matching "controller"—while filtering out results that exceed the distance threshold.

What fields does the search engine index for each code element?

The engine indexes four fields defined in the FUSE_OPTIONS configuration: name (weight 0.4), tags (weight 0.4), summary (weight 0.2), and languageNotes (weight 0.1). These fields are extracted from each GraphNode object representing files, classes, functions, and other code entities in the knowledge graph.

How are search results ranked and limited?

Results include a score property ranging from 0 (exact match) to 1 (worst match) computed by Fuse.js. The SearchEngine applies a default limit of 50 results and supports optional filtering by node type through the options.types parameter, allowing callers to restrict results to specific categories like functions or classes.

Can the search index update without restarting the application?

Yes. The updateNodes method in packages/core/src/search.ts rebuilds the Fuse index dynamically when the underlying graph changes. This allows the dashboard and other components to reflect newly analyzed files or modified code structures immediately without requiring an application restart.

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