How UI-TARS Session Management and UUID Generation Works

UI-TARS stores each conversation as a session in the browser's IndexedDB using a singleton SessionManager that generates unique identifiers by concatenating millisecond timestamps with RFC-4122 v4 UUIDs from the uuid library.

The UI-TARS desktop agent by ByteDance implements a robust client-side persistence layer to manage conversation state across application restarts. Understanding how UI-TARS session management works requires examining the IndexedDB integration in the renderer process and the hybrid identifier strategy that ensures global uniqueness while maintaining human-readable prefixes. This implementation leverages the uuid npm package alongside the idb-keyval wrapper to provide reliable CRUD operations without external database dependencies.

How UI-TARS Stores Sessions in IndexedDB

The core persistence logic resides in apps/ui-tars/src/renderer/src/db/session.ts, where the application creates a dedicated object store named sessions inside the IndexedDB database ui_tars_db. The createStore(DBName, 'sessions') function establishes this storage context, enabling atomic operations through the idb-keyval abstraction layer.

The SessionItem Data Model

Each session adheres to the SessionItem TypeScript interface, which defines the schema for conversation metadata. The structure includes an id string, human-readable name, creation and modification timestamps, and a flexible meta object typed as SessionMetaInfo. This design allows the application to store operator configuration and other extensible metadata without schema migrations.

Database Store Configuration

The session manager instantiates a singleton store reference that all CRUD operations share. By using entries(sessionStore), the manager can enumerate all persisted sessions for UI listing, while set, get, and del operations handle individual record access. This architecture ensures that session data survives browser refreshes and application restarts.

Creating and Managing Sessions

The SessionManager class exposes methods for the complete lifecycle of a conversation session, from creation through deletion.

CRUD Operations Implementation

Creating a session involves generating the composite identifier, constructing the initial object, and persisting it via set(session.id, session, sessionStore). The updateSession method performs partial merges with existing records, automatically refreshing the updatedAt timestamp before overwriting. For cleanup, deleteSession(id) removes records from the store when users explicitly delete conversations.

UUID Generation Strategy

According to the UI-TARS-desktop source code, session identifiers follow the pattern session_${now}_${v4()}, where now represents Date.now() and v4() produces a random RFC-4122 version-4 UUID. This approach imports the v4 function from the uuid package declared in the root package.json. The timestamp prefix provides chronological sorting capabilities, while the UUID suffix guarantees global uniqueness across distributed instances.

import { v4 } from 'uuid';

const now = Date.now();
const session = {
  id: `session_${now}_${v4()}`,   // e.g., "session_1715291234567_3f9f9f2e-2d5b-4e6a-8c2b-1a7e9e5d2c4f"
  name: 'New Conversation',
  createdAt: now,
  updatedAt: now,
  meta: { /* SessionMetaInfo */ },
};

State Management Integration

While the database layer handles persistence, the UI layer accesses sessions through a Zustand store defined in apps/ui-tars/src/renderer/src/store/session.ts. This store provides asynchronous actions including fetchSessions, createSession, updateSession, deleteSession, and setActiveSession that synchronize the React component tree with the underlying IndexedDB state. The file apps/ui-tars/src/renderer/src/utils/share.ts demonstrates additional usage patterns where session IDs may be exported or shared between application contexts.

Practical Code Examples

To create a new session programmatically from the store layer:

// In a component or hook
await useSessionStore.getState().createSession('My New Session');

Fetching all persisted sessions:

await useSessionStore.getState().fetchSessions();
console.log(useSessionStore.getState().sessions);

For direct database access outside the React lifecycle:

import { sessionManager } from '@renderer/db/session';

// Create with metadata
const newSess = await sessionManager.createSession('Demo', {
  operator: Operator.LocalComputer,
});
console.log(newSess.id);   // e.g., "session_1715291234567_3f9f9f2e-2d5b-4e6a-8c2b-1a7e9e5d2c4f"

// Update existing session
await sessionManager.updateSession(newSess.id, { name: 'Renamed Session' });

// Permanent deletion
await sessionManager.deleteSession(newSess.id);

Summary

• UI-TARS session management persists conversation data in the browser's IndexedDB using the idb-keyval wrapper, with core logic centralized in apps/ui-tars/src/renderer/src/db/session.ts.
• UUID generation combines millisecond timestamps with RFC-4122 v4 UUIDs from the uuid package, creating composite identifiers like session_1715291234567_uuid-string.
• CRUD operations include createSession, getSession, getAllSessions, updateSession, and deleteSession, all operating asynchronously on the IndexedDB object store.
• UI synchronization occurs through a Zustand store in apps/ui-tars/src/renderer/src/store/session.ts, which bridges the database layer with React components.
• Data model uses the SessionItem interface with extensible SessionMetaInfo for flexible metadata storage.

Frequently Asked Questions

How are session IDs generated in UI-TARS?

Session IDs follow a composite pattern defined in apps/ui-tars/src/renderer/src/db/session.ts. The system calls Date.now() to capture the current timestamp, then appends a random RFC-4122 v4 UUID generated by the uuid library's v4() function. The final string format is session_${timestamp}_${uuid}, ensuring both chronological sortability and global uniqueness.

Where are sessions stored in UI-TARS?

Sessions persist in the browser's IndexedDB within a database named ui_tars_db and an object store called sessions. The application uses the idb-keyval library to simplify transactions, with all CRUD operations targeting this specific store through the singleton sessionManager instance.

How does the UI layer access session data?

The renderer process accesses session data through a Zustand store located at apps/ui-tars/src/renderer/src/store/session.ts. This store exposes asynchronous actions such as fetchSessions and createSession that wrap the underlying SessionManager methods, keeping React component state synchronized with the IndexedDB backend.

What is the SessionMetaInfo used for?

The SessionMetaInfo type defines the structure of the meta property on SessionItem objects, allowing storage of flexible metadata such as operator configuration (e.g., Operator.LocalComputer) and other conversation-specific settings. This extensible object enables the session model to accommodate future features without requiring database schema migrations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}