kgrag-usage

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

1. Check registry: kgrag status
2. Query: kgrag query "your pattern here"
3. Extract snippets: kgrag pack "pattern" --out file.md
4. Analyze: Read the snippet file with context

Workflow: Initialize a new repo

1. Navigate to repo: cd ~/repos/myproject
2. Initialize: kgrag init .
3. Verify: kgrag status (should show the new KGs)
4. Query: kgrag query "your search" --kind code to test

Workflow: Rebuild stale KGs

1. Check status: kgrag status (look for "Built: no")
2. If stale: kgrag init /path/to/repo --wipe
3. 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.