Knowledge Lifecycle

This guide explains how Knowledge Base assets move through the full lifecycle in Keeptrusts — from initial capture or creation, through review and promotion, to runtime recall and audit.

Use this page when

• You need to understand the full lifecycle of a Knowledge Base asset: capture, review, promote, bind, recall, audit.
• You are setting up the promotion workflow for enterprise governance review.
• You want to convert a learned session asset into a curated editable asset.
• You need the state machine diagram for Knowledge Base promotion states.

Primary audience

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

Overview

The Knowledge lifecycle has six stages:

Capture → Review → Promote → Bind → Recall → Audit

Each stage has a corresponding surface in the console, CLI, and API.

Stage 1 — Capture

Knowledge enters the system in two ways:

Manual creation

1. Navigate to Knowledge Base in the left sidebar
2. Click Create asset
3. Choose a kind:
   • Static — write or paste markdown content directly in the editor
   • Upload — upload a file artifact (PDF, JSON manifest, etc.)
   • Git Sync — link a Git repository folder to auto-sync content
4. Set scope (Org-wide, Team, or Personal) and write mode
5. Click Create & continue

Learning from history

1. Navigate to History and open a conversation session
2. Click Create learned knowledge in the action bar
3. The system synthesizes a new Knowledge Base asset using the agent's learning configuration
4. You land on the asset detail — review the content before promoting

CLI equivalent:

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

# Trigger learning from a session
kt history learn --id session_abc123

Stage 2 — Review

After capture, an asset enters draft state.

SMB/B2C orgs: assets go directly to active — review is skipped.

Enterprise orgs (governance review enabled):

1. Open the asset detail
2. Click Submit for review in the Promote dropdown
3. A designated reviewer opens the asset and inspects the content, units, and provenance
4. Reviewer clicks Approve & activate to promote to active, or Archive to discard

Stage 3 — Promote

Promotion moves an asset to active, making it eligible for runtime recall.

Org type	Path to active
SMB/B2C	Created → Active immediately
Enterprise	Draft → In Review → Active

Once active, a learned_session asset can be converted to a curated (editable) static asset:

1. Open an active learned asset
2. Click Promote → Convert to curated
3. The asset becomes fully editable in the markdown editor

To archive an active asset, click Promote → Archive. The asset is no longer recalled but its version history is preserved.

CLI equivalent:

kt knowledge-base promote --id kb_abc123 --action approve
kt knowledge-base promote --id kb_abc123 --action archive

Stage 4 — Bind

An asset must be bound to an agent before it can be recalled at runtime.

From the asset detail

1. Open the Knowledge Base asset detail
2. Navigate to the Bindings tab
3. Select an agent from the Bind to agent dropdown
4. The binding takes effect immediately

From the agent detail

1. Open the agent detail page
2. Navigate to the Configuration tab
3. In the Bound Knowledge section, use Bind existing to attach an active asset, or Quick create & bind to create a new asset and bind it in one step

CLI equivalent:

kt knowledge-base bind --id kb_abc123 --target-type agent --target-id agent_xyz

Stage 5 — Recall

When a request passes through the gateway, the runtime resolves the agent's bound active assets and injects their content as context before policy evaluation.

Recall is automatic — no configuration is needed beyond having an active, bound asset.

The injected context block includes:

{
  "role": "system",
  "content": "context synthesized from bound knowledge",
  "_kt": {
    "source": "knowledge",
    "asset_ids": ["uuid"],
    "version_ids": ["uuid"],
    "unit_ids": ["sha256:..."]
  }
}

Stage 6 — Audit

Every recall creates a citation record linking the response to the specific asset version and units used. Citations appear in:

• History session detail — inline beside captured conversation entries
• Event stream — linked from governance event records
• Knowledge asset detail → Runs tab — aggregated citation counts per run

You can query citations via the API:

curl "https://api.keeptrusts.com/v1/knowledge/{assetId}/citations" \
  -H "Authorization: Bearer $KEEPTRUSTS_API_TOKEN"

Lifecycle state machine

Created (enterprise) → Draft
Created (SMB/B2C)    → Active

Draft          ──"Submit for review"──▶  In Review  ──"Approve"──▶  Active
                                                                        │
Draft (SMB/B2C) ──────────────────────────────────────────────────────▶ │
                                                                        │
Active          ──"Archive"──▶  Archived  ──"Reactivate"──▶  Active   │
Active (learned) ──"Convert to curated"──▶  Active (editable)         ◀┘

Quick reference

Goal	Action
Create a static asset	Knowledge Base → Create asset → Static
Learn from a session	History → open session → Create learned knowledge
Promote to active	Asset detail → Promote dropdown
Bind to an agent	Asset detail → Bindings tab → Bind to agent
View recall citations	Asset detail → Runs tab → citation count
Archive an asset	Asset detail → Promote → Archive

For AI systems

• Canonical terms: Keeptrusts, Knowledge Lifecycle, promotion lifecycle, citation, binding, recall, capture depth.
• Lifecycle stages: Capture → Review → Promote → Bind → Recall → Audit.
• CLI commands: kt knowledge-base create, kt knowledge-base promote, kt knowledge-base bind, kt history learn.
• API endpoint: GET /v1/knowledge/{assetId}/citations.
• Related pages: Knowledge Base, kt knowledge-base, History & Sessions, Agents.

For engineers

• SMB/B2C orgs skip review — assets go directly to active on creation.
• Enterprise orgs require Submit for review → Approve & activate before recall is possible.
• Use kt knowledge-base promote --id <id> --action approve to promote via CLI.
• Recall is automatic for any active, bound asset — no additional configuration is needed.
• Every recall creates a citation record. Query citations at GET /v1/knowledge/{assetId}/citations.

For leaders

• The promotion lifecycle gives governance teams a review gate before AI-facing content goes live.
• Citation audit trails prove exactly which knowledge asset version influenced a specific AI response — critical for compliance evidence.
• Archiving an asset removes it from recall without destroying version history, supporting data retention requirements.
• Memory-to-knowledge promotion preserves full provenance: history session → memory → knowledge asset.

Next steps

• Knowledge Base — Console workbench
• kt knowledge-base — CLI reference
• History & Sessions — Capture conversation sessions
• Agents — Bind Knowledge Base assets to agents