# How the Persistence Layer Saves and Loads the Knowledge Graph JSON in Egonex-AI/Understand-Anything

> Discover how Egonex AI's persistence layer saves and loads knowledge graph JSON. Learn about JSON serialization, file path sanitization, and TypeScript schema validation for robust data management.

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

---

**The persistence layer in Egonex-AI/Understand-Anything writes the knowledge graph to a hidden `.understand-anything` directory as pretty-printed JSON, sanitizing file paths to remove absolute references before serialization, and validates the structure against a TypeScript schema when loading it back.**

The Egonex-AI/Understand-Anything repository provides a robust persistence mechanism that stores analysis results locally while preserving user privacy. Understanding how this layer serializes and deserializes the knowledge graph JSON is essential for developers extending the tool or integrating it into custom workflows. The implementation resides in [`understand-anything-plugin/packages/core/src/persistence/index.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/persistence/index.ts) and handles everything from directory creation to schema validation.

## Where the Persistence Layer Lives

The core persistence logic is centralized in **[`understand-anything-plugin/packages/core/src/persistence/index.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/persistence/index.ts)**. This module exports functions for saving and loading the primary knowledge graph, along with auxiliary metadata, fingerprints, configuration, and domain-specific graphs. All persisted files are stored within a hidden folder named **`.understand-anything`** located at the project root.

## How the Knowledge Graph Is Saved

The `saveGraph` function orchestrates the write process through three critical steps to ensure portable, privacy-safe storage.

### Directory Initialization

Before writing any data, the helper `ensureDir(projectRoot)` verifies that the `.understand-anything` folder exists, creating it if necessary. This check runs at lines 13–19 in the persistence index.

### Path Sanitization

To prevent leakage of personal directory structures, the `sanitiseFilePaths` function (lines 38–66) normalizes every node’s `filePath` before serialization:

- **Inside the project**: Converts absolute paths to relative paths (e.g., [`/Users/alice/company/src/auth.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main//Users/alice/company/src/auth.ts) → [`src/auth.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/src/auth.ts))
- **Outside the project**: Strips to filename only (e.g., [`/Users/alice/library.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main//Users/alice/library.ts) → [`library.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/library.ts))
- **Already relative**: Leaves unchanged

### JSON Serialization

After sanitization, `saveGraph` (lines 69–83) calls `JSON.stringify(graph, null, 2)` to produce pretty-printed JSON and writes the output to **[`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json)** using `writeFileSync`.

## How the Knowledge Graph Is Loaded

The `loadGraph` function (lines 85–104) reverses the process with built-in safety checks.

### Validation on Read

By default, `loadGraph` reads the JSON from disk, parses it, and passes the result through `validateGraph` imported from **[`packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts)**. If the structure does not conform to the `KnowledgeGraph` TypeScript interface defined in [`src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/src/types.ts), the function throws an error immediately. Developers can bypass validation by passing `{ validate: false }` in the options parameter.

## Auxiliary Data Files

The persistence layer manages several companion files alongside the main graph, each following the same ensure-directory-write pattern:

- **[`meta.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/meta.json)**: Stores runtime metadata including timestamps and git hashes (`saveMeta`/`loadMeta`, lines 107–115)
- **[`fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprints.json)**: Caches file-level fingerprints for incremental change detection (`saveFingerprints`/`loadFingerprints`, lines 118–131)
- **[`config.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/config.json)**: Holds user-configurable settings (`saveConfig`/`loadConfig`, lines 133–148)

## Domain-Graph Handling

For higher-level system views, the same sanitization and validation logic is reused for **[`domain-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/domain-graph.json)**. The `saveDomainGraph` and `loadDomainGraph` functions (lines 152–182) follow identical patterns to the primary graph functions but operate on a separate data structure representing domain-level abstractions.

## Practical Code Examples

### Saving a Graph After Analysis

```typescript
import { saveGraph } from '@understand-anything/core/persistence';
import type { KnowledgeGraph } from '@understand-anything/core/types';

async function persist(projectRoot: string, graph: KnowledgeGraph) {
  // Absolute paths are automatically sanitised before writing
  saveGraph(projectRoot, graph);
}

```

### Loading a Graph With Validation

```typescript
import { loadGraph } from '@understand-anything/core/persistence';
import type { KnowledgeGraph } from '@understand-anything/core/types';

function restore(projectRoot: string): KnowledgeGraph {
  // Throws if JSON is malformed or violates the schema
  return loadGraph(projectRoot);
}

```

### Loading Without Validation

```typescript
// Use for quick probes or when schema evolution creates temporary mismatches
const graph = loadGraph(projectRoot, { validate: false });

```

### Working with Auxiliary Data

```typescript
import {
  saveMeta,
  loadMeta,
  saveFingerprints,
  loadFingerprints,
} from '@understand-anything/core/persistence';

// Update last-run timestamp
const meta = loadMeta(projectRoot) ?? { lastAnalyzedAt: '' };
meta.lastAnalyzedAt = new Date().toISOString();
saveMeta(projectRoot, meta);

// Check cached fingerprints
const fingerprints = loadFingerprints(projectRoot);

```

## Summary

- The persistence layer lives in **[`understand-anything-plugin/packages/core/src/persistence/index.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/persistence/index.ts)** and stores all data under a **`.understand-anything`** directory at the project root.
- **`sanitiseFilePaths`** strips absolute paths to protect privacy before writing to **[`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json)**.
- **`saveGraph`** serializes to pretty-printed JSON using `JSON.stringify(..., null, 2)`.
- **`loadGraph`** validates against the TypeScript schema by default via `validateGraph` from [`packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts).
- Auxiliary files (**[`meta.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/meta.json)**, **[`fingerprints.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/fingerprints.json)**, **[`config.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/config.json)**, and **[`domain-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/domain-graph.json)**) use identical persistence patterns.

## Frequently Asked Questions

### What happens if the knowledge graph JSON is corrupted?

If the stored JSON is malformed or fails schema validation, `loadGraph` throws an error immediately. You can skip validation by passing `{ validate: false }` to attempt loading the raw data, though this risks runtime type errors.

### Why does the persistence layer sanitize file paths?

**Sanitization prevents accidental leakage of developer-specific directory structures** such as `/Users/alice/...` or `/home/bob/...`. Paths inside the project become relative, while external paths are reduced to filenames only, ensuring the JSON remains portable and privacy-safe when shared.

### Can I store the knowledge graph outside the `.understand-anything` folder?

The current implementation in [`packages/core/src/persistence/index.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/persistence/index.ts) hardcodes the `.understand-anything` directory via `ensureDir(projectRoot)`. To use a custom location, you would need to fork the persistence module or use the lower-level `sanitiseFilePaths` and `JSON.stringify` logic manually.

### Where is the TypeScript schema defined for graph validation?

The validation logic resides in **[`packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts)**, which exports `validateGraph`. This validator ensures that loaded objects conform to the `KnowledgeGraph` interface defined in [`packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/types.ts).