knowledge-base-framework/AGENT_QUERY_GUIDE.md

id, title, type, status, tags, last_reviewed

id	title	type	status	tags	last_reviewed
meta/agent-query-guide	Agent Query Guide	meta	active	agents jq graph	2026-06-16

Agent Query Guide

index/graph.json is the selected vault's navigation index. MCP is the canonical cross-repository interface: graph_summary, graph_search_nodes, graph_neighbors, and read_note; use refresh_graph(validate=true) to update it.

MCP-only agents use the tools above; shell examples below are for operators, not agent fallback. For those queries, explicitly set KNOWLEDGE_BASE_ROOT and change into that directory. Framework commands require KNOWLEDGE_BASE_FRAMEWORK_ROOT as an explicit path; skill or agent file locations do not identify the data vault.

: "${KNOWLEDGE_BASE_ROOT:?Set the data vault directory explicitly}"
cd -- "$KNOWLEDGE_BASE_ROOT"

Schema:

• Top-level object:
  • version (number): schema version
  • generated_at (string): ISO-8601 UTC timestamp
  • nodes (array): note metadata records
  • edges (array): directed wiki-link records
• Node object (nodes[]):
  • id (string): stable note identifier (usually from frontmatter)
  • title (string): note title
  • path (string): vault-relative markdown path
  • repo (string): repo scope (a repository identifier, or global)
  • type (string): note classification from a controlled vocabulary — hub|project|area|guideline|policy|feature|roadmap|decision|note|meta|reference; absent frontmatter means note, and --validate fails on anything else
  • status (string): lifecycle state (active, draft, deprecated)
  • tags (string array): topic tags
  • last_reviewed (string): YYYY-MM-DD
  • outbound_links (string array): linked note IDs from this note
  • inbound_count (number): number of edges targeting this note
• Edge object (edges[]):
  • from (string): source note ID
  • to (string): target note ID
  • kind (string): link mechanism — normally markdown_link (legacy wiki_link is rejected by --validate and should not appear in a valid graph)
  • type (string): semantic relationship (see vocabulary below); default related
  • anchor_text (string): display / alias text used in the link
  • annotation (string): free-text "what the source needs from the destination" (from the link's link-info, falling back to a trailing — gloss); may be empty
  • weight (number): link weight, currently 1.0

Link syntax

Links are standard markdown links whose target is the stable note id, with an optional JSON brace suffix carrying the relationship and annotation:

[display text](resource/old-deadlines){"type":"supersedes","link-info":"the deadline table this replaces"}

• A bare [text](id) with no brace is a related edge.
• type must be one of the controlled vocabulary; generate-graph.py --validate fails on any other value: related, supersedes, superseded-by, depends-on, part-of, parent, derived-from, see-also, source.
• Legacy [[wiki links]] are no longer accepted: generate-graph.py --validate fails on any that remain. Locate and convert them with python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/list-wiki-links.py" --vault-root "$KNOWLEDGE_BASE_ROOT".

Examples with jq:

# list repos
jq -r '.nodes[].repo' index/graph.json | sort -u

# list the tag vocabulary, most frequent first (tags are matched verbatim)
jq -r '[.nodes[].tags[]?] | group_by(.) | map({tag: .[0], count: length})
  | sort_by(-.count)[] | "\(.count)\t\(.tag)"' index/graph.json

# list top linked notes
jq -r '.nodes | sort_by(-(.inbound_count // 0))[] | "\(.inbound_count // 0)\t\(.id)\t\(.path)"' index/graph.json

# notes in one repo
jq -r '.nodes[] | select(.repo=="<repo>") | "\(.id)\t\(.path)"' index/graph.json

# all projects (PARA category 1)
jq -r '.nodes[] | select(.type=="project") | "\(.id)\t\(.path)"' index/graph.json

# outgoing links from one note
NOTE_ID="<note-id>"
jq -r --arg id "$NOTE_ID" '.nodes[] | select(.id==$id) | .outbound_links[]?' index/graph.json

# incoming links to one note
NOTE_ID="<note-id>"
jq -r --arg id "$NOTE_ID" '.edges[] | select(.to==$id) | .from' index/graph.json | sort -u

# outbound edges of a note WITH relationship type + annotation
jq -r --arg id "$NOTE_ID" '.edges[] | select(.from==$id) | "\(.type)\t\(.to)\t\(.annotation)"' index/graph.json

# all edges of a given relationship type (e.g. what supersedes what)
jq -r '.edges[] | select(.type=="supersedes") | "\(.from) -> \(.to)"' index/graph.json

# what a note supersedes
jq -r --arg id "$NOTE_ID" '.edges[] | select(.from==$id and .type=="supersedes") | .to' index/graph.json

For jg, use the same filters if your local jg is jq-compatible.

Validation:

# validate: non-zero exit on unresolved links, edge types or note types
# outside their vocabularies, OR any remaining legacy [[wiki links]]
python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/generate-graph.py" --vault-root "$KNOWLEDGE_BASE_ROOT" --validate

# regenerate graph and validate
python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/generate-graph.py" --vault-root "$KNOWLEDGE_BASE_ROOT" && python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/generate-graph.py" --vault-root "$KNOWLEDGE_BASE_ROOT" --validate

# list any remaining legacy [[wiki links]] (rejected by --validate) to convert
python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/list-wiki-links.py" --vault-root "$KNOWLEDGE_BASE_ROOT"