kg

name	kg
category	knowledge
description	Load relevant entities from the bstack knowledge graph (research/entities/) for a given topic. Two-tier scoring: tier-1 (catalog-only, ~5ms — slug + tags + claim + links + sources match against docs/knowledge-index.md) is the fast first pass and the only stage for high-confidence exact-slug/tag queries; tier-2 (body-grep fallback, ~300ms — auto-fires when tier-1 returns < N matches OR its best hit is below the confidence floor, default 18) recovers topics whose vocabulary appears in entity prose but not the dense catalog (hit rate jumps from 70% → 100% on representative queries; this is hit rate ≥1, not true recall@N). Surfaces top-N entity bodies as a single context block the agent reasons over. This is a LOAD skill, not a query DSL — querying is what the agent does once loaded. Implements the LLM-as-index architecture (BRO-1223): substrate canonical, one projection (catalog) routes, agent IS the query engine. Empirical: peak per-query context drops from 29% → 4.6% of 1M (6.3× reduction); cumulative session tokens 23.8× fewer over 10 queries. Default N=10 entities; override with --n. Tier-2 auto-fires on few-OR-weak tier-1 hits (confidence gate, default --tier2-floor 18; BRO-1426 lifts R@5 0.871→0.952, MRR 0.868→0.968 with no flag); force unconditionally with --body-search, disable the gate with --tier2-floor 0. Routing-quality flags (BRO-1422): --terms (query expansion — score agent-supplied synonyms/variants alongside the topic), --expand 1 (graph 1-hop — also load related: neighbours of top hits, capped at --n extra, total ≤ 2x--n), --explain (per-signal score trace); hub-aware tiebreak always on. Output: catalog header + ranked entity blocks with full body. USE WHEN load knowledge graph, kg load, load entities, route to entities, load context for, what do we know about, what entities are relevant to, surface knowledge on, browse the graph for, find entities about, semantic load, topical load, agent-as-index load. NOT FOR PAI session retrieval (use ContextSearch), web research (use Research), Knowledge Archive ingest (use Knowledge), or entity write/edit operations (those are direct Read+Edit + commit per the AGENTS.md §P6 sub-rule on substrate-edit-as-inference-persistence).
argument-hint	["topic"]
effort	low

kg — knowledge graph loader

Load relevant entities for: $ARGUMENTS

Purpose

The bstack knowledge graph lives at research/entities/**/*.md (~250 entities, ~1.1 MB, ~280k tokens). It fits in any 1M-context model with 3.5× headroom — meaning the LLM is the index. This skill performs the routing step: reads the dense catalog at docs/knowledge-index.md, ranks entities by topical relevance, and surfaces the top-N bodies as a single context block.

The agent does the rest: traversal, inference, contradiction detection, semantic comparison — all by reading. There is no SQL layer, no embeddings, no typed-edge schema. The substrate is canonical; the catalog routes; the agent reasons.

Usage

/kg load <topic>              # default: top 10 (two-tier; tier-2 auto-fires on few OR weak tier-1 hits)
/kg load <topic> --n 20       # widen the load
/kg load <topic> --type tool  # restrict by entity type
/kg load <topic> --terms "recall,persistence"  # query expansion: score synonyms/variants too
/kg load <topic> --expand 1   # also load 1-hop related: neighbours of the top hits
/kg load <topic> --explain    # show the per-signal score trace for each loaded entity
/kg load <topic> --body-search  # force tier-2 body grep unconditionally
/kg load <topic> --tier2-floor 0  # disable the confidence gate (tier-2 only on count<--n)
/kg load <topic> --json       # machine-readable output (for piping)
/kg                           # catalog-only mode: print summary stats + top hubs

Routing-quality flags (BRO-1422)

These raise routing recall without leaving the LLM-as-index architecture (no sidecar, no embeddings). The gap was never reasoning — a frontier agent reranking the top-N already beats a small reranker model — it was that whatever routing drops below N, the agent never sees.

• --terms (query expansion). The single biggest recall lever. The catalog scorer matches literal terms; pass the synonyms/variants the topic implies and they're scored alongside it. The agent IS the query expander here — no headless expansion model needed (that's the only reason QMD fine-tunes one). Repeatable (one value per flag); each value may be comma/space-separated. Topic terms keep priority on ties.
• --expand 1 (graph 1-hop). After ranking, also pull the related: neighbours of the top hits — the structural advantage flat-document search (BM25, vector) structurally cannot offer. Automates the "reading frontier" (Phase 3). Neighbours are deduped against the primary set, ranked by their own relevance then in-degree, and capped at --n extra entities (so total load is ≤ 2×) — a hub neighbour (e.g. , in-degree 100+) can't explode the load. Each is marked (its immediate parent). Only 1 hop is supported for now (values >1 clamp to 1, so provenance always resolves); under , expansion is limited to that type (a one-line note is printed) since cross-type edges aren't resolved.