# Best Practices for Using Graphify: Local Knowledge Graph Optimization

> Master Graphify best practices for local knowledge graph optimization. Install the CLI, register skills, manage exclusions, version control outputs, and enable Git hooks for seamless AI assistant updates.

- Repository: [Graphify Labs/graphify](https://github.com/Graphify-Labs/graphify)
- Tags: best-practices
- Published: 2026-07-19

---

**The best practices for using Graphify involve installing the CLI via `uv` or `pipx`, registering the skill with `graphify install`, maintaining a `.graphifyignore` file to exclude generated artifacts, committing the `graphify-out/` directory to version control, and enabling automatic rebuilds through Git hooks to ensure your AI assistant always queries the most current graph structure.**

Graphify transforms entire codebases—including documentation, PDFs, images, and videos—into a **local knowledge graph** that supports intelligent querying without relying on grep. According to the Graphify-Labs/graphify source code, implementing these best practices ensures reproducible builds, prevents accidental indexing of secrets, and maintains consistent graph-first interactions with your IDE assistant. The tool parses code using Tree-Sitter AST extraction (requiring no LLM or network traffic for code analysis) while attaching semantic information for non-code assets.

## Installation and Skill Registration

Start with isolated installation to avoid dependency conflicts. The PyPI package is named `graphifyy` while the CLI command is `graphify`.

```bash
uv tool install graphifyy

# Alternative: pipx install graphifyy

```

After installation, register the skill to enable AI assistant integration. This writes the skill file to [`.agents/skills/graphify/SKILL.md`](https://github.com/Graphify-Labs/graphify/blob/main/.agents/skills/graphify/SKILL.md) (global) or [`./.claude/skills/graphify/SKILL.md`](https://github.com/Graphify-Labs/graphify/blob/main/./.claude/skills/graphify/SKILL.md) (project-scoped).

```bash

# Global registration (recommended for personal machines)

graphify install

# Project-scoped registration (for repository-specific setups)

graphify install --project

```

The skill file instructs your assistant to run `graphify query` before reading source files, establishing a graph-first workflow.

## Building and Committing the Graph

Generate the knowledge graph artifacts by running the build command in your repository root. The first execution may take several seconds; subsequent runs are incremental.

```bash
graphify .

```

This creates the `graphify-out/` directory containing three critical artifacts:

- [`graph.json`](https://github.com/Graphify-Labs/graphify/blob/main/graph.json) – The serialized knowledge graph with god-node rankings and community detection
- [`GRAPH_REPORT.md`](https://github.com/Graphify-Labs/graphify/blob/main/GRAPH_REPORT.md) – Human-readable summary of connections and suggested questions
- [`graph.html`](https://github.com/Graphify-Labs/graphify/blob/main/graph.html) – Interactive visualization with edge confidence tags (`EXTRACTED`, `INFERRED`)

Commit the `graphify-out/` directory to version control to ensure team consistency. However, exclude transient files that vary by environment:

```text

# .gitignore additions

graphify-out/cost.json        # Local cost tracking only

graphify-out/cache/           # Optional: exclude large cache files

```

## Automating Updates with Git Hooks

Prevent graph staleness by installing automatic rebuild triggers. The `graphify hook install` command configures post-commit and post-checkout hooks that regenerate the graph after code changes.

```bash
graphify hook install

```

These hooks include a specialized git merge driver that union-merges [`graph.json`](https://github.com/Graphify-Labs/graphify/blob/main/graph.json) without conflicts, enabling smooth collaborative workflows. After installation, every `git commit` automatically triggers a graph rebuild, ensuring the knowledge graph remains synchronized with the codebase.

## Configuring the Ignore List with `.graphifyignore`

Control indexing scope by creating a `.graphifyignore` file at your repository root. This file follows `.gitignore` syntax but operates with an important constraint: patterns are evaluated **after** `.gitignore`, meaning they can only exclude additional files—never re-include files already excluded by git.

```text

# .graphifyignore example

node_modules/
dist/
*.generated.py

# Only index src/, ignore everything else

*
!src/
!src/**

```

Use the `!` prefix to re-include specific paths within excluded directories when necessary. This configuration prevents Graphify from processing build artifacts, dependencies, and generated files that bloat the graph without adding semantic value.

## Strict Mode and Advanced Configuration

For environments requiring guaranteed graph-first behavior, enable strict mode by setting the `GRAPHIFY_HOOK_STRICT` environment variable. This forces the assistant to query the graph before reading any source file.

```bash
export GRAPHIFY_HOOK_STRICT=1
graphify install  # Re-install to apply the strict configuration

```

Configure headless CI environments using these additional variables:

| Variable | Purpose | Example |
|----------|---------|---------|
| `ANTHROPIC_API_KEY` | Claude backend authentication | `export ANTHROPIC_API_KEY=sk-...` |
| `GRAPHIFY_MAX_WORKERS` | Parallel AST extraction threads | `export GRAPHIFY_MAX_WORKERS=12` |

## Serving the Graph for Team Access

Large teams can centralize graph access by serving the JSON file through an MCP (Model Context Protocol) server. This eliminates the need for each developer to maintain local builds.

```bash
python -m graphify.serve graphify-out/graph.json \
  --transport http --host 0.0.0.0 --port 8080 \
  --api-key "$GRAPHIFY_API_KEY"

```

Clients connect to `http://<host>:8080/mcp` and issue `query_graph` calls against the shared endpoint. This approach leverages the `graphify.serve` module as implemented in the Graphify-Labs/graphify repository.

## Summary

- **Install via `uv` or `pipx`** using the package name `graphifyy` to maintain isolated environments
- **Register the skill** with `graphify install` (global) or `graphify install --project` (repository-scoped) to enable AI assistant integration
- **Maintain `.graphifyignore`** to exclude `node_modules/`, build artifacts, and generated files from indexing
- **Commit `graphify-out/`** to version control while excluding [`cost.json`](https://github.com/Graphify-Labs/graphify/blob/main/cost.json) and cache directories
- **Enable automatic rebuilds** via `graphify hook install` to keep the graph synchronized with code changes
- **Use strict mode** (`GRAPHIFY_HOOK_STRICT=1`) when requiring guaranteed graph-first queries
- **Serve via MCP** for team-wide access using `python -m graphify.serve`

## Frequently Asked Questions

### How does Graphify handle sensitive files and secrets?

Graphify respects your existing `.gitignore` patterns and supports additional exclusions via `.graphifyignore`. Since code parsing uses local Tree-Sitter AST extraction without LLM involvement, sensitive code never leaves your machine. The [`SECURITY.md`](https://github.com/Graphify-Labs/graphify/blob/main/SECURITY.md) file in the Graphify-Labs/graphify repository details the security model ensuring secrets remain local.

### What is the difference between `graphify install` and `graphify install --project`?

The standard `graphify install` command registers the skill globally, writing to [`.agents/skills/graphify/SKILL.md`](https://github.com/Graphify-Labs/graphify/blob/main/.agents/skills/graphify/SKILL.md) in your home directory. The `--project` flag scopes the skill to the current repository only, creating [`./.claude/skills/graphify/SKILL.md`](https://github.com/Graphify-Labs/graphify/blob/main/./.claude/skills/graphify/SKILL.md). Use global registration for personal development machines and project-scoped registration for repository-specific CI/CD pipelines or shared environments.

### Why should I commit the `graphify-out/` directory?

Committing `graphify-out/` ensures all team members start from the same graph structure, eliminating build inconsistencies and reducing onboarding time. The directory contains [`graph.json`](https://github.com/Graphify-Labs/graphify/blob/main/graph.json) (the serialized graph), [`GRAPH_REPORT.md`](https://github.com/Graphify-Labs/graphify/blob/main/GRAPH_REPORT.md) (human-readable analysis), and [`graph.html`](https://github.com/Graphify-Labs/graphify/blob/main/graph.html) (interactive visualization). Exclude only transient files like [`cost.json`](https://github.com/Graphify-Labs/graphify/blob/main/cost.json) and cache subdirectories via `.gitignore`.

### How do I force a complete graph rebuild after major refactoring?

Use the `--force` flag with the extract command to rebuild the graph from scratch, bypassing incremental updates. This is useful after large-scale refactoring that changes import structures or file organization:

```bash
graphify extract . --force

```