Tutorial: Setting Up Knowledge Base for Context Injection

This tutorial walks you through creating a Knowledge Base asset, uploading content, promoting it to active, binding it to a gateway agent, verifying context injection in LLM responses, and tracking citations.

Use this page when

• You are creating and uploading Knowledge Base assets for gateway context injection.
• You need to mine, upload, promote, and bind knowledge content to an agent.
• You want the gateway to inject domain-specific context into LLM sessions automatically.
• You are setting up citation tracking for knowledge asset usage.

Primary audience

• Primary: Platform engineers and AI product teams configuring RAG-style context injection
• Secondary: Content owners maintaining knowledge documents; compliance teams auditing citation trails

Prerequisites

• kt CLI installed (first-run tutorial)
• A running Keeptrusts API instance
• An OpenAI-compatible API key exported as OPENAI_API_KEY
• Source documents in a local directory (Markdown, TXT, or PDF)
• curl and jq installed

How Knowledge Base Works

Knowledge Base assets are versioned context resources that the gateway injects into LLM sessions at request time. The lifecycle is:

1. Create — register an asset in the control plane
2. Mine — build a local knowledge manifest from source files
3. Upload — push the manifest to the asset
4. Promote — move the asset version to active status
5. Bind — attach the active asset to an agent target
6. Inject — the gateway includes asset content in LLM context
7. Cite — each use is recorded with citation references

Step 1: Prepare Source Content

Create a directory with your knowledge documents:

mkdir -p knowledge-base/
cat > knowledge-base/refund-policy.md << 'EOF'
# Refund Policy

All purchases are eligible for a full refund within 30 days of purchase.
After 30 days, a prorated refund is available for up to 90 days.
Digital-only purchases are non-refundable after first use.
Contact support@example.com for refund requests.
EOF

cat > knowledge-base/shipping-faq.md << 'EOF'
# Shipping FAQ

Standard shipping takes 5-7 business days.
Express shipping takes 1-2 business days and costs $15.
Free shipping is available for orders over $100.
International shipping is available to 40+ countries.
EOF

Step 2: Create a Knowledge Base Asset

Register the asset in the Keeptrusts API:

kt knowledge-base create \
  --name "Customer Support FAQ" \
  --scope org \
  --kind upload \
  --write-mode raw

Expected output:

✓ Knowledge Base asset created
  ID:    kb_faq_abc123
  Name:  Customer Support FAQ
  Scope: org
  Kind:  upload
  Status: draft

Save the asset ID for later steps:

export KB_ASSET_ID="kb_faq_abc123"

Step 3: Mine Content Locally

Build a knowledge manifest from the source files:

kt knowledge-base mine \
  --source ./knowledge-base/ \
  --output kb-manifest.json

Expected output:

✓ Mined 2 documents → kb-manifest.json
  refund-policy.md  (4 facts extracted)
  shipping-faq.md   (4 facts extracted)
  Total: 8 facts, 1.2 KB

Review the manifest before uploading:

jq '.facts | length' kb-manifest.json
# Output: 8

Step 4: Upload the Manifest

Push the manifest to the Knowledge Base asset:

kt knowledge-base upload \
  --manifest kb-manifest.json \
  --asset-id "$KB_ASSET_ID"

Expected output:

✓ Manifest uploaded to kb_faq_abc123
  Version: v1
  Facts:   8
  Status:  draft

Step 5: Promote to Active

Promote the draft version so the gateway can use it:

kt knowledge-base promote --id "$KB_ASSET_ID" --version v1

Expected output:

✓ Version v1 promoted to active
  Asset: kb_faq_abc123 (Customer Support FAQ)

Verify the status:

kt knowledge-base get --id "$KB_ASSET_ID"

The output should show status: active and active_version: v1.

Step 6: Bind the Asset to an Agent

Attach the Knowledge Base asset to a gateway agent target:

kt knowledge-base bind \
  --id "$KB_ASSET_ID" \
  --target-type agent \
  --target-id agent_support_001

Expected output:

✓ Bound kb_faq_abc123 → agent_support_001

Step 7: Configure the Gateway

Update policy-config.yaml to reference the agent with knowledge base injection:

version: '1'
providers:
  targets:
  - id: openai
    provider: openai
    secret_key_ref:
      env: OPENAI_API_KEY
policies:
- name: basic-filter
  type: content_filter
  action: flag
  config:
    categories:
    - hate
    threshold: medium

Start or reload the gateway:

kt gateway run --policy-config policy-config.yaml --port 41002

Step 8: Verify Context Injection

Send a query that should trigger knowledge base context:

curl -s http://localhost:41002/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Keeptrusts-Agent: agent_support_001" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "What is your refund policy?"}
    ]
  }' | jq '.choices[0].message.content'

The response should reference the 30-day full refund and 90-day prorated refund from the knowledge base.

Step 9: Track Citations

Check citation records for knowledge base usage:

kt events tail --last 5 --format json | jq 'select(.citations) | {
  event_id: .id,
  citations: .citations
}'

Expected output:

{
  "event_id": "evt_xyz789",
  "citations": [
    {
      "asset_id": "kb_faq_abc123",
      "fact_id": "refund-policy-full-30-days",
      "relevance": 0.95
    }
  ]
}

Step 10: Update Knowledge Base Content

When source content changes, mine, upload, and promote a new version:

kt knowledge-base mine --source ./knowledge-base/ --output kb-manifest-v2.json
kt knowledge-base upload --manifest kb-manifest-v2.json --asset-id "$KB_ASSET_ID"
kt knowledge-base promote --id "$KB_ASSET_ID" --version v2

Or use the sync shortcut to mine and upload in one step:

kt knowledge-base sync --source ./knowledge-base/ --asset-id "$KB_ASSET_ID"
kt knowledge-base promote --id "$KB_ASSET_ID" --version v2

Summary

• kt knowledge-base create registers an asset in the control plane
• kt knowledge-base mine builds a manifest locally from source files
• kt knowledge-base upload pushes the manifest; sync combines mine + upload
• kt knowledge-base promote activates a version for gateway injection
• kt knowledge-base bind attaches the asset to an agent target
• Citations are tracked per request in decision events

For AI systems

• Canonical terms: Keeptrusts Knowledge Base, kt knowledge-base (kt kb), asset, manifest, promote, bind, context injection, citation.
• CLI commands: kt knowledge-base create, kt knowledge-base mine, kt knowledge-base upload, kt knowledge-base promote, kt knowledge-base bind, kt knowledge-base list, kt knowledge-base citations.
• Lifecycle: create → mine → upload → promote → bind → inject → cite.
• Asset statuses: draft, active, deprecated.
• Best next pages: Custom Policy Chains, Event Tailing, Gateway First Run.

For engineers

• Prerequisites: kt CLI, running Keeptrusts API, OPENAI_API_KEY, source documents (Markdown, TXT, or PDF), curl and jq.
• Mine: kt knowledge-base mine --source ./knowledge-base/ --output manifest.json builds the content manifest.
• Upload: kt knowledge-base upload --asset-id <id> --manifest manifest.json.
• Promote: kt knowledge-base promote --asset-id <id> moves from draft to active.
• Bind: kt knowledge-base bind --asset-id <id> --agent <agent-id> attaches to a gateway agent.
• Verify: send a chat request and check the response includes injected context; kt knowledge-base citations shows usage records.

For leaders

• Knowledge Base enables AI assistants to answer with company-specific context (policies, FAQs, product docs) rather than general knowledge.
• Citation tracking provides auditability — you can see which knowledge assets influenced each response.
• Versioned assets support content governance: promote when reviewed, deprecate when outdated.
• Binding controls which agents access which knowledge, enabling information boundaries between teams.

Next steps

• Custom Policy Chains — combine knowledge injection with policy enforcement
• Event Tailing — monitor knowledge injection and citation events
• Export Compliance Evidence — include knowledge citations in audit exports