History and Sessions

The History and Sessions pages let you browse, inspect, and manage organization history across chats, task runs, and captured gateway sessions.

Use this page when

• You want to browse or search captured conversation sessions from the gateway.
• You want one organization-wide list that mixes chat conversations and task-backed sessions.
• You need to inspect a specific session's timeline, policy results, token usage, or knowledge citations.
• You want to convert a valuable conversation into a reusable Knowledge Base asset.
• You are paginating or filtering sessions via the API.

Primary audience

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

Sessions page

The Sessions page groups related events into conversation sessions. Each session represents a continuous interaction thread.

What the session list shows

• Session ID and display name
• Entry count and duration
• Agent and user attribution
• Capture depth (raw, metadata_only)
• Knowledge citation count — how many Knowledge Base assets were referenced in the session
• Task run link — if the session was produced by a task executor, a link to the originating task run

Session detail

Opening a session shows:

• Full conversation timeline with request/response pairs
• Policy evaluation results for each turn
• Token usage per turn, including a context_tokens breakdown showing how many tokens the agent context block consumed
• Knowledge citations — which assets or memory items were recalled and injected
• Associated events and exported evidence links

Long-running or background chat replies can also create inbox notifications. Those notifications deep-link back to the exact history-backed chat session so collaborators can reopen the finished response without searching for the thread manually.

History page

The History page is a dedicated main-sidebar destination in the console. It provides an organization-wide history list that merges chat conversations, task-backed sessions, and other captured gateway sessions into one view.

Rows are sorted by the latest captured activity in the session, so a new user prompt or assistant output pushes that row to the top.

Task runs are linked into History as soon as they are dispatched or retried. That means a new Task row can appear immediately, even before the executor has written the first captured entry for the run.

Admins can review every captured chat or task session for the organization. Other users see only the history they can access through membership, grants, or actor attribution.

What the history list shows

• An in-panel History sessions heading with quick Refresh and Download actions
• A single-line title link for each chat, task, or session row
• A type badge for Chat, Task, or Session
• Agent name when a session is bound to an agent, otherwise an unassigned fallback
• Entry count
• Learning on or off
• Last updated timestamp

When a session does not already have a human title, Keeptrusts seeds one from the first prompt and then refines it in the background after the first three user turns.

History list search

The console list uses a single search bar. Search matches:

• Titles and preview text
• Session, conversation, task, and task-run identifiers
• Tags
• Agent names and identifiers
• User and team attribution fields when present

When you type a recognized field clause such as visibility: or click back into an existing clause such as visibility:user, Keeptrusts opens filter suggestions based on the currently loaded History rows. This lets you swap to another available value for that same field without retyping the whole filter.

Active structured filters also appear as chips below the search box. Each chip supports two actions:

• Click the chip body to reopen that filter for editing and change its value
• Click the × remove action to clear just that filter while leaving the rest of the query intact

Refreshing and exporting rows

Use the Refresh button in the History sessions header to reload the current table without losing your current search, page, or pinned agent/task filters.

Use the selection checkboxes in the Title column to choose the rows you want to export. Once one or more visible rows are selected, the Download dropdown becomes available and lets you export those selected rows as either CSV or JSON.

History session detail

Each history session includes:

• All captured entries (requests and responses)
• Session metadata (agent, user, team attribution)
• Task run link (when session was produced by a task executor)
• Condensation options for converting sessions into reusable knowledge

Chat rows open the dedicated conversation transcript view. Task rows open the task workbench for the linked task. Generic history rows still open the governance-oriented history detail.

Filtering sessions

Since filter

Use the since query parameter to request only sessions updated after a specific point in time:

GET /v1/history/sessions?since=2026-04-25T00:00:00Z

Only sessions with last_activity_at > since are returned. This is useful for incremental sync and polling.

Task run filter

To find the session produced by a specific task run:

GET /v1/history/sessions?task_run_id=<run-uuid>

Returns the session(s) written by the gateway executor for that run.

Pagination

Session list responses include has_more: boolean and next_cursor: string | null. Pass cursor=<next_cursor> to fetch the next page.

{
  "sessions": [...],
  "next_cursor": "session-uuid",
  "has_more": true
}

Session types: governance vs. history

Two separate session namespaces exist in Keeptrusts:

Namespace	Identifier field	Table	Purpose
History session	history_session_id	history_sessions	Immutable ledger of request/response activity
Governance/runner session	governance_session_id	runner_sessions	Runner execution context and audit trail

These identifiers MUST NOT be used interchangeably. API parameters and response fields are named consistently to distinguish them.

Capture depth modes

The gateway captures conversation history at configurable depth:

Mode	What is captured
raw	Full request and response bodies
metadata_only	Token counts, timing, verdicts — no content
disabled	No history capture

Configure capture depth in your policy-config.yaml:

history:
  capture: raw

Creating Knowledge from Sessions

Valuable conversation sessions can be condensed and converted into learned_session Knowledge Base assets:

1. Open the session detail
2. Review the conversation content
3. Click Create learned knowledge to synthesize a Knowledge Base asset from the session
4. The new asset appears in Knowledge Base with status Active
5. Bind the asset to an agent for runtime context injection

This is also available via the CLI:

kt history learn --id session_abc123

For AI systems

• Canonical terms: Keeptrusts, History, Sessions, history_sessions, task-backed history, capture depth, learned_session, history_session_id, governance_session_id.
• Feature and page names: History page, Sessions page, history list search, Create learned knowledge, kt history learn.
• Config keys: history.capture (values: raw, metadata_only, disabled).
• Related pages: Knowledge Base, Knowledge Lifecycle, Events, kt history.

For engineers

• Set history.capture: raw in policy-config.yaml to capture full request/response bodies. Use metadata_only for token counts without content.
• The console /history list is intentionally organization-wide and mixes chats plus task-backed sessions; use the row type badge and title link destination to distinguish where each row will open.
• Paginate with cursor=<next_cursor> — never assume all sessions fit in one response.
• history_session_id and governance_session_id are distinct namespaces. Do not mix them in API calls.
• Use GET /v1/history/sessions?since=<ISO8601> for incremental polling instead of full re-fetches.

For leaders

• Capture depth affects storage costs: raw stores full bodies, metadata_only stores only counts and timing.
• Session history is the basis for Knowledge Base learning — teams that capture raw history can synthesize reusable context assets.
• Citation auditing links every knowledge recall back to the specific asset version, supporting compliance evidence requirements.

Next steps

• kt history — CLI history management
• Events
• Knowledge Base
• Knowledge Lifecycle