# Best Practices for Committing Egonex Knowledge Graph to Shared Repositories

> Master best practices for committing your Egonex knowledge graph to shared repositories. Ensure dashboard functionality by validating before pushing and enabling auto-update hooks.

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

---

**Commit the canonical [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) file to version control while excluding intermediate artifacts, enabling auto-update hooks, and validating the graph before pushing to ensure the dashboard remains functional.**

The Egonex (Understand-Anything) pipeline generates a knowledge graph that captures structural, semantic, and domain-specific information from your codebase. This graph is persisted as [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) inside the `/.understand-anything/` directory and serves as a first-class artifact driving the interactive dashboard and AI agents. Following these guidelines when committing the Egonex knowledge graph to shared repositories ensures that every checkout can render the dashboard without requiring a full recompute.

## Commit the Canonical Egonex Knowledge Graph File

The primary artifact to version is [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json). This file is referenced by multiple skills including `understand-chat` and `understand-dashboard` according to the documentation in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md).

```bash
git add .understand-anything/knowledge-graph.json

```

Committing this file guarantees that team members can immediately access the dashboard without running the analysis pipeline. The graph file is defined as a constant in the core package at [`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), where `GRAPH_FILE = "knowledge-graph.json"` determines the canonical filename.

## Exclude Intermediate Files from Shared Repository Commits

Do not commit temporary or intermediate files generated during the analysis process. Files such as [`intermediate/assembled-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/intermediate/assembled-graph.json) or temporary batch files are regenerated on each run and contain non-canonical data that pollutes repository history.

Add the intermediate directory to your `.gitignore`:

```gitignore

# Do not commit temporary analysis artefacts

.understand-anything/intermediate/

```

## Enable Auto-Update on Commit

Configure the pipeline to automatically keep the graph synchronized with your codebase by setting `"autoUpdate": true` in [`.understand-anything/config.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/config.json). When enabled, a post-commit hook defined in [`understand-anything-plugin/hooks/hooks.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/hooks/hooks.json) triggers the incremental update script, eliminating manual intervention.

```json
{
  "autoUpdate": true,
  "ignorePatterns": ["**/*.test.ts", "node_modules/**"]
}

```

The hook logic, detailed in [`understand-anything-plugin/hooks/auto-update-prompt.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/hooks/auto-update-prompt.md), detects staleness by comparing the stored `gitCommitHash` in [`meta.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/meta.json) against the current repository state. This ensures incremental analysis only runs when the actual code changes.

## Merge Sub-Domain Graphs Before Committing

For projects containing multiple sub-graphs (such as [`frontend-knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/frontend-knowledge-graph.json)), run the bundled [`merge-subdomain-graphs.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/merge-subdomain-graphs.py) script before committing. This script, located at [`understand-anything-plugin/skills/understand/merge-subdomain-graphs.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/merge-subdomain-graphs.py), consolidates disparate graphs into the canonical [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json).

```bash
cd understand-anything-plugin/skills/understand
python merge-subdomain-graphs.py

```

The script scans for `*knowledge-graph*.json` files, deduplicates nodes and edges, and rewrites the canonical file, ensuring a single source of truth across sub-domains.

## Validate the Egonex Knowledge Graph Before Pushing

The dashboard employs Zod schema validation to prevent malformed graphs from breaking the user interface. Validation occurs automatically when the core package writes the graph, as implemented 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).

Run the core package tests locally to verify graph integrity before pushing:

```bash
pnpm --filter @understand-anything/core test

```

This prevents CI failures and ensures the dashboard build completes successfully.

## Document the Egonex Knowledge Graph in Your README

Add a dedicated "Knowledge Graph" section to your repository's README explaining the purpose of [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) and how it is generated via the `/understand` skill. This documentation prevents contributors from manually editing the file and clarifies that it is a generated artifact, not source code.

## Summary

- **Commit the canonical file**: Version [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) alongside your source code to ensure dashboard availability.
- **Ignore intermediate artifacts**: Exclude the `.understand-anything/intermediate/` directory to prevent noisy diffs.
- **Enable auto-updates**: Set `"autoUpdate": true` in [`config.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/config.json) to leverage post-commit hooks for incremental analysis.
- **Merge sub-domain graphs**: Run [`merge-subdomain-graphs.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/merge-subdomain-graphs.py) before committing when working with multiple graph fragments.
- **Validate before pushing**: Execute core package tests to verify graph schema compliance and prevent CI failures.
- **Document the process**: Explain the knowledge graph's purpose in your README to guide new contributors.

## Frequently Asked Questions

### Should I commit the intermediate files in the `.understand-anything/intermediate/` directory?

No, you should not commit intermediate files. These files are regenerated on each analysis run and contain temporary, non-canonical data that will pollute your repository history. Add the entire `intermediate/` folder to your `.gitignore` file to exclude it from version control.

### How does the auto-update hook detect when the knowledge graph needs regeneration?

The pipeline stores the current git commit hash in [`meta.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/meta.json) under the `gitCommitHash` field. The post-commit hook, defined in [`understand-anything-plugin/hooks/hooks.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/hooks/hooks.json) and implemented according to [`understand-anything-plugin/hooks/auto-update-prompt.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/hooks/auto-update-prompt.md), compares this stored hash against the current repository state. When they differ, the hook triggers incremental analysis to update the graph automatically.

### What happens if I commit a malformed knowledge graph?

Committing a malformed graph will cause the dashboard to fail at runtime because the UI validates the graph against a Zod schema. The validation occurs automatically when the core package writes the file 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), but running `pnpm --filter @understand-anything/core test` before pushing will catch errors early and prevent broken dashboard builds in CI.

### Can I merge multiple domain-specific knowledge graphs into one file?

Yes, use the [`merge-subdomain-graphs.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/merge-subdomain-graphs.py) script located in `understand-anything-plugin/skills/understand/`. This utility scans for all `*knowledge-graph*.json` files (excluding the canonical one), deduplicates nodes and edges across them, and consolidates the results into the single [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) file required by the dashboard.