# How the Kimi Code Session Management System Works: A Three-Layer Architecture

> Explore the Kimi Code session management system's three-layer architecture. Learn how it ensures atomic operations, real-time tracking, and cross-platform consistency for MoonshotAI/kimi-code.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: architecture
- Published: 2026-07-22

---

**The Kimi Code session management system implements a robust three-layer architecture separating filesystem persistence, RPC service logic, and protocol definitions to enable atomic session operations, real-time status tracking, and consistent cross-platform behavior across the MoonshotAI/kimi-code repository.**

The session management system in MoonshotAI/kimi-code coordinates complex AI agent interactions through a sophisticated design that spans on-disk storage, real-time event streaming, and workspace isolation. This architecture ensures that sessions remain consistent across multiple front-ends including the CLI, web UI, and VS Code extension, while providing atomic operations for creation, forking, and archival.

## Three-Layer Architecture Overview

The system organizes functionality into three tightly coupled layers:

| Layer | Responsibility | Core Files |
|-------|----------------|------------|
| **Persistence** | Stores sessions on disk, maintains a global index, and handles creation, forking, renaming, archiving, and deletion. | [`packages/agent-core/src/session/store/session-store.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/session/store/session-store.ts) |
| **Service** | Exposes a high-level RPC-style API used by the engine, translates RPC calls into persistence actions, and publishes status events. | [`packages/agent-core/src/services/session/sessionService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/services/session/sessionService.ts) |
| **Protocol** | Defines the wire-format types (`Session`, `SessionSummary`, `SessionUpdate`, etc.) that client SDKs and servers exchange. | [`packages/protocol/src/session.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/protocol/src/session.ts) |

## Session Persistence Layer (SessionStore)

The **persistence layer** implements durable storage through the `SessionStore` class in [`packages/agent-core/src/session/store/session-store.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/session/store/session-store.ts).

### Directory Layout and Workspace Buckets

All sessions live under the path `<home>/sessions/<bucket>/<session-id>/`. The **workspace bucket** derives from a hash of the normalized `workDir` computed by `encodeWorkDirKey`, unless a workspace registry resolves the physical root to a predefined workspace ID. This design prevents duplicate buckets on case-variant Windows paths by canonicalizing directory strings before hashing.

### The Append-Only Index

Session lookup relies on an **append-only index** stored at `sessions/index.jsonl`, which contains `SessionIndexEntry` records mapping session IDs to their directories and work-directories. The index enables fast lookups without filesystem scanning and can be rebuilt via `SessionStore.reindex()` if corrupted, which scans the filesystem, recovers work-dirs from each [`state.json`](https://github.com/MoonshotAI/kimi-code/blob/main/state.json), and repairs missing entries without overwriting valid data.

### Atomic Operations and Error Handling

Core operations—including `create`, `fork`, `rename`, `archive`, `delete`, and `list`—manipulate both the index and on-disk files atomically. Each session directory contains a [`state.json`](https://github.com/MoonshotAI/kimi-code/blob/main/state.json) for metadata and `wire.jsonl` for recorded agent events. Failures such as "session already exists" or "invalid title" raise strongly-typed **KimiError** instances with appropriate **ErrorCodes**.

### Forking Sessions

The `SessionStore.fork()` method implements session branching by copying the source directory, optionally truncating history at a specific turn, dropping unneeded files like [`upcoming-goals.json`](https://github.com/MoonshotAI/kimi-code/blob/main/upcoming-goals.json), and updating [`state.json`](https://github.com/MoonshotAI/kimi-code/blob/main/state.json) with fork metadata including `forkedFrom` and timestamps. Forking also appends a "forked" record to each agent's `wire.jsonl` to maintain audit trails.

## Session Service Layer (SessionService)

The **service layer** acts as the bridge between RPC surface and persistence, implemented in [`packages/agent-core/src/services/session/sessionService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/services/session/sessionService.ts).

### Event-Driven Status Management

`SessionService` maintains per-session **work facts** (`busy`, `main_turn_active`, `pending_interaction`, `last_turn_reason`) by listening to bus events such as `turn.started`, `turn.ended`, `prompt.submitted`, and `event.approval.requested`. These facts are recomputed via `_computeWorkFacts` and published as `event.session.work_changed` events through the `IEventService` defined in [`packages/agent-core/src/services/event/event.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/services/event/event.ts).

### CRUD Operations and RPC Integration

Public methods including `create`, `list`, `get`, `update`, `fork`, `createChild`, and `archive` forward to the core RPC service (`this.core.rpc.*`). After each mutation, `_patchSessionStatus` augments the protocol session with live facts before emitting creation events. The service throws strongly-typed errors like `SessionNotFoundError` and `SessionUndoUnavailableError` to client SDKs.

### Undo and Compaction Support

The `undo` method validates user input history via `canUndoHistory` before issuing `undoHistory` on the core RPC. The `compact` operation triggers `beginCompaction` after resuming the session in memory, allowing the system to condense event logs while preserving semantic state.

## Protocol Layer and Type Definitions

The **protocol layer** defined in [`packages/protocol/src/session.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/protocol/src/session.ts) establishes the contract between clients and server.

### Core Session Types

Key types include:

- **`Session`** – The full session object exposed to UIs, containing `id`, `title`, `busy`, `main_turn_active`, and metadata.
- **`SessionSummary`** – Lightweight records for listing sessions, containing timestamps, `archived` flags, and optional `lastPrompt`.
- **`SessionCreate`, `SessionUpdate`, `SessionFork`** – Input shapes accepted by the service layer for mutations.

### Wire Format Stability

These TypeScript definitions ensure a stable contract across the TUI, web UI, VS Code extension, and Node SDK, preventing breaking changes in serialized session data.

## Event Flow and Real-Time Updates

Session changes propagate through a four-stage pipeline:

1. **Client requests** arrive at REST/WebSocket endpoints (`/api/v1/sessions`) and route to `SessionService` methods.
2. **Service** updates `SessionStore` or calls core RPC, triggering disk mutations and index updates.
3. **Service** patches sessions with live facts via `_computeWorkFacts` and fires `event.session.created` or `event.session.work_changed`.
4. **UI components** subscribe via `IEventService` and refresh session lists, status badges, or transcript views.

## Integration with Subsystems

Session management interacts with several supporting services:

- **Workspace Registry** – Located in [`packages/agent-core/src/session/store/workdir-key.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/session/store/workdir-key.ts), provides `resolveWorkspaceId` to map `workDir` to stable buckets and handle Windows path canonicalization.
- **Prompt Service** – Supplies current prompt IDs to determine `mainTurnActive` status.
- **Approval and Question Services** – Contribute to the `busy` flag by exposing pending user interactions.

## Working with the Session API

The following examples demonstrate common operations using the Node SDK.

Creating a new session:

```typescript
import { Klient } from '@moonshot-ai/klient';

async function newSession() {
  const client = new Klient({ baseUrl: 'http://localhost:58627' });
  const session = await client.global.sessions.create({
    metadata: { cwd: '/home/alice/project' },
    title: 'Exploring Kimi',
  });
  console.log('Created session:', session.id);
}

```

Forking a session at turn 2:

```typescript
const forked = await client.global.sessions.fork('session-abc123', {
  title: 'Fork of Exploration',
  turnIndex: 2,                     // truncate after the 2nd user turn
});
console.log('Forked session ID:', forked.id);

```

Listing non-archived sessions:

```typescript
const list = await client.global.sessions.list({
  workspaceId: 'workspace-my-repo',
  excludeEmpty: true,
});
list.items.forEach(s => console.log(`${s.title} (${s.id})`));

```

Subscribing to status changes via WebSocket:

```typescript
const ws = new WebSocket('ws://localhost:58627/api/v1/ws');
ws.onmessage = ev => {
  const event = JSON.parse(ev.data);
  if (event.type === 'event.session.work_changed') {
    console.log(`Session ${event.sessionId} busy=${event.busy}`);
  }
};

```

## Summary

- **Three-layer design** separates filesystem persistence (`SessionStore`), RPC service logic (`SessionService`), and protocol types (`@moonshot-ai/protocol`).
- **Atomic storage** uses workspace buckets, an append-only index at `sessions/index.jsonl`, and per-session [`state.json`](https://github.com/MoonshotAI/kimi-code/blob/main/state.json) and `wire.jsonl` files.
- **Real-time status** propagates via event-driven work facts and the `event.session.work_changed` event.
- **Robust forking** copies directories, truncates history, and maintains audit trails in `wire.jsonl`.
- **Cross-platform safety** relies on workspace registry canonicalization in [`workdir-key.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/workdir-key.ts) to handle case-sensitivity issues.

## Frequently Asked Questions

### How does Kimi Code store session data on disk?

Sessions are stored under `<home>/sessions/<bucket>/<session-id>/` as defined in [`packages/agent-core/src/session/store/session-store.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/session/store/session-store.ts). Each session contains a [`state.json`](https://github.com/MoonshotAI/kimi-code/blob/main/state.json) file for metadata and a `wire.jsonl` file for recorded agent events, organized into workspace buckets derived from normalized directory paths.

### What happens when I fork a session in Kimi Code?

The `SessionStore.fork()` method copies the source directory to a new location, optionally truncates the history at a specified turn index, removes temporary files like [`upcoming-goals.json`](https://github.com/MoonshotAI/kimi-code/blob/main/upcoming-goals.json), updates [`state.json`](https://github.com/MoonshotAI/kimi-code/blob/main/state.json) with `forkedFrom` metadata, and appends a fork record to `wire.jsonl` to preserve the audit trail.

### How does the session service track real-time activity status?

`SessionService` computes **work facts** (`busy`, `main_turn_active`, `pending_interaction`) by listening to internal bus events such as `turn.started` and `prompt.submitted`. It publishes these status changes via `event.session.work_changed` through the event bus defined in [`packages/agent-core/src/services/event/event.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/services/event/event.ts), allowing UI components to react instantly.

### Can session data be recovered if the index becomes corrupted?

Yes. The `SessionStore.reindex()` method scans the filesystem, recovers work-directories from each session's [`state.json`](https://github.com/MoonshotAI/kimi-code/blob/main/state.json), and reconstructs the append-only index at `sessions/index.jsonl` without overwriting existing valid data, effectively repairing the catalog while preserving session integrity.