# How Session State is Persisted and Managed Across Kimi-Code Restarts

> Discover how Kimi-Code persists session state with wire.jsonl logs, enabling seamless restarts and transcript rebuilding with SessionStore for uninterrupted workflow.

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

---

**Kimi-Code persists session state using a JSON-Lines log file (`wire.jsonl`) stored in a per-session directory, which SessionStore replays on startup to rebuild the full transcript and resume execution.**

The **MoonshotAI/kimi-code** repository implements durable session persistence through a filesystem-backed architecture. Every conversation turn, tool invocation, and metadata update is appended to a local log, enabling seamless recovery after server or CLI restarts without losing context.

## Core Persistence Architecture

### The SessionStore Component

At the heart of kimi-code's durability layer sits 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). This component manages the lifecycle of session data, coordinating between in-memory state and disk storage.

When initialized, the constructor (lines 380–420) establishes a dedicated directory under the kimi-code data root:

```bash
~/.kimi-code/server/instances/<instance>/sessions/<session-id>/

```

The store instantiates a `FileSystemAgentRecordPersistence` handler from [`packages/agent-core/src/session/store/file-system-persistence.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/session/store/file-system-persistence.ts) to manage low-level I/O operations including `read()`, `append()`, `rewrite()`, and `flush()`.

### The wire.jsonl Format

All state mutations serialize to a **JSON-Lines** file named `wire.jsonl`. Each line represents an `AgentRecord` containing transcript operations, plan revisions, or configuration updates. This append-only structure ensures crash safety and enables efficient streaming replays.

The format captures:

- **Transcript operations** (turns, tool frames, plan updates)
- **Session metadata** (title, working directory, custom fields)
- **Plan revision references** (pointers to markdown files under the `plan/` subdirectory)
- **Workspace attachments** (files added via `session.addAdditionalDir` stored under `additional/`)
- **MCP and user configuration** ( reapplied during rebuild)

## Writing Session State to Disk

### Real-Time Record Appending

During active sessions, the engine emits transcript operations that `SessionStore` immediately persists. At lines 891–893 of [`session-store.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/session-store.ts), the implementation appends each record synchronously:

```typescript
persistence.append(record);
await persistence.flush();

```

This guarantees that every tool call and agent response survives a sudden process termination.

### Durability Guarantees

The `FileSystemAgentRecordPersistence` implementation ensures data integrity through explicit flushing. Unlike buffered writes that risk data loss on crash, kimi-code forces filesystem synchronization after each append operation, trading marginal write latency for reliability.

## Recovering State After Restart

### Cold Rebuild Process

When the kimi-code server boots, `SessionStore.read()` (lines 637–701) executes a **cold rebuild**. The method iterates through the session's `wire.jsonl`, reconstructing the transcript object and reinitializing per-agent sequence number watermarks.

This process transforms the append-only log back into a functional in-memory state managed by the `@moonshot-ai/transcript` layer, making sessions available to the SDK and UI without manual intervention.

### In-Memory Journal for Live Streams

To optimize WebSocket performance without sacrificing durability, [`packages/kap-server/src/transport/ws/v1/sessionEventJournal.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/src/transport/ws/v1/sessionEventJournal.ts) maintains a bounded in-memory journal. This mirrors the sequence numbers persisted to disk, enabling fast event replay for reconnecting clients while avoiding redundant filesystem reads.

## Resuming Sessions via the SDK

The Node SDK exposes session persistence through intuitive methods. Below are practical implementations for common workflows.

### Creating a Persisted Session

By default, sessions enable persistence automatically:

```typescript
import { KimiHarness } from '@moonshot-ai/node-sdk';

const client = new KimiHarness({ /* auth config */ });

async function start() {
  const session = await client.createSession({
    title: 'Data Analysis',
    persist: true, // defaults to true
  });
  console.log('Session ID:', session.id);
}
start();

```

*Source: [`packages/node-sdk/src/session.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/session.ts) (line 174)*

### Attaching Files with Persistence

Workspace attachments survive restarts when persisted:

```typescript
import { join } from 'path';
import { readFileSync } from 'fs';

async function attachFile(sessionId: string) {
  const content = readFileSync('data/input.txt');
  await client.session.addAdditionalDir(sessionId, {
    path: join('/tmp', 'input.txt'),
    persist: true, // writes to session folder
  });
}

```

*Source: [`packages/node-sdk/src/rpc.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/rpc.ts) (line 377)*

### Resuming After Server Restart

Recover an existing session using the resume API:

```typescript
async function resume() {
  const resumed = await client.session.resume({
    id: 'session-abc123',
    includePersistedSubagents: true,
  });

  console.log('Resumed title:', resumed.title);
  // Transcript contains all prior turns
}
resume();

```

*Source: [`packages/node-sdk/src/kimi-harness.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/kimi-harness.ts) (lines 139–148)*

### Deleting Persisted State

Remove both memory and disk artifacts:

```typescript
await client.session.delete('session-abc123');

```

*Source: [`packages/agent-core/src/tools/cron/session-store.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/tools/cron/session-store.ts) (line 44)*

## What Gets Persisted (and What Doesn't)

**Persisted to wire.jsonl:**
- Engine-generated transcript operations
- Tool call frames and responses
- Plan revision markers
- Session metadata and configuration
- Additional directory references

**Not persisted:**
- UI-specific state (scroll positions, panel layouts)
- Transient client-side caches
- Uncommitted in-memory buffers

This selective approach minimizes disk footprint while preserving complete logical state for session continuity.

## Summary

- **SessionStore** 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) coordinates all persistence operations
- State serializes to **JSON-Lines** format in `wire.jsonl` within per-session directories
- **Synchronous flushing** after each append ensures durability against crashes
- **Cold rebuild** logic replays logs on startup to reconstruct transcripts
- The **Node SDK** provides `createSession()`, `resume()`, and `delete()` methods for lifecycle management
- Only engine events persist; UI state remains client-side

## Frequently Asked Questions

### Where is kimi-code session data stored on disk?

Session data resides in `~/.kimi-code/server/instances/<instance>/sessions/<session-id>/`, specifically within a `wire.jsonl` file containing the JSON-Lines log. The `SessionStore` constructor creates this hierarchy during session initialization.

### Does kimi-code persist UI state like scroll positions?

No. The persistence layer intentionally excludes UI-specific state such as scroll positions or panel layouts. Only engine-generated events—transcript operations, tool calls, and metadata—serialize to disk, keeping the log focused on execution context rather than interface state.

### How does the SDK resume a session after server restart?

The SDK calls `client.session.resume()` with the session ID, which triggers the server to invoke `SessionStore.read()`. This method replays the `wire.jsonl` log, rebuilds the transcript via `@moonshot-ai/transcript`, and returns a fully rehydrated session object including all prior conversation history.

### Is session persistence enabled by default?

Yes. When creating sessions through `client.createSession()`, the `persist` parameter defaults to `true`. You must explicitly set `persist: false` to create ephemeral sessions that exist only in memory.