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.

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)

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

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.

Related pages

• /docs/install
• /docs/quickstart
• /docs/cli
• /docs/mcp
• /docs/troubleshooting
• Architecture Overview
• /docs/admin