# What Is a Session in Maka? A Complete Technical Guide

> Learn what a session is in Apache Maka. Understand this core unit for managing conversational threads, tool invocations, and LLM replies with persistent state and metadata.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-09-10

---

**A Session in Apache Maka is the fundamental unit representing a single conversational thread, encapsulating a persistent stream of turns (user inputs, tool invocations, and LLM replies) along with the metadata that drives rendering, state management, and SQLite persistence.**

In the Apache Maka framework, a **Session** serves as the central abstraction for managing individual conversations. Every interaction between users, tools, and language models occurs within the context of a specific session, making it the primary container for conversational state and history according to the `apache/maka` source code.

## Session Identity and UUID Management

Every session is identified by a stable UUID assigned to the `sessionId` property. According to [`packages/ui/src/transcript-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/transcript-projection.ts), the UI extracts this identifier from DOM elements carrying `data-session-id` attributes, ensuring consistent session tracking across the interface.

Turns are stored as `StoredMessage` objects defined in `@maka/core/session`. These structures contain raw text content, tool execution results, timestamps, and optional "thinking" streams that represent intermediate LLM processing states.

## Session Status and Lifecycle States

As implemented in [`packages/ui/src/session-status-presentation.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/session-status-presentation.ts), a session transitions through distinct states including `Active`, `Background`, and `Blocked`. When blocked, the system exposes specific `SessionBlockedReason` values such as `RateLimited` or `ToolError` to inform the UI about interruption causes.

## Per-Session Isolation and State Scoping

Maka enforces strict isolation between concurrent sessions. Draft text entries, temporary tool outputs, and thinking streams are all scoped to specific `sessionId` values. The implementation in [`packages/ui/src/use-composer-draft.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/use-composer-draft.ts) utilizes a runtime-only key to store unsent drafts, automatically clearing them when the active session changes to prevent cross-session data leakage.

## Session Persistence Architecture

Sessions achieve durability through SQLite storage integration. The performance tests in [`scripts/perf/frontend.spec.ts`](https://github.com/apache/maka/blob/main/scripts/perf/frontend.spec.ts) validate that the session stream, SQLite storage layer, and renderer loop remain connected, enabling session restoration after page reloads or host-side context switches.

## Working with the Session API

The global `window.maka.sessions` object exposes methods for session manipulation. You can create sessions, submit messages, and subscribe to real-time events using the following patterns:

### Creating and Submitting Messages

```typescript
// Create a new session (the host generates a UUID)
const sessionId = window.maka.sessions.create();

// Send a user message to the session
await window.maka.sessions.submitMessage(sessionId, 'next_turn', {
  text: 'Explain quantum computing in simple terms.',
});

// Listen for incremental updates (e.g. LLM streaming tokens)
window.maka.sessions.subscribeEvents(sessionId, (event) => {
  console.log('Session event:', event);
});

```

### React Component Integration

```tsx
// React component that shows the current session status
import { SessionStatus } from '@maka/core/session';
import { useSessionStatus } from '@maka/ui';

function SessionHeader({ sessionId }: { sessionId: string }) {
  const status: SessionStatus = useSessionStatus(sessionId);
  return <h2>{`Session ${sessionId} – ${status}`}</h2>;
}

```

### Draft Text Retrieval

```typescript
// Retrieve the draft text that belongs to a specific session
import { getDraft } from '@maka/ui';

const draft = getDraft(sessionId);
console.log('Unsaved draft for this session:', draft);

```

## Key Implementation Files

The following source files define how a Session is created, managed, persisted, and visualized throughout the Maka codebase:

- **[`packages/ui/src/session-status-presentation.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/session-status-presentation.ts)** – Renders the status badge and interprets `SessionStatus` and `SessionBlockedReason`
- **[`packages/ui/src/transcript-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/transcript-projection.ts)** – Core logic for projecting a session's transcript into the UI
- **[`packages/ui/src/use-transcript-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/use-transcript-projection.ts)** – React hook that wires the projection into components
- **[`packages/ui/src/thinking-stream.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/thinking-stream.ts)** – Handles per-session "thinking" (LLM streaming) buffers
- **[`packages/ui/src/stream-delta.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/stream-delta.ts)** – Implements per-session caps for streamed output
- **[`packages/ui/src/use-composer-draft.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/use-composer-draft.ts)** – Stores unsent draft text per session
- **[`scripts/perf/frontend.spec.ts`](https://github.com/apache/maka/blob/main/scripts/perf/frontend.spec.ts)** – Performance tests validating the session-stream, SQLite storage, and renderer loop connectivity

## Summary

- A **Session** is the atomic container for a single conversation thread in Apache Maka
- Every session receives a unique UUID stored in `sessionId` and referenced via `data-session-id` attributes in the DOM
- Conversation history persists as `StoredMessage` objects with support for incremental updates and "thinking" streams
- The system maintains strict isolation for drafts, thinking streams, and temporary state per session
- Sessions transition through defined states (`Active`, `Background`, `Blocked`) with explicit blocking reasons exposed via `SessionBlockedReason`
- SQLite persistence ensures conversation continuity across page reloads and host context switches

## Frequently Asked Questions

### How is a session identified in the Maka UI?

Each session receives a stable UUID assigned to the `sessionId` property. The UI extracts this identifier from DOM elements carrying `data-session-id` attributes, as implemented in [`packages/ui/src/transcript-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/transcript-projection.ts), ensuring consistent session tracking across components.

### What data structure stores conversation turns in a Maka session?

Turns are stored as `StoredMessage` objects defined in the `@maka/core/session` package. These structures contain raw text content, tool execution results, timestamps, and optional thinking streams that capture intermediate LLM processing states.

### How does the UI receive real-time updates from an active session?

Components subscribe to session events through `window.maka.sessions.subscribeEvents()`, which streams incremental updates including LLM tokens and tool results. This mechanism is validated in [`scripts/perf/frontend.spec.ts`](https://github.com/apache/maka/blob/main/scripts/perf/frontend.spec.ts) to ensure proper connectivity between the session stream and renderer loop.

### Where is session data persisted in Maka?

Session data persists to SQLite storage, as confirmed by the performance test suite in [`scripts/perf/frontend.spec.ts`](https://github.com/apache/maka/blob/main/scripts/perf/frontend.spec.ts). This architecture enables session restoration after browser refreshes or when switching between host contexts, maintaining conversation continuity.