Chat History & Storage
Relevant source files
The following files were used as context for generating this wiki page:
The Chat History & Storage system in Linux Archductor is responsible for persisting, retrieving, and displaying interactions between users and AI agents (Codex, Claude, etc.) across various workspaces. It provides a unified view of local Linux sessions, structured chat threads, and legacy data imported from macOS Conductor databases.
This system ensures that agent context is maintained across restarts, allows for "session resumption" where an agent can pick up from a previous conversation state, and provides users with a comprehensive timeline of all events—including tool usage, skill announcements, and file changes—that occurred during a task.
Data Model & Storage Architecture
The project utilizes a SQLite-backed storage model to manage workspace state, chat threads, and individual messages. The storage is primarily handled by the WorkspaceStore, which manages the lifecycle of chat data.
Core Entities
The storage architecture revolves around several key entities:
- ChatThreadRecord: Represents a high-level conversation container identified by a provider (e.g., "codex") and a title.
- ChatMessageRecord: Individual messages within a thread, assigned roles such as "user", "agent", or "system".
- ChatEventRecord: Structured events occurring during a session, such as tool calls or file changes, stored as JSON payloads.
- ProcessRecord: PTY-backed session logs that represent the raw output of agent processes.
Sources: crates/gtk-app/src/session_surface.rs:60-63, crates/cli/src/main.rs:18-22
Schema Relationships
The following ER diagram illustrates the relationships between the primary storage entities:
This diagram shows how workspaces act as the top-level container for all chat-related entities.
Sources: crates/gtk-app/src/workspace_command_center.rs:159-170, crates/gtk-app/src/session_surface.rs:590-605
Unified History View
The History system merges multiple data sources into a single interface. It handles three distinct types of history:
- Local Thread History: Modern structured chat threads created within the Linux app.
- Linux Legacy History: Saved PTY-backed session logs from early iterations of the Linux app that do not have associated thread IDs.
- Imported History: Data imported from the original macOS Conductor application database.
Sources: crates/gtk-app/src/history.rs:188-215
History Source Mapping
| Source | Identifier Prefix | Storage Mechanism |
|---|---|---|
| Linux (Modern) | local-thread: | SQLite chat_threads and chat_messages tables |
| Linux Legacy | local: | SQLite processes table + raw log files |
| Imported | imported: | Read-only macOS Conductor DB tables (sessions, session_messages) |
Sources: crates/gtk-app/src/history.rs:242-255, crates/gtk-app/src/history.rs:282-300
Parsing & Transcript Processing
To display PTY-backed session logs as readable chats, the system employs advanced parsing logic. This is critical for agents like Codex that output raw TUI (Terminal User Interface) data.
Message Extraction
The parse_local_chat_transcript and parse_session_transcript_events functions scan raw logs for specific markers to segment the output into distinct roles.
The parsing flow identifies structured markers within raw terminal logs to reconstruct a conversation timeline.
Sources: crates/core/src/local_chat.rs:43-70, crates/gtk-app/src/session_surface.rs:1055-1080
Codex TUI Parsing
The Codex agent outputs ANSI terminal sequences. The codex_tui.rs module parses these sequences to extract clean messages and detect "inline events."
- Screen Messages: Parses boxed "You" and "Codex" messages from a virtual terminal screen.
- Inline Events: Detects specific patterns such as
Ran <command>orUsing <skill>to render them as interactive "chips" in the UI. - Context Usage: Extracts token count and window percentage (e.g.,
Context window: 42%) to display usage gauges.
Sources: crates/core/src/codex_tui.rs:135-155, crates/core/src/codex_tui.rs:595-610, crates/gtk-app/src/session_surface.rs:660-685
Session Resumption & Bootstrap
When switching between agents or restarting a workspace, the system can "bootstrap" the new session with history from the previous one.
Bootstrap Logic
The function session_history_bootstrap_markdown generates a summary of the prior conversation in Markdown format. This is then injected into the new agent session to provide continuity.
// Example bootstrap generation
fn session_history_bootstrap_markdown(events: &[SessionTranscriptEvent]) -> Option<String> {
let mut markdown = String::from(
"Conversation context from previous agent session.\n\
Do not answer this message. Use it only for continuity...\n\n\
# Prior Conversation\n\n",
);
// ... iterates and appends User and Agent turns
}
Sources: crates/gtk-app/src/session_surface.rs:1880-1910
Resumption IDs
The system tracks session_resume_id for agents like Claude. This ID allows the agent harness to re-attach to an existing remote conversation state if the local process was interrupted.
Sources: crates/gtk-app/src/session_surface.rs:1595-1610, crates/gtk-app/src/session_surface.rs:1942-1955
Workspace Timeline
Separate from the chat-specific history, the Workspace Timeline provides a persistent audit trail of all actions performed within a workspace. These events are recorded automatically by the WorkspaceStore.
Recorded Event Types
| Event Kind | Description |
|---|---|
branch.renamed | Logs when a Git branch is renamed within the workspace. |
session.start | Records when a new agent or shell session begins. |
pr.created | Logs the creation of a GitHub Pull Request. |
checkpoint.create | Records a manual or automatic workspace checkpoint. |
Sources: crates/cli/src/main.rs:1130-1145, crates/gtk-app/src/workspace_command_center.rs:1155-1165
Summary
The Chat History & Storage module provides a robust foundation for parallel agent workflows. By combining structured SQLite data for modern threads with PTY log parsing for raw terminal sessions, it achieves a unified user experience. The system's ability to import legacy Conductor data and generate bootstrap context for session resumption ensures that no work is lost and agent continuity is maintained throughout the development lifecycle.
Sources: crates/gtk-app/src/history.rs, crates/gtk-app/src/session_surface.rs, crates/core/src/local_chat.rs