Knowledge Graph
You maintain a queryable project graph at docs/knowledge-graph/. Stdlib Python only — no Graphify, no pip deps, no external URLs in outputs.
Deployment Context
| Host | Mode | Typical use |
|---|
| agent-loom (skill library) | skill-library | Map skill invoke chains, memory, handoffs |
| Any consumer project | application | Map modules, docs, memory for GRAPHIFY-style project management |
Mode auto-detects from authoritative skill-library files: docs/skill-graph.md and docs/SKILL-INDEX.md → skill-library label; otherwise application. Both modes always perform a repo-wide scan — skills, all application source (any path), packages, config, docs, memory, directories. Never skills-only.
Hard Rules
- Full repo, always.
build_graph.py walks the entire repository for source files. .agents/skills/ is indexed as skills, not skipped — but application code in packages/, artifacts/, lib/, etc. must appear as module nodes.
- Query before rebuild. Relational questions →
query_graph.py first.
- Authoritative > inferred.
invokes from docs/skill-graph.md + SKILL-INDEX.md Calls: lines are authoritative; references edges are hypotheses.
- Shrink guard. No
--force unless user confirms or graph is corrupt.
- Handoff sync. Every
memory-handoff → --incremental build.
- No secrets. Skip
.env, credentials, tokens by path name.
Common Rationalizations
| Excuse | Reality |
|---|
| "I'll just grep" | Grep misses invoke chains and handoff lineage. Query the graph. |
| "Graph is stale, full rebuild" | Try --incremental first; authoritative sources may be unchanged. |
| "INFERRED edge = fact" | Read source_file / provenance before acting. |
| "Skip graph on handoff" | Next agent loses relational context. |
| "Need Graphify pip package" | Native stdlib scripts; patterns only, no install. |
| "Only for agent-loom" | Bootstrap in every project via project-setup. |
| "Many skills = skills-only graph" | Wrong — repo-wide scan always runs; read build stdout Why: line. |
Workflow
Step 1 — Check existing graph
Read GRAPH_INDEX.md and GRAPH_REPORT.md when present.
Step 2 — Build or update
python3 .agents/skills/knowledge-graph/scripts/build_graph.py # full repo scan
python3 .agents/skills/knowledge-graph/scripts/build_graph.py --incremental # handoff/default
python3 .agents/skills/knowledge-graph/scripts/build_graph.py --force # override shrink guard
python3 .agents/skills/knowledge-graph/scripts/build_graph.py --strict # fail if source on disk but 0 modules
Stdout always prints: auto mode label, why that label was chosen, and scan layers (skills, code dirs, docs, memory). Read it before assuming skills-only — both modes scan the full repository.
Step 3 — Query
python3 .agents/skills/knowledge-graph/scripts/query_graph.py query "memory handoff connections"
python3 .agents/skills/knowledge-graph/scripts/query_graph.py path memory-handoff knowledge-graph
python3 .agents/skills/knowledge-graph/scripts/query_graph.py explain validate-skills
Cite path, confidence, and provenance for every hit. routing_note in JSON output confirms authoritative-first ordering — prefer invokes edges from skill-graph.md over INFERRED heuristics when choosing skills.
Step 4 — Health audit (optional / validate-skills hook)
python3 .agents/skills/knowledge-graph/scripts/graph_health.py
Step 5 — Report
Summarize: mode, node/edge counts, authoritative vs inferred ratio, hub nodes, communities, top query results.
Handoff Hook (mandatory for memory-handoff)
After appending to agent-handoffs.md:
python3 .agents/skills/knowledge-graph/scripts/build_graph.py --incremental
If build fails, note in handoff ### Graph — do not block save.
Output Format
## Knowledge graph — [full | incremental | query | health]
Mode: [skill-library | application]
Stats: [N] nodes, [E] edges ([A] authoritative invokes)
Hub nodes: [top 3]
Query: "[question]" → [matches with confidence tags]
Files: graph.json, call-graph.json, GRAPH_INDEX.md, GRAPH_REPORT.md
Verification
Red Flags
- Full graph rebuild run before query_graph for relational ask
- Inferred edges override authoritative Calls: from SKILL-INDEX
- Repo walk skipped — partial graph presented as complete
- graph.json stale versus latest handoff not rebuilt
Reference Files
references/schema.md — node/edge types, provenance priorityreferences/integration.md — producers/consumers, project-setup bootstrapscripts/build_graph.py — full/incremental buildscripts/query_graph.py — query, path, explainscripts/graph_health.py — dangling invokes, stale graph, orphan skills
File Output
Append to docs/skill-outputs/SKILL-OUTPUTS.md:
| YYYY-MM-DD HH:MM | knowledge-graph | docs/knowledge-graph/ | [N] nodes, [E] edges, mode=[mode] |
Examples
<examples>
<example>
<input>Build a knowledge graph for this project.</input>
<output>
Ran `build_graph.py` → mode=skill-library, 120 nodes, 412 edges (164 authoritative invokes). Hubs: universal-skill-creator, validate-skills, secure-skill. Saved to `docs/knowledge-graph/`. See `GRAPH_REPORT.md` for communities and suggested questions.
</output>
</example>
<example>
<input>How does memory-handoff connect to knowledge-graph?</input>
<output>
`query_graph.py path memory-handoff knowledge-graph` → 1 hop via `invokes` [EXTRACTED, provenance: memory-handoff/SKILL.md]. Neighbors: memory-capture, agent-handoffs [recorded_in].
</output>
</example>
</examples>
Prune Log
Last pruned: 2026-07-04
- No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)
Impact Report
Knowledge graph: [full/incremental/query/health]
Mode: [skill-library|application] | Nodes: [N] | Edges: [E]
Authoritative invokes: [A] | EXTRACTED: [E] | INFERRED: [I]
Shrink guard: [ok/refused/forced] | Handoff sync: [yes/no]
Consumers notified: [list or n/a]