# How to Commit and Share the Knowledge Graph with Your Development Team

> Learn how to commit and share your knowledge graph using Git. Serialize your knowledge graph as knowledge-graph.json for seamless team collaboration and codebase architecture tracking in Lum1104/Understand Anything.

- Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-02

---

**The Understand-Anything knowledge graph is serialized as [`knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/knowledge-graph.json) inside the `.understand-anything/` directory, enabling version control through standard Git workflows so development teams can collaboratively track codebase architecture.**

The Understand-Anything open-source project constructs a detailed knowledge graph representing every file, function, class, and dependency in your codebase. Because this graph is persisted as a flat JSON file rather than binary storage, it integrates seamlessly with existing Git workflows, allowing teams to share architectural insights through standard commits and pull requests.

## Where the Knowledge Graph Is Stored

According to the source code in [`understand-anything-plugin/packages/core/src/persistence/index.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/persistence/index.ts), the graph is written to [`.understand-anything/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) at the project root. This location is explicitly documented in the skill definition at [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md), which specifies that the `/understand` skill outputs the committable graph to this hidden directory.

## Step-by-Step Workflow to Commit and Share the Knowledge Graph

### 1. Generate the Graph

Execute the primary analysis skill to create the graph. The CLI command triggers the persistence layer that serializes the structured data:

```bash

# Run from project root

understand

# Or force a full rebuild rather than incremental

understand --full

```

This writes the complete graph structure to [`.understand-anything/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) as specified in the skill documentation.

### 2. Verify the Output

Confirm the file exists and is readable. The dashboard validates this by serving the file via a dedicated route in [`understand-anything-plugin/packages/dashboard/vite.config.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/vite.config.ts) (lines 130-252), exposing it at [`/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main//knowledge-graph.json). Start the dashboard to verify:

```bash
pnpm dev:dashboard

```

### 3. Configure Auto-Updates (Optional)

For teams wanting automatic graph updates on every commit, enable the post-commit hook. Modify [`.understand-anything/config.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/config.json):

```json
{
  "autoUpdate": true
}

```

When enabled, the hook registered in [`understand-anything-plugin/hooks/hooks.json`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/hooks/hooks.json) triggers incremental updates by comparing the commit hash stored in [`.understand-anything/meta.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/meta.json) against the current HEAD, as detailed in [`understand-anything-plugin/hooks/auto-update-prompt.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/hooks/auto-update-prompt.md) (lines 19-30).

### 4. Stage and Commit the Graph

Add the generated file to your repository:

```bash
git add .understand-anything/knowledge-graph.json
git commit -m "chore: add latest knowledge graph for team review"

```

### 5. Share with Your Development Team

Push the commit to your remote repository:

```bash
git push origin main

```

Team members pull the latest changes and launch the dashboard, which automatically loads the shared graph from the local [`.understand-anything/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json) file via the Vite dev server route.

### 6. Validate Continuously in CI

The repository includes a persistence test in [`understand-anything-plugin/packages/core/src/persistence/persistence.test.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/persistence/persistence.test.ts) (line 78) that asserts the graph can be written to the expected directory. Run this in your CI pipeline to ensure committed graphs are well-formed:

```bash
pnpm test

```

Example GitHub Actions snippet:

```yaml
- name: Install dependencies
  run: pnpm install --frozen-lockfile

- name: Validate graph persistence
  run: pnpm test

```

## Understanding the Auto-Update Mechanism

The auto-update feature relies on git metadata to avoid unnecessary full rebuilds. When `autoUpdate` is enabled in the configuration, the system stores the last processed commit hash in [`.understand-anything/meta.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/meta.json). The post-commit hook, registered in [`hooks/hooks.json`](https://github.com/Lum1104/Understand-Anything/blob/main/hooks/hooks.json), executes the logic from [`hooks/auto-update-prompt.md`](https://github.com/Lum1104/Understand-Anything/blob/main/hooks/auto-update-prompt.md) to determine whether to perform an incremental merge or a full regeneration based on whether the hash has changed.

## Summary

- The **knowledge graph** is persisted as [`.understand-anything/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json), making it fully version-controllable
- Run the **`/understand` skill** to generate the graph, which writes through the persistence layer in [`packages/core/src/persistence/index.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/persistence/index.ts)
- Enable **auto-updates** by setting `"autoUpdate": true` in [`.understand-anything/config.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/config.json) to trigger post-commit hooks defined in [`hooks/hooks.json`](https://github.com/Lum1104/Understand-Anything/blob/main/hooks/hooks.json)
- The **dashboard** serves the shared graph via [`/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main//knowledge-graph.json) as configured in [`vite.config.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/vite.config.ts), requiring no additional setup for teammates
- Include **persistence tests** in your CI pipeline to validate graph integrity on every build

## Frequently Asked Questions

### Does the knowledge graph need to be committed to the repository?

Yes. The JSON format is deliberately chosen to support Git-based collaboration. Without committing [`.understand-anything/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json), teammates cannot view the architectural state through the dashboard, as the visualization layer reads from this specific file path.

### What happens if two team members generate different graphs?

Git will flag the merge conflict in [`knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/knowledge-graph.json). Teams should treat the graph like any generated artifact—either regenerate it after merging code changes or designate specific commits for graph updates. The persistence layer in [`packages/core/src/persistence/index.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/persistence/index.ts) handles atomic writes to prevent corruption during generation.

### Can the auto-update hook slow down my commits?

The post-commit hook defined in [`hooks/hooks.json`](https://github.com/Lum1104/Understand-Anything/blob/main/hooks/hooks.json) runs asynchronously and performs incremental updates by comparing commit hashes stored in [`.understand-anything/meta.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/meta.json). For large codebases, the initial generation may take time, but subsequent updates only process changed files unless a full rebuild is forced.

### How do teammates access the shared graph after pulling?

After running `git pull`, team members simply execute `pnpm dev:dashboard`. The Vite configuration in [`packages/dashboard/vite.config.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/dashboard/vite.config.ts) automatically serves the updated [`knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/knowledge-graph.json) at the [`/knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main//knowledge-graph.json) endpoint, loading the latest architectural data in the browser without manual configuration.