---
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 what to exclude using the taxonomy below, then surface borderline cases (migrations, seeds, fixtures, sample data) for a human call — do not make that judgment unilaterally.

**Meta-principle:** index what a human authored as this project's source and knowledge; exclude anything that is (a) fetched, (b) generated/derived/compiled, (c) cached, (d) tooling/environment config, (e) bulk data or binary, or (f) secret. Recognize the KIND even in an unfamiliar stack — the example names are illustrative, not exhaustive. Weight remaining cost by **non-code file count**: only non-code files go through the Ollama doc pass (~15–25s each), so a stray docs-heavy tooling dir or a large lockfile is what blows up runtime, not source-file count.

**Default-exclude categories:**

| # | Category | Illustrative names |
|---|----------|--------------------|
| 1 | Fetched dependencies | `node_modules/`, `vendor/`, `.venv/`/`venv/`, `target/`, `Pods/`, `site-packages/` |
| 2 | Build / compiled / generated output | `dist/`, `build/`, `out/`, `.next/`, `.svelte-kit/`, `bin/`, `obj/`, `*.min.js`, source maps, generated dirs |
| 3 | Caches | `.cache/`, `.vite/`, `.turbo/`, `__pycache__/`, `.pytest_cache/`, `.gradle/`, `.terraform/` |
| 4 | VCS internals | `.git/`, `.hg/`, `.svn/` |
| 5 | Editor / IDE & AI-assistant tooling dirs | `.vscode/`, `.idea/`, `.claude/`, `.codex/`, `.cursor/`, `.pi/`, `.impeccable/`, `.husky/` — these are full of markdown that floods the doc pass |
| 6 | Lockfiles (machine-generated, hit the LLM) | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `poetry.lock`, `Cargo.lock`, `composer.lock`, `Gemfile.lock` |
| 7 | Coverage / reports / logs | `coverage/`, `htmlcov/`, `test-results/`, `playwright-report/`, `*.log`, `logs/` |
| 8 | Data, databases & bulk dumps | `*.db`, `*.sqlite`, `pb_data/`, large `*.csv`/`*.json`/`*.parquet`, snapshots — keep small schema/seed files that define structure; drop bulk data |
| 9 | Binary & media | images, audio, video, fonts, archives, PDFs/Office docs unless they ARE the knowledge |
| 10 | Secrets / env | `.env`, `*.pem`, credentials |
| 11 | graphify-out/ | graphify's own output — avoid self-ingestion |

For non-coding/writing/research projects the same principle holds but offenders shift: exported duplicates of source notes (PDF/HTML/DOCX exports of the same markdown — index the source, not the export), attachment/media folders, app config (`.obsidian/`), and archived old-version folders.

- **Include candidates:** source code (free AST pass) and genuine docs (README, design docs, ADRs).

**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 qwen25-coder-7b-16k
graphify cluster-only .
```

`qwen25-coder-7b-16k` is the `ollama_model` in `config.yaml` — a 16k-context build of qwen2.5-coder:7b. Its larger context window reduces the number of chunks per document, which is the main onboarding-speed lever: inference is GPU-bound (~65 tok/s), so the cost is chunk-count × generation, not hardware. Note: `GRAPHIFY_OLLAMA_NUM_CTX` does not propagate through graphify's OpenAI-compatible path; the larger context comes from the model's own Modelfile.

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 `qwen25-coder-7b-16k` (config.yaml `ollama_model`) — do not substitute. This is a 16k-context build of qwen2.5-coder:7b; using the smaller base model silently reduces context and increases chunk count.
- The `.gitignore` entry for `graphify-out/` must survive even if the directory is deleted.