How Understand-Anything Implements Fuzzy Matching Across Graph Nodes

The Understand-Anything search module implements fuzzy matching across graph nodes by wrapping the Fuse.js library in a SearchEngine class that indexes GraphNode objects with weighted keys and typo-tolerant OR-style query parsing.

The open-source Understand-Anything project by Egonex-AI provides intelligent knowledge graph exploration through its fuzzy search capabilities. Located in the core package, the SearchEngine class leverages Fuse.js to deliver typo-tolerant queries across node attributes. This implementation weights specific fields like node names and tags to prioritize the most relevant matches when searching the knowledge graph.

Understanding the SearchEngine Architecture

The fuzzy search capability centers on the SearchEngine class defined in packages/core/src/search.ts. This class initializes a Fuse.js index over an array of GraphNode objects during construction, enabling fast, client-side fuzzy retrieval without external search services.

According to the source code at lines 31-34, the constructor instantiates Fuse with the node array and a shared options configuration:

this.fuse = new Fuse(nodes, FUSE_OPTIONS);

The GraphNode type definition resides in packages/core/src/types.ts, establishing the schema for indexed documents.

Weighted Field Configuration for Relevance

Configuring Search Keys with Priority Weights

To ensure search results prioritize the most meaningful node attributes, the engine configures four weighted search keys in FUSE_OPTIONS (lines 15-20). Each key receives a specific weight that influences the relevance score:

• name – Weight 0.4 (highest priority)
• tags – Weight 0.3
• summary – Weight 0.2
• languageNotes – Weight 0.1

This weighting scheme ensures that matches in node names contribute significantly more to the final score than matches in supplementary fields like language-specific notes.

Fuzzy Matching Configuration

Threshold and Scoring Behavior

The FUSE_OPTIONS object (lines 21-24) configures Fuse.js for true fuzzy matching with the following parameters:

• threshold: 0.4 – Sets the match quality tolerance, where 0.0 requires a perfect match and 1.0 matches everything.
• includeScore: true – Returns relevance scores with each result for ranking transparency.
• ignoreLocation: true – Allows matches to occur anywhere in the field, not just at the beginning.
• useExtendedSearch: true – Enables logical operators like OR within queries.

These settings enable the engine to locate nodes even when queries contain typographical errors or partial terms.

Query Processing and Token-OR Logic

Before executing a search, the SearchEngine.search() method transforms user input to support implicit OR logic. As implemented at lines 44-47, the code splits the query on whitespace and rejoins tokens with the | operator, which Fuse interprets as logical OR.

For example, the query "auth contrl" becomes "auth | contrl", allowing the engine to match nodes containing either token. This transformation is critical for the typo-tolerant behavior demonstrated in the test suite at packages/core/src/__tests__/search.test.ts (lines 73-78), where the misspelled query "auth contrl" successfully locates the AuthenticationController node (ID: auth-ctrl).

Filtering and Result Limiting

After Fuse returns raw results, the engine applies optional post-processing filters. As shown in lines 49-59, the implementation supports:

1. Type filtering – Restricting results to specific node types via the options.types parameter.
2. Result limiting – Slicing the result array to the requested limit count.
3. Score stripping – Mapping final results to a clean { nodeId, score } object.

This pipeline ensures consumers receive precisely formatted, bounded result sets without leaking internal Fuse metadata.

Practical Implementation Examples

The following TypeScript examples demonstrate how to initialize the search engine and execute queries against a knowledge graph:

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

// Example node set (usually generated from the knowledge graph)
const nodes: GraphNode[] = [
  {
    id: "auth-ctrl",
    name: "AuthenticationController",
    type: "class",
    tags: ["auth", "controller"],
    summary: "Handles login and session management",
    languageNotes: "Express middleware",
    // …other fields required by GraphNode
  },
  // …more nodes
];

// Initialise the engine
const engine = new SearchEngine(nodes);

// 1️⃣ Simple fuzzy query (typo tolerant)
const fuzzy = engine.search("auth contrl");
console.log(fuzzy[0].nodeId); // → "auth-ctrl"

// 2️⃣ Search across tags / summary
const tagMatch = engine.search("security");
console.log(tagMatch.map(r => r.nodeId)); // → ["auth-ctrl", "auth-middleware"]

// 3️⃣ Restrict results to a specific node type
const functionsOnly = engine.search("auth", { types: ["function"] });
console.log(functionsOnly.map(r => r.nodeId)); // → ["auth-middleware"]

// 4️⃣ Limit the number of returned results
const limited = engine.search("database", { limit: 2 });
console.log(limited.length); // → 2

To update the index without rebuilding the entire instance, use the updateNodes() method:

engine.updateNodes([...nodes, newNode]);
const afterUpdate = engine.search("newFeature");

Summary

• Fuse.js Integration: The SearchEngine class in packages/core/src/search.ts wraps Fuse.js to provide client-side fuzzy matching over GraphNode arrays.
• Weighted Scoring: Four node attributes (name, tags, summary, languageNotes) are searched with descending weights of 0.4, 0.3, 0.2, and 0.1 respectively.
• Typo Tolerance: A threshold of 0.4 combined with ignoreLocation: true enables matching despite spelling errors and partial terms.
• Token OR Logic: Queries are automatically converted to extended search syntax by joining space-separated tokens with |, enabling matches on any query word.
• Flexible Filtering: Results can be filtered by node type and limited to specific counts before returning clean { nodeId, score } objects.

Frequently Asked Questions

What library does Understand-Anything use for fuzzy matching?

The search module leverages Fuse.js, a lightweight JavaScript fuzzy-search library. The SearchEngine class instantiates a Fuse index in its constructor (lines 31-34 of packages/core/src/search.ts) with custom configuration options optimized for graph node attributes.

How does the search handle typos in queries?

The implementation tolerates typos through a combination of Fuse's fuzzy algorithm and a threshold of 0.4, which allows approximate matches. Additionally, the ignoreLocation: true setting ensures characters can match anywhere in the text, not just at the start. The test suite demonstrates this by successfully matching "auth contrl" to AuthenticationController despite the missing "o".

Can I filter search results by node type?

Yes. The search() method accepts an optional types parameter in its options object. When provided, the engine filters the Fuse results to include only nodes whose type property matches the specified array of strings, as implemented in lines 49-59 of the core search module.

How are search results ranked?

Results are ranked according to weighted relevance scores calculated by Fuse.js based on the configured keys. The name field carries the highest weight (0.4), followed by tags (0.3), summary (0.2), and languageNotes (0.1). The includeScore: true option ensures these relevance scores are returned with each result, with lower scores indicating better matches.

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