knowledge-graph

Build, update, and query a persistent project knowledge graph from skills, memory, docs, and code structure — stdlib Python only, no external tools. Dual-mode: skill-library (agent-loom) or applicatio

SKILL.md

GitHub

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

  • graph.json, GRAPH_INDEX.md, GRAPH_REPORT.md exist under docs/knowledge-graph/
  • Build stdout shows repo-wide source layer (not skills-only)
  • Consumer repos with code have module nodes in graph.json stats
  • call-graph.json present when mode=skill-library
  • Shrink guard respected (or --force approved)
  • Query results cite path + confidence + provenance
  • Handoff hook ran --incremental when invoked from memory-handoff
  • No secrets or external URLs in graph artifacts

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 priority
  • references/integration.md — producers/consumers, project-setup bootstrap
  • scripts/build_graph.py — full/incremental build
  • scripts/query_graph.py — query, path, explain
  • scripts/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]