| name | kgrag-usage |
| description | Use KGRAG to query across federated knowledge graphs (code, docs, metabolic) and manage cross-KG registries. Triggers when: searching multiple repos/KGs simultaneously, initializing KGs in new repos, querying code patterns across projects, extracting multi-KG snippets, or managing registry status. |
KGRAG Usage
Overview
KGRAG is the federated query layer for PyCodeKG, DocKG, and MetaKG. It maintains a central registry of all knowledge graphs across all repositories and enables cross-KG semantic search, snippet extraction, and batch operations. Use KGRAG when you need to search or analyze code/docs across multiple projects simultaneously.
Core Commands
Query Across KGs
Search all registered knowledge graphs with a natural-language query:
kgrag query "database connection pooling"
kgrag query "API authentication" --kind code -k 5
kgrag query "metabolic pathway" --kind meta --json
Use when: You're searching for patterns, implementations, or documentation across all registered repos. Returns top N results per KG kind (code/doc/meta).
Extract Snippets Across KGs
Get source code snippets ready for LLM context:
kgrag pack "graph traversal logic" --out snippets.md
kgrag pack "authentication middleware" --kind code --context 3
Use when: You need actual source code with context from multiple KGs for analysis or refactoring.
Initialize a Repo with KGRAG
Detect, build, and register all KG layers (code and doc) in a single command:
kgrag init ~/repos/myproject
kgrag init . --layer code --layer doc --wipe
kgrag init ~/repos/myproject --name custom-name
Use when: Setting up a new repo for the first time. Auto-detects which layers (code/doc) apply and registers them in the central registry.
Manage the Registry
List all registered KGs:
kgrag list
kgrag list --kind code
Check registry health:
kgrag status
Returns counts, built/unbuilt status, and missing paths. Use this before querying to ensure all repos are indexed.
Register a new KG manually:
kgrag register ~/repos/project --kind code --name project-code
Remove a KG:
kgrag unregister project-code
Scan for unregistered KGs:
kgrag scan ~/repos --register
Analyze Registry Health
kgrag analyze
Shows cross-KG statistics, coverage, and structural metrics across all registered knowledge graphs.
Common Workflows
Workflow: Find patterns across all repos
- Check registry:
kgrag status
- Query:
kgrag query "your pattern here"
- Extract snippets:
kgrag pack "pattern" --out file.md
- Analyze: Read the snippet file with context
Workflow: Initialize a new repo
- Navigate to repo:
cd ~/repos/myproject
- Initialize:
kgrag init .
- Verify:
kgrag status (should show the new KGs)
- Query:
kgrag query "your search" --kind code to test
Workflow: Rebuild stale KGs
- Check status:
kgrag status (look for "Built: no")
- If stale:
kgrag init /path/to/repo --wipe
- Verify:
kgrag status
Registry Location
The central KGRAG registry is stored at:
~/.kgrag/registry.sqlite
Override with --registry /path/to/registry.sqlite on any command, or set KGRAG_REGISTRY environment variable.
