Knowledge Base

The Knowledge Base page is the primary workbench for creating and managing the context resources that the Keeptrusts gateway recalls at runtime. Knowledge Base assets can hold curated documents, policies, learned conversation summaries, uploaded manifests, task reports, replay exports, or other durable context that agents should draw on when processing requests.

The Knowledge Base now has two primary routes:

• /knowledge is the project hub. Use it to create top-level Knowledge projects, review project health, and jump into the right workspace.
• /knowledge/projects/[projectId] is the file-manager workspace. It provides the folder tree on the left, the file list or grid in the center, and the preview plus sync rail on the right.

Use the project workspace for folder organization, connector-first imports, uploads, project sharing, and save-to-knowledge flows. Use /knowledge/[assetId] for lifecycle work such as promotion, bindings, versions, and citations.

Use this page when

• You want to create, organize, or promote Knowledge Base assets in the console.
• You need to understand folder organization, sync health, write modes, or the promotion lifecycle.
• You are binding assets to agents so they are recalled at gateway runtime.
• You want to use the CLI (kt knowledge-base / kt kb) for local mining, bulk upload, or asset management.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

What a Knowledge Base asset is

A Knowledge Base asset is a versioned, scoped, and governable content store. Unlike ephemeral session context, assets are:

• Versioned — every content update creates a new immutable version; previous versions are preserved for audit
• Governable — assets move through a promotion lifecycle (draft → reviewed → active) before they can be recalled at runtime
• Auditable — every recall is recorded as a citation linked to the originating session or governance event
• Project-aware — assets live inside Knowledge projects, can be nested into folders within that project, inherit collaboration through project sharing, and retain stable provenance metadata across chat, task, replay, and memory saves

Default Organization Knowledge Base

Every new organization receives a top-level Knowledge project named "Organization Knowledge" during bootstrap. Inside that project, Keeptrusts seeds a default Knowledge Base asset named "Organization Knowledge Base". This asset is:

• Placed inside the default Organization Knowledge project so /knowledge opens to a populated project hub instead of an empty state.
• Automatically populated with a structured snapshot of your entire organization: users, teams, roles, policies, agents, configurations, gateways, API tokens (metadata only — never actual key values), knowledge assets, connectors, wallet balances, governance events, escalations, chat history, tasks, learning runs, exports, model pricing, and notifications.
• Bound to the default "Assistant" agent so the agent can answer questions about your organization immediately.
• Periodically refreshed (default: every hour) to stay current as your organization changes. Each refresh creates a new version only when the content has actually changed.
• Editable — you can customize or replace the content at any time.

The default agent also ships with auto-learning enabled (schedule: on_session_close), meaning every completed chat session automatically creates learned knowledge. Combined with the org-context snapshot, this gives the default agent comprehensive awareness of your organization from day one.

Security boundaries

The org-context snapshot never includes:

• Actual API key or token values (only names, prefixes, types, and expiry metadata)
• Password hashes or credentials
• Webhook secrets or encryption keys
• Raw configuration YAML (only names and descriptions)

Refresh schedule

The org-context refresh worker runs on a configurable interval (default: 1 hour). Set KEEPTRUSTS_ORG_CONTEXT_REFRESH_INTERVAL_SECS to adjust the interval. A new version is created only when the content hash changes, preventing unnecessary version churn on quiet organizations.

Asset kinds

Kind	Description
static	Manually curated content — written or edited directly in the markdown editor
upload	Content uploaded through the console or API as a file artifact
git_sync	Content synced from a linked Git repository
learned_session	Automatically created from a conversation session via the learning system. Not manually creatable.

Promotion lifecycle

New assets start in draft state and must be promoted before they are eligible for gateway recall.

State	Description
draft	Initial state — not recalled by gateways. Edit content freely.
in_review	Submitted for reviewer approval (enterprise orgs with governance review enabled).
active	Fully promoted — eligible for gateway recall by bound agents.
archived	Soft-deleted — no longer recalled, but version history is preserved.

SMB/B2C orgs (without governance review enabled): assets go directly to active on creation. The Promote dropdown shows Archive as the primary action.

Enterprise orgs: assets start as draft. Use "Submit for review" → "Approve & activate" to move through the lifecycle.

Write modes

Write mode controls how Knowledge Base content is surfaced and written back at runtime:

Write mode	Behaviour
raw	Full content is injected and written back as-is (default)
facts_only	Only structured facts are extracted and written back
metadata_only	Only metadata and labels are included in recall
disabled	Content is stored but not injected at runtime

Project sharing

Knowledge assets are organization-owned. Instead of per-asset ownership scopes, the Knowledge Base uses project sharing to control who collaborates on a project and its nested folders:

Permission	Meaning
viewer	Can inspect the shared folder and its files
editor	Can add or update files in the shared folder
manager	Can manage sharing and collaborative changes for the folder

Creating a Knowledge project

1. Navigate to Knowledge Base in the left navigation.
2. Select New project.
3. Give the project a name and optional description.
4. Open the new project's workspace at /knowledge/projects/[projectId].

Creating a Knowledge Base asset

1. Navigate to Knowledge Base in the left navigation.
2. Open the destination project workspace.
3. Create or select a destination folder inside that project.
4. Use Import from connector, Upload file, or Save to Knowledge Base from another surface.
5. Review duplicate handling and destination folder selection.
6. Open the detail page when you need lifecycle actions such as promotion or bindings.

Editing content

The Content tab on the asset detail page provides a markdown editor for static assets. Each save creates a new immutable version. Use the Versions tab to view the full version history.

Saving a chat reply into Knowledge Base

You can turn a useful assistant response into reusable knowledge without leaving the chat workbench:

1. In Chat, open the actions for a completed assistant reply and click Save to Knowledge Base
2. Pick the destination project and folder plus duplicate handling
3. Save the reply as a discrete file with origin metadata
4. Review the file in Knowledge Base and promote or bind the resulting asset as needed

Managing bindings

A binding links an asset to an agent so it is eligible for runtime recall. Only active assets with a binding to the requesting agent are recalled.

1. Open the asset detail
2. Go to the Bindings tab
3. Click Bind to agent and select the target agent from the dropdown
4. The binding takes effect immediately for requests through that agent

CLI integration

The CLI provides additional workflows for local mining, bulk upload, and asset management:

# List knowledge base assets
kt knowledge-base list
kt kb list                          # short alias

# Create an asset
kt knowledge-base create --name "Product FAQ" --scope org --kind static

# Mine content from local files
kt knowledge-base mine --source ./knowledge-base/ --output manifest.json

# Upload a manifest to an asset
kt knowledge-base upload --manifest manifest.json --asset-id kb_abc123

# Mine and upload in one step
kt knowledge-base sync --source ./knowledge-base/ --asset-id kb_abc123

# Bind an asset to an agent
kt knowledge-base bind --id kb_abc123 --target-type agent --target-id agent_xyz

Compatibility note: kt loads is a deprecated alias for kt knowledge-base. It continues to work in the current release but will be removed in a future version. Migrate scripts to use kt knowledge-base or kt kb.

Learning from history

You can create a learned_session asset from any captured conversation:

1. Navigate to History and open a session
2. Click Create learned knowledge in the session action bar
3. The system synthesizes a knowledge asset from the session using the agent's learning configuration
4. You land on the new asset's detail page — review the content and promote it to active when ready

You can also save a replay summary directly from the History detail page into the folder-based Knowledge Base workspace when you want a human-readable debugging file rather than a learned synthesis.

Agent-Owned Context Plan and Promotion Model

Knowledge assets participate in the deterministic Agent Context Plan — a bounded, ordered context block resolved before each request:

• Each agent has a context policy defining token budgets per lane: frozen_memory, ranked_recall (memory + knowledge), and working_context.
• Knowledge assets are ranked by binding strength, priority, freshness, and request-text relevance (prompt-aware retrieval).
• The resolved plan produces a stable plan_hash so any gateway in the pool can detect context drift without re-resolving.

Memory promotion

High-confidence durable memories can be promoted into draft knowledge assets:

1. A memory crosses the agent's promotion_threshold (confidence-based).
2. The operator or automated workflow invokes promotion.
3. A new knowledge asset is created in draft status with lineage back to the source memory_id and originating history_session_id.
4. The draft is reviewed and promoted to active when ready.

This preserves the full provenance chain: history session → memory → knowledge asset.

Token accounting

Each entry in a session records per-lane token consumption:

• user_prompt_tokens — user message
• memory_tokens — injected memories
• knowledge_tokens — injected knowledge assets
• working_context_tokens — episodic history recall

These fields appear in history detail views and are available via the history API.

For AI systems

• Canonical terms: Keeptrusts, Knowledge Base project hub, Knowledge project workspace, folder tree, file preview, sync health, project share, connector import, save-to-knowledge, binding, citation, promotion lifecycle, learned_session, static, upload, git_sync.
• CLI commands: kt knowledge-base list, kt kb create, kt kb mine, kt kb upload, kt kb sync, kt kb bind.
• Promotion states: draft, in_review, active, archived.
• Write modes: raw, facts_only, metadata_only, disabled.
• Collaboration model: assets are org-owned and Knowledge projects carry viewer, editor, or manager sharing rules that apply to nested folders.
• Related pages: Knowledge Lifecycle, kt knowledge-base, History & Sessions, Agents.

For engineers

• Only active assets with a binding to the requesting agent are recalled at runtime. Draft or archived assets are never injected.
• Each content save creates a new immutable version — use the Versions tab to audit changes.
• /knowledge is the project hub, /knowledge/projects/[projectId] is the file-manager workspace, and /knowledge/[assetId] stays the asset lifecycle and detail surface.
• kt loads is deprecated. Migrate scripts to kt knowledge-base or kt kb.
• Token accounting fields (knowledge_tokens, memory_tokens) appear in history detail views and the API.
• Use kt knowledge-base mine --source ./docs/ --output manifest.json to bulk-prepare content locally before uploading.

For leaders

• Knowledge Base assets are governable: enterprise orgs require reviewer approval before assets reach production agents.
• Every runtime recall is recorded as a citation — auditors can trace which content influenced which response.
• Folder sharing lets you control who collaborates on sensitive context without duplicating files across separate personal or team inventories.
• The promotion lifecycle prevents unreviewed content from reaching live AI responses.

Next steps

• Knowledge Lifecycle — Full capture-to-recall guide
• kt knowledge-base — CLI Knowledge Base management
• History & Sessions — Learn from conversation history
• Agents — Bind Knowledge Base assets to agents