/graph-query

Query the vault's knowledge graph index using natural language or structured queries.

Usage

code

/graph-query ADRs with status proposed
/graph-query high priority tasks
/graph-query orphaned notes
/graph-query broken links
/graph-query backlinks to Project - MyProject
/graph-query --type=Adr --status=accepted

Instructions

When the user invokes /graph-query or asks to query the graph index:

Phase 1: Ensure Index Exists

Before executing any query, check if the graph index exists:

•
Check if .graph/index.json exists
•
If not found, inform the user and offer to build it:
code
```
The graph index needs to be generated first.
Running: npm run graph:build
```
Execute: npm run graph:build
•
If index exists but is stale (>1 day old), optionally suggest rebuilding

Phase 2: Parse the Query

Understand what the user is asking for. The query system supports:

Natural Language Patterns:

Pattern	Interpretation
"ADRs with status proposed"	`--type=Adr --status=proposed`
"high priority tasks"	`--type=Task --priority=high`
"active projects"	`--type=Project --status=active`
"orphaned notes"	`--orphans`
"broken links"	`--broken-links`
"stale notes"	`--stale`
"meetings about kafka"	`--type=Meeting --search=kafka`
"backlinks to X"	`--backlinks="X"`
"notes mentioning aws"	`--search=aws`

Structured Parameters:

Parameter	Description	Example
`--type=`	Filter by note type	`--type=Adr`, `--type=Project`
`--status=`	Filter by status	`--status=proposed`, `--status=active`
`--priority=`	Filter by priority	`--priority=high`
`--search=`	BM25 relevance search (ranked results)	`--search="kafka integration"`
`--backlinks=`	Find notes linking to target	`--backlinks="Project - MyProject"`
`--orphans`	List orphaned notes
`--broken-links`	List broken wiki-links
`--stale`	List notes >6 months old
`--stats`	Show index statistics
`--json`	Output as JSON with scores

Phase 3: Execute Query via CLI

Run the appropriate command:

bash

# Natural language query
node scripts/graph-query.js "ADRs with status proposed"

# Structured query
node scripts/graph-query.js --type=Adr --status=proposed

# Special queries
node scripts/graph-query.js --orphans
node scripts/graph-query.js --broken-links
node scripts/graph-query.js --stats

# JSON output (for further processing)
node scripts/graph-query.js --type=Task --priority=high --json

Phase 4: Format Response

Present results as a markdown table. For search queries, results are ranked by BM25 relevance score:

markdown

## Search Results

Found **X** result(s) for: "kafka integration"

| Score | Type | Title |
|-------|------|-------|
| 14.65 | Page | Kafka Integration Solution Architecture |
| 11.32 | Integration | ERP → Data Lake |
| 9.45 | System | Data Platform |

*Results ranked by BM25 relevance score (higher = more relevant)*

For type/status queries (no search term), show standard format:

markdown

## Query Results

Found **X** result(s) for: "ADRs with status proposed"

| Type | Status | Priority | Title |
|------|--------|----------|-------|
| Adr | proposed | high | ADR - API Gateway Selection |
| Adr | proposed | medium | ADR - Event Streaming Platform |

### Quick Actions
- View a note: `[[ADR - API Gateway Selection]]`
- Find related: `/graph-query backlinks to "ADR - API Gateway Selection"`
- Check quality: `/graph-query --stats`

For special queries like orphans or broken links, format appropriately:

markdown

## Orphaned Notes Report

Found **8** orphaned notes (notes with no backlinks)

| Type | Title | Last Modified |
|------|-------|---------------|
| Page | Database Migration Checklist | 2025-11-15 |
| Project | Research - Event-Driven Architecture | 2025-10-20 |

### Recommendations
- Consider linking from relevant MOCs
- Archive if no longer needed
- Use `/archive <note>` to soft-archive

Query Examples

By Type

code

/graph-query all ADRs
/graph-query projects
/graph-query active tasks
/graph-query meetings

By Status/Priority

code

/graph-query ADRs with status proposed
/graph-query high priority tasks
/graph-query completed projects
/graph-query draft ADRs

Search

code

/graph-query notes about kafka
/graph-query mentions of aws bedrock
/graph-query "integration pattern"

Relationships

code

/graph-query backlinks to Project - MyProject
/graph-query orphaned notes
/graph-query broken links

Quality

code

/graph-query stale notes
/graph-query --stats

Notes

•The graph index is stored in .graph/ directory (git-ignored)
•Index is automatically excluded from vault searches
•Rebuild index after major changes: npm run graph:build
•Use npm run graph:watch for automatic rebuilding during active work
•Results are limited to 50 items by default; use --json for full results
•Search uses BM25 ranking - results are sorted by relevance score, not just filtered
•BM25 weights rare terms higher (IDF) and normalises for document length
•JSON output includes relevance scores for programmatic use

Related Skills

•/orphans - Dedicated orphan analysis with recommendations
•/broken-links - Detailed broken link analysis with fixes
•/quality-report - Comprehensive vault quality report
•/vault-maintenance - Full maintenance check including graph analysis