What Is a Session in Maka? A Complete Technical Guide

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, 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, 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 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 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

// 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

// 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

// 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 – Renders the status badge and interprets SessionStatus and SessionBlockedReason
• packages/ui/src/transcript-projection.ts – Core logic for projecting a session's transcript into the UI
• packages/ui/src/use-transcript-projection.ts – React hook that wires the projection into components
• packages/ui/src/thinking-stream.ts – Handles per-session "thinking" (LLM streaming) buffers
• packages/ui/src/stream-delta.ts – Implements per-session caps for streamed output
• packages/ui/src/use-composer-draft.ts – Stores unsent draft text per session
• 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, 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 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. This architecture enables session restoration after browser refreshes or when switching between host contexts, maintaining conversation continuity.

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