Skip to main content
Browse docs
By Audience
Getting Started
Configuration
Use Cases
IDE Integration
Third-Party Integrations
Engineering Cache
Console
API Reference
Gateway
Workflow Guides
Templates
Providers and SDKs
Industry Guides
Advanced Guides
Browse by Role
Deployment Guides
In-Depth Guides
Tutorials
CLI Reference
Overview
CLI Fundamentals
OverviewInstallationAuthenticationHealth CheckInitialize ConfigCommand Groups
Run and Manage Gateway
Investigate, Test & Export
Resources & Integrations
Knowledge BaseHistorySecretsConfig VariablesControlWebhooksAgents
IAM & Team Administration
Spend & Budgets
Advanced Features
Policy Reference
FAQ

kt history

The kt history command group manages conversation history sessions captured by the gateway runtime. Use it to list sessions, inspect one session, delete a session with confirmation, synthesize a local condensed summary, or turn a captured session into learned knowledge.

Use this page when​

  • You need to list, inspect, or delete conversation history sessions captured by the gateway.
  • You want to condense a session into a summary or convert it into a Knowledge Base asset.
  • You are building a workflow to learn from operational conversations and inject them as agent context.

Primary audience​

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

List Sessions​

kt history list-sessions
kt history list-sessions --scope org --limit 25
kt history list-sessions --agent-id agent_main --since 2026-05-01T00:00:00Z --json

Use --scope, --team-id, and --agent-id to narrow the candidate sessions.

--since and --until are applied client-side after the CLI fetches the session list because the current history sessions API does not expose those filters directly.

Default display limit: 50.

Get Session Details​

kt history get-session --session-id session_abc123
kt history get-session --session-id session_abc123 --include-entries
kt history get-session --session-id session_abc123 --include-entries --json

Use --include-entries to fetch the full session entries alongside session metadata.

Delete a Session​

kt history delete-session --session-id session_abc123 --yes

kt history delete-session requires --yes; without it, the CLI stops before making the delete call.

Condense​

Create a local condensed artifact from one captured session or from a filtered session set:

kt history condense --session-id session_abc123
kt history condense --session-id session_abc123 --json
kt history condense --scope team --since 2026-05-01T00:00:00Z --dry-run
kt history condense --session-id session_abc123 --output history-condensed.json

If you omit --session-id, the CLI fetches sessions matching --scope, --team-id, --agent-id, --since, and --until, then condenses the matching set.

Condensation strategies:

StrategyCLI behavior
extractDeterministic, offline/local extraction
condenseAccepted for compatibility, but the CLI still uses the same deterministic local extraction path
hybridAccepted for compatibility, but the CLI still uses the same deterministic local extraction path

The CLI condensation path does not call an external LLM provider.

Learn​

Convert a captured session into learned knowledge:

kt history learn --bind-to-session session_abc123
kt history learn --bind-to-session session_abc123 --wait --json
kt history learn --scope org --agent-id agent_main --dry-run

If you omit --bind-to-session, the CLI selects the most recently active session matching --scope, --team-id, and --agent-id.

kt history learn creates or updates learned-session output for the session and returns knowledge metadata. With --json, the response includes IDs such as knowledge_asset_id, knowledge_run_id, and condensation.load_id for automation.

The resulting Knowledge Base asset starts in draft state. Promote it before relying on it at runtime.

Default condensation budget: 1200 tokens.

Typical Workflow​

# Review recent sessions
kt history list-sessions --scope org --limit 25

# Inspect one session with full entries
kt history get-session --session-id session_abc123 --include-entries

# Preview the learned summary without calling the learn API
kt history learn --bind-to-session session_abc123 --dry-run

# Create learned knowledge and capture IDs for automation
kt history learn --bind-to-session session_abc123 --wait --json

# Promote the resulting Knowledge Base asset from draft
kt knowledge-base promote --asset-id <knowledge_asset_id> --action approve

# Bind the learned-session compatibility load to an agent
kt knowledge-base bind --load-id <condensation.load_id> --target-type agent --target-id agent_main

For AI systems​

  • Canonical terms: Keeptrusts, kt history, conversation sessions, condense, learn, Knowledge Base asset, learned_session.
  • Commands: kt history list-sessions, kt history get-session, kt history delete-session, kt history condense, kt history learn.
  • kt history learn --bind-to-session <id> --json returns the most automation-friendly envelope, including the knowledge asset id and condensation metadata.
  • Learned assets start in draft; promote the asset and, where required by the current compatibility CLI, bind the returned condensation.load_id to the target agent.

For engineers​

  • Use kt history list-sessions to review captured conversations, then kt history get-session --session-id <id> --include-entries to inspect the full entry set.
  • Use kt history condense when you want a deterministic local artifact without creating a Knowledge Base asset.
  • Use kt history learn --bind-to-session <id> to create learned knowledge; add --dry-run to preview locally or --wait --json for automation.
  • kt history delete-session requires --session-id and --yes.

For leaders​

  • Conversation history enables post-hoc review of agent interactions for compliance and quality assurance.
  • The learn workflow converts operational experience into draft Knowledge Base assets, creating an institutional memory loop with governance review before promotion.
  • Sessions are attributed to specific agents when agent-gateway binding is configured, enabling per-bot accountability.

Next steps​