# How UI-TARS Session Management and UUID Generation Works

> Discover how UI-TARS session management and UUID generation leverage IndexedDB and RFC-4122 v4 UUIDs to store conversations effectively. Learn the technical details now.

- Repository: [Bytedance Inc./UI-TARS-desktop](https://github.com/bytedance/UI-TARS-desktop)
- Tags: internals
- Published: 2026-05-10

---

**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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/package.json). The timestamp prefix provides chronological sorting capabilities, while the UUID suffix guarantees global uniqueness across distributed instances.

```typescript
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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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:

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

```

Fetching all persisted sessions:

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

```

For direct database access outside the React lifecycle:

```typescript
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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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`](https://github.com/bytedance/UI-TARS-desktop/blob/main/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.