Knowledge-Augmented Generation (KAG)

Executive summary

KAG builds a domain knowledge graph (entities + relations) from your private corpus and uses it for structured, multi-hop, auditable reasoning. It is slower and more expensive to build than plain RAG, and it is disabled by default. Use KAG when your domain is entity/relationship-heavy and you need explainability and repeatability.

Image

kag-rag-contrast-pipeline | alt: Diagram contrasting RAG vs KAG: RAG builds vectors for semantic retrieval; KAG extracts entities/relations into a graph DB for multi-hop reasoning; both feed an answer engine that returns minimal context + citations.

RAG vs KAG (why KAG exists)

RAG is great for finding relevant text and citing it. KAG is for reasoning over relationships, constraints, and multi-hop paths. In Conduit, KAG runs alongside RAG (it does not replace it) and is optional by design.

KAG build time scales with corpus size; expect longer sync times than vector indexing.

When KAG is worth it (decision guidance)

KAG is justified when:

You have strong structure and a stable ontology.
Your questions require complex, multi-hop, constraint-heavy queries.
You need high accuracy, explainability, and auditability.
Your workload is entity-centric and factual (systems, inventories, compliance), not open-ended chat.
You can amortize the graph build cost across many workflows and teams.

When NOT to use KAG:

Small or fast-changing corpora.
Exploratory questions where semantic retrieval is sufficient.
You do not have stable entities/IDs or you do not want to invest in schema hygiene.
You only run occasional queries (the graph cost is not amortized).

Prerequisites

See /docs/install for full requirements.
KAG is opt-in (kag.enabled: false by default). It requires a configured extraction provider.
RAG uses Qdrant for vectors. KAG can use FalkorDB for graph traversal; without it, KAG runs in SQLite-only mode (no multi-hop traversal).

If you have not enabled KAG, add a minimal config in ~/.conduit/conduit.yaml:

kb:
  kag:
    enabled: true
    provider: ollama
    ollama:
      model: mistral:7b-instruct-q4_K_M

Cloud providers are supported via config, with keys provided by environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY). See the upstream KAG HLD for full options: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/blob/main/docs/KAG_HLD.md

The workflow (end-to-end)

Image

kag-build-and-query-flow | alt: Flowchart: Add KB sources → kb sync (vectors) → kb kag-sync (graph extraction) → kag-query (multi-hop) → optional MCP integration → validate with test queries.

Step 0 - Start with RAG first (recommended)

Establish a baseline: confirm your sources are correct and retrieval works. This saves hours of KAG debugging later.

Quickstart: /docs/quickstart
CLI reference: /docs/cli

Step 1 - Add sources to your knowledge base

conduit kb add ~/Documents/my-project --name "My Project Docs"
conduit kb add ~/code/my-repo --name "My Repo"
conduit kb list

Best practices: start small, use a known dataset, and keep paths stable so IDs do not churn.

Step 2 - Build / sync the vector index (RAG)

conduit kb sync

Sanity check before graph extraction:

conduit kb search "authentication flow"

Success looks like relevant results with paths and snippets.

Step 3 - Build the knowledge graph (KAG)

conduit kb kag-sync
 
# Optional: limit to a single source
conduit kb kag-sync --source <source-id>
 
# Check extraction status
conduit kb kag-status

What happens:

Entities and relations are extracted from your indexed chunks.
Results are stored in SQLite tables.
If FalkorDB is running, it is used for multi-hop graph traversal.

Expectations:

This can take significantly longer than vector sync.
Time depends on corpus size and your machine.
KAG is a deliberate choice - run it when you need multi-hop structure.

Step 4 - Query the graph (KAG queries)

conduit kb kag-query "Kubernetes"
conduit kb kag-query "authentication" --entities OAuth,JWT --max-hops 2
conduit kb kag-query "container orchestration" --entities Docker,Kubernetes

Notes on flags:

--entities provides comma-separated entity hints to guide matching.
--max-hops controls graph traversal depth (default 2, max 3).

Results include matched entities and relationships, with source references when available.

Step 5 - Use KAG results in an AI workflow

If you are using MCP, Conduit exposes kag_query when KAG is enabled. See /docs/mcp for client wiring.

If you are CLI-first, run conduit kb kag-query and paste the structured output into your AI client for constrained, auditable reasoning.

Performance, cost, and operational reality

KAG adds a graph build step on top of vector indexing. This is the expensive part.

From the KAG HLD (typical per-chunk extraction times):

Ollama Mistral 7B: ~2-5s per chunk on CPU, ~0.5-1s with GPU
OpenAI GPT-4o-mini: ~0.5-1.5s per chunk (API latency)
Validation + storage: ~10-50ms per chunk

Memory planning (KAG HLD estimates):

mistral:7b-instruct-q4_K_M: ~4.1 GB
Qdrant: ~1-2 GB
FalkorDB: ~1-2 GB

Once the graph is built, kag_query is fast (typical ~20-60ms, target under 100ms). If you only need better retrieval, focus on RAG quality (chunking, filters, query phrasing) and skip KAG.

Troubleshooting

Symptom	Likely cause	Fix
`kag-sync` takes a very long time	Large corpus or slow extraction provider	Check `conduit kb kag-status`, limit scope with `--source`, consider `conduit ollama warmup`.
`kag-query` returns nothing	KAG disabled or not synced	Ensure `kag.enabled: true`, run `conduit kb kag-sync`, verify with `conduit kb kag-status`.
Multi-hop paths missing	FalkorDB not running	Run `conduit falkordb status` and start it if needed. SQLite-only mode does not do multi-hop traversal.
Graph DB errors	FalkorDB container not healthy	Restart it: `conduit falkordb stop` then `conduit falkordb start`.
KAG slow on first use	Model cold start	Run `conduit ollama warmup` and retry.

For more, see /docs/troubleshooting and the upstream Known Issues doc: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/blob/main/docs/KNOWN_ISSUES.md

Design notes (PM-grade, short)

Conduit supports KAG because some domains demand multi-hop, auditable reasoning that plain retrieval cannot deliver. It is optional because graph extraction is expensive and adds operational complexity. Keeping KAG CLI-first today makes it repeatable and testable, and avoids unstable GUI-driven flows. The MCP surface stays read-only to protect the KB and keep behavior predictable. RAG remains the default path for most teams, with KAG as a deliberate escalation when structure and auditability matter. The product philosophy is still minimal context and clear citations, even when the graph is involved.