# What Is the Fingerprint Baseline in Egonex AI's Incremental Updates?

> Learn how the fingerprint baseline in Egonex AI's incremental updates distinguishes code changes, optimizing knowledge graph analysis by storing structural signatures and content hashes.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: internals
- Published: 2026-06-17

---

**The fingerprint baseline is a JSON snapshot stored in [`.understand-anything/fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/fingerprints.json) that captures structural signatures and SHA-256 content hashes for every source file, enabling the system to distinguish between cosmetic and structural code changes to avoid unnecessary full re-analyses of the knowledge graph.**

The Egonex-AI/Understand-Anything repository implements an efficient incremental update system that avoids expensive LLM calls on every commit. By maintaining a **fingerprint baseline**, the system can detect exactly what changed in your codebase and decide whether to perform a lightweight token update or a full graph reconstruction.

## How the Baseline Is Generated

When a project is first scanned or after a full update, the skill `build-fingerprints.mjs` invokes the core function `buildFingerprintStore()` in [`understand-anything-plugin/packages/core/src/fingerprint.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/fingerprint.ts) (lines 48-55) to produce the baseline file.

For each source file, the system:

- Extracts **structural signatures** (functions, classes, imports/exports) using Tree‑Sitter
- Records a SHA‑256 content hash of the file
- Falls back to content‑hash only for files without Tree‑Sitter support, which forces a **STRUCTURAL** classification on any subsequent change

The resulting [`fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprints.json) lives under `.understand-anything/` and is versioned together with the Git commit hash via the `FingerprintStore` interface (lines 41-46 in [`fingerprint.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprint.ts)).

## The Incremental Decision Logic

On every subsequent commit, the auto‑update script ([`auto-update-prompt.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/auto-update-prompt.md)) reads the stored baseline and compares it to freshly extracted fingerprints using `analyzeChanges()` (lines 95-108 in [`fingerprint.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprint.ts)).

The `compareFingerprints()` function categorizes each changed file into one of three levels:

**NONE** – Identical content hash means no work is required.

**COSMETIC** – Content changed but structural signatures match, requiring only a minimal LLM token update.

**STRUCTURAL** – Any signature change (new or removed functions, modified parameters, import list changes) triggers recomputation of affected graph nodes, potentially requiring a full‑graph rebuild.

## Why the Baseline Matters for Performance

The baseline acts as the single source of truth for every incremental run. If [`fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprints.json) is missing or stale, the system treats every file as new with a `STRUCTURAL` classification and falls back to a full update, as noted in the comments of `build-fingerprints.mjs` (lines 5-9).

Maintaining an accurate baseline dramatically reduces token usage and improves update speed by ensuring only truly changed structures trigger expensive graph operations.

## Working with the Fingerprint Baseline

### Generating the Baseline

Run the following after a full update or initial project scan:

```bash

# From the project root

node understand-anything-plugin/skills/understand/build-fingerprints.mjs \
  .understand-anything/intermediate/fingerprint-input.json

# → writes .understand-anything/fingerprints.json

```

This script reads the list of source files produced by the scanner and calls `buildFingerprintStore()` to create the persistent baseline.

### Using the Baseline for Incremental Updates

```typescript
import { analyzeChanges } from "./fingerprint.js";
import { PluginRegistry } from "./plugins/registry.js";
import { readFileSync } from "fs";
import { join } from "path";

// Load the stored baseline
const stored = JSON.parse(readFileSync(
  join(projectRoot, ".understand-anything", "fingerprints.json"),
  "utf-8"
)) as FingerprintStore;

// Detect which files changed (e.g., from git diff)
const changed = ["src/foo.ts", "src/bar.ts"];

// Run the incremental analysis
const analysis = analyzeChanges(projectRoot, changed, stored, registry);

console.log(analysis);

```

The `analysis` object contains the `changeLevel` for each file (`NONE`, `COSMETIC`, or `STRUCTURAL`). The auto‑update pipeline uses this to determine whether to re‑run the LLM on specific graph nodes or skip them entirely.

### Detecting Structural Changes Programmatically

```typescript
// Old fingerprint from baseline
const oldFp = stored.files["src/foo.ts"];

// New fingerprint after the edit
const newFp = extractFileFingerprint(
  "src/foo.ts",
  readFileSync(join(projectRoot, "src/foo.ts"), "utf-8"),
  registry.analyzeFile("src/foo.ts", /* ... */)
);

// Compare against baseline
const result = compareFingerprints(oldFp, newFp);
console.log(result.changeLevel); // → "STRUCTURAL" if a function signature changed

```

The `compareFingerprints` routine (lines 31-40 in [`fingerprint.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprint.ts)) reports exact structural differences—such as added or removed functions and changed parameters—that drive the incremental update decision.

## Summary

- The **fingerprint baseline** is stored in [`.understand-anything/fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/fingerprints.json) and contains SHA‑256 hashes and structural signatures for every source file.
- The `buildFingerprintStore()` function in [`fingerprint.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprint.ts) generates this baseline using Tree‑Sitter parsing.
- `analyzeChanges()` compares the current state against the baseline to classify changes as **NONE**, **COSMETIC**, or **STRUCTURAL**.
- Missing or stale baselines force expensive full re‑analyses, while accurate baselines minimize LLM token consumption.
- The system is implemented across `build-fingerprints.mjs`, [`fingerprint.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprint.ts), and the [`auto-update-prompt.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/auto-update-prompt.md) pipeline.

## Frequently Asked Questions

### What happens if the fingerprint baseline file is deleted?

If [`.understand-anything/fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/fingerprints.json) is missing, the system cannot determine the previous state of any file. According to the source code in `build-fingerprints.mjs`, the update pipeline treats every file as having a **STRUCTURAL** change level, forcing a full knowledge graph rebuild rather than an incremental update.

### How does the baseline distinguish between cosmetic and structural changes?

The baseline stores both content hashes and parsed structural signatures. When `compareFingerprints()` runs, it first checks the SHA‑256 hash. If the hash differs, it compares the Tree‑Sitter extracted signatures (functions, classes, imports). Matching signatures with different content yields **COSMETIC**, while signature mismatches yield **STRUCTURAL**.

### Where is the fingerprint baseline stored and versioned?

The baseline persists as [`fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprints.json) in the `.understand-anything/` directory. The `FingerprintStore` interface (lines 41-46 in [`fingerprint.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprint.ts)) records the Git commit hash alongside the fingerprint data, ensuring the baseline remains synchronized with the repository state it represents.

### Can files without Tree‑Sitter support use incremental updates?

Files unsupported by Tree‑Sitter receive only a content‑hash fingerprint with no structural signatures. This forces the system to classify any change as **STRUCTURAL**, since it cannot determine whether the modification affects code structure or merely comments and whitespace.