Injecting Knowledge into AI Responses

The Keeptrusts knowledge base lets you inject curated context documents into AI requests at the gateway level. This grounds LLM responses in your organization's data without modifying application code. This guide covers the full lifecycle: creating assets, versioning, promotion, binding, runtime injection, and citation tracking.

Use this page when

• You are using the kt knowledge-base CLI to create, version, promote, and bind knowledge assets.
• You need to understand the full knowledge asset lifecycle: create → version → promote → bind → inject → cite.
• You want to configure priority-based injection and monitor citation events in the audit trail.
• You are troubleshooting knowledge injection issues (draft status, missing bindings, stale content).

Primary audience

• Primary: AI Engineers managing knowledge assets for runtime injection into LLM responses
• Secondary: Content Managers authoring and versioning knowledge documents, Platform Engineers configuring bindings

How Knowledge Injection Works

Client request
  → Gateway receives request
    → Retrieves bound active knowledge assets
    → Injects asset content into system context
    → Forwards enriched request to provider
  ← Provider response
    → Gateway records citation metadata
  ← Response returned to client

Decision event includes:
  - knowledge_assets_injected: ["product-docs", "compliance-rules"]
  - citation_records: [{asset: "product-docs", sections: [...]}]

The application sends a normal chat completion request. The gateway transparently injects knowledge before the request reaches the provider.

Creating Knowledge Assets

From a File

kt knowledge-base create \
  --name "product-docs" \
  --file ./docs/product-overview.md

From stdin

cat ./docs/api-reference.md | kt knowledge-base create \
  --name "api-reference" \
  --stdin

With Metadata

kt knowledge-base create \
  --name "compliance-rules" \
  --file ./compliance/eu-ai-act-summary.md \
  --description "EU AI Act compliance requirements for output filtering" \
  --tags "compliance,eu,regulation"

Listing Assets

kt knowledge-base list

NAME               VERSION  STATUS    CREATED              TAGS
product-docs       v1       draft     2026-04-23T10:00:00  docs,product
api-reference      v1       draft     2026-04-23T10:05:00  api,reference
compliance-rules   v1       draft     2026-04-23T10:10:00  compliance,eu

Note: kt kb is a shorthand alias for kt knowledge-base.

Versioning

Every update to an asset creates a new version:

# Update the content
kt knowledge-base update \
  --name "product-docs" \
  --file ./docs/product-overview-v2.md

kt knowledge-base list --name "product-docs"

NAME           VERSION  STATUS    CREATED
product-docs   v1       active    2026-04-23T10:00:00
product-docs   v2       draft     2026-04-23T14:00:00

Only the active version is injected at runtime. Draft versions exist for review before promotion.

Promotion Lifecycle

Assets follow a draft → active → superseded lifecycle:

  create → draft
             ↓ promote
           active  (injected at runtime)
             ↓ new version promoted
           superseded

Promoting an Asset

kt knowledge-base promote --name "product-docs"

This promotes the latest draft version to active. If a previous version was active, it moves to superseded status.

Checking Status

kt knowledge-base inspect --name "product-docs"

{
  "name": "product-docs",
  "current_version": "v2",
  "status": "active",
  "created_at": "2026-04-23T10:00:00Z",
  "promoted_at": "2026-04-23T14:05:00Z",
  "description": "Product overview documentation",
  "tags": ["docs", "product"],
  "content_size_bytes": 4582,
  "bound_configurations": ["production-config"]
}

Binding Assets to Gateway Configurations

Binding tells the gateway which assets to inject. Add bindings in your policy config:

gateway:
  listen_port: 41002
providers:
  targets:
  - id: openai
    provider: 
    base_url: https://api.openai.com/v1
    secret_key_ref:
      env: OPENAI_API_KEY
knowledge_base:
  assets:
  - name: product-docs
    injection: system_context
  - name: compliance-rules
    injection: system_context
    priority: high
policies:
- name: log-all
  type: observe
  action: log

Injection Modes

Mode	Behavior
system_context	Prepends asset content to the system message
user_context	Appends asset content after the last user message

Priority

When multiple assets are bound, priority controls injection order:

Priority	Behavior
high	Injected first (closest to system prompt)
normal	Default — injected in config order
low	Injected last

Runtime Injection in Action

Python Example

Your application code doesn't change — the gateway handles injection:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:41002/v1",
    api_key="kt_gk_...",
)

# No knowledge base content in the request — gateway injects it
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a product assistant."},
        {"role": "user", "content": "What features does our product offer?"},
    ],
)

print(response.choices[0].message.content)
# Response is grounded in your product-docs asset

What the Provider Actually Receives

The gateway enriches the request before forwarding:

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "[Knowledge Context: product-docs]\n<asset content here>\n[End Knowledge Context]\n\nYou are a product assistant."
    },
    {
      "role": "user",
      "content": "What features does our product offer?"
    }
  ]
}

Citation Tracking

The gateway records which knowledge assets were used for each request. Check citations in the decision event:

kt events tail --limit 1 --output json | jq '.[0].citation_records'

[
  {
    "asset": "product-docs",
    "version": "v2",
    "sections_referenced": ["features", "pricing"],
    "injection_mode": "system_context"
  }
]

Querying Citation History

# All events where a specific asset was used
kt events tail --filter "knowledge_asset=product-docs" --limit 20

# Events where no knowledge was injected
kt events tail --filter "knowledge_assets_injected=" --limit 10

Managing Assets at Scale

Bulk Import

# Import all markdown files from a directory
for file in docs/*.md; do
  name=$(basename "$file" .md)
  kt knowledge-base create --name "$name" --file "$file"
  kt knowledge-base promote --name "$name"
done

Deleting an Asset

kt knowledge-base delete --name "outdated-docs"

Warning: Deleting removes all versions. Prefer creating a new version if you want to update content.

Tagging for Organization

kt knowledge-base update \
  --name "product-docs" \
  --tags "docs,product,v2,reviewed"

Filter by tags:

kt knowledge-base list --tag "compliance"

Troubleshooting

Symptom	Cause	Fix
Knowledge not injected	Asset is still in draft status	Run kt knowledge-base promote --name "..."
Old content being used	New version not promoted	Promote the latest version
Response quality degraded	Too much context injected	Reduce asset size or lower priority
422 on create	Invalid characters in asset name	Use letters, digits, hyphens, underscores
Config reload doesn't pick up binding	Gateway didn't reload after YAML change	Save the file and check reload logs

Best Practices

Practice	Why
Keep assets focused and small	Large assets dilute relevance and increase token costs
Use descriptive names and tags	Makes management easier at scale
Promote after review, not on create	Prevents untested content from reaching production
Monitor citation events	Verifies assets are being used effectively
Version rather than delete	Preserves audit trail and allows rollback
Bind compliance assets with priority: high	Ensures regulatory context is always included

Next steps

• Chat Workbench for AI Prototyping — test knowledge injection interactively
• Debugging AI Requests with Events — verify citation records in events
• Routing Across Multiple AI Models — knowledge injection works with all routing strategies

For AI systems

• Canonical terms: kt knowledge-base (kt kb), knowledge asset, versioning, promotion (draft → active), binding, runtime injection, citation tracking, priority.
• CLI commands: kt kb create, kt kb list, kt kb promote, kt kb bind, kt kb version. Create from file or stdin.
• Injection flow: gateway retrieves bound active assets → injects into system context → provider response → citation metadata logged in decision event.
• Best next pages: Chat Workbench for Prototyping, Debugging with Events, Multi-Model Routing.

For engineers

• Create assets with kt kb create --name "..." --file ./path.md (or --stdin for piped content).
• Assets start in draft status — they must be promoted (kt kb promote) to active before injection.
• Bind active assets to gateways with kt kb bind --asset-id ... --gateway-id ....
• The gateway injects bound assets into the system context transparently; applications send normal requests.
• Citation records appear in decision events (knowledge_assets_injected, citation_records fields).
• Use priority: high for compliance assets that must always be included regardless of context budget.
• Version assets rather than editing in place — preserves audit trail and supports rollback.

For leaders

• Knowledge injection grounds LLM responses in curated organizational content, reducing hallucination and liability.
• The promotion lifecycle prevents untested or unreviewed content from reaching production AI responses.
• Citation tracking provides auditable evidence of which knowledge informed each AI response.
• Knowledge assets are a shared organizational investment — monitor citation rates to validate adoption and ROI.
• Priority-based injection ensures regulatory and compliance content is never dropped due to context budget constraints.