---
description: Manage per-project Graphify knowledge graphs — onboard, update, remove, and query codebase structure for the current repo
---

**Scope:** project graph at `./graphify-out/graph.json` — codebase structure and module relationships for the current repo only. For cross-project evergreen knowledge, use `memory-vault`.

## Onboard

Assessment-first onboarding per ADR-017. Do not run `graphify extract` bare — graphify does not honor `.gitignore`; it uses a separate `.graphifyignore` (same syntax). Without one, repos with `node_modules/` or other dependency/build/cache dirs will walk every file and route all non-code content through the slow Ollama doc pass. Only non-code files hit the LLM; code uses the free tree-sitter AST pass.

**Step 1 — Assess the repo.** Survey before touching graphify. List top-level dirs and get a file-type/size profile. Identify:

- **Exclude candidates:** dependency dirs (`node_modules/`, `vendor/`, `venv/`, `.venv/`); build/generated output (`dist/`, `build/`, `.next/`, `target/`, `pb_public/`); caches (`.vite/`, `coverage/`, `__pycache__/`); VCS internals (`.git/`); lockfiles; databases and logs (`*.db`, `*.log`); binary/media blobs; and `graphify-out/` itself.
- **Include candidates:** source code (free AST pass) and genuine docs (README, design docs, ADRs).

Weigh cost by non-code file count, not directory size. Surface borderline cases (migrations, seeds, fixtures, sample data) for a human call — do not make that judgment unilaterally.

**Step 2 — Draft `.graphifyignore`.** Write `.gitignore`-syntax rules from the assessment. Add a one-line rationale comment above each rule so the intent is clear later.

**Step 3 — Confirm with the user.** Present the proposed ignore list and rationale; adjust per feedback before writing anything. This is a judgment step, not a mechanical one — do not skip it.

**Step 4 — Write the files.** Write `.graphifyignore` at the repo root. Ensure `graphify-out/` is in the project's `.gitignore`; add it if missing.

**Step 5 — Build the graph.**

```bash
graphify extract . --backend ollama --model qwen2.5-coder:7b
graphify cluster-only .
```

Confirm `./graphify-out/graph.json` exists before reporting done.

## Incremental update

```bash
# Routine edits (no renames/deletions/moves)
graphify update .

# Structural changes (renames, deletions, directory moves)
graphify update . --force
```

Suggest running `graphify update .` after sessions involving significant refactoring, and `--force` after any renames or directory reorganization.

## Remove

Delete `graphify-out/` when the project is inactive or the graph is too stale. The graph is always rebuildable via the onboard sequence. Leave the `.gitignore` entry even after removal.

## Query

```bash
graphify query "<question>" --graph ./graphify-out/graph.json
```

For traversal mechanics (`graphify path`, `graphify explain`, `--budget`, `--dfs`), see `memory-vault` — query mechanics are not duplicated here.

## Graph path discovery

`session_context.py` injects the absolute path to `graphify-out/graph.json` when it exists. If no graph path is present in session context and you are working in a project context, suggest running the onboard sequence before proceeding with knowledge queries.

## Constraints

- **Never commit `graphify-out/`** — it is local, disposable, and rebuildable.
- Model is `qwen2.5-coder:7b` — do not substitute.
- The `.gitignore` entry for `graphify-out/` must survive even if the directory is deleted.