/graph-query

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

Usage

/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:

1. Check if .graph/index.json exists

2. If not found, inform the user and offer to build it:

   The graph index needs to be generated first.
   Running: npm run graph:build
   

   Execute: npm run graph:build

3. 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:

# 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:

## 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:

## 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:

## 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

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

By Status/Priority

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

Search

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

Relationships

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

Quality

/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