66 lines
3.4 KiB
Markdown
66 lines
3.4 KiB
Markdown
---
|
|
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.
|