# How to Manage Conversation History in Kimi-CLI: A Complete Guide

> Learn to manage Kimi-CLI conversation history efficiently. Discover how messages are stored and automatically compacted to optimize token usage in this comprehensive guide.

- Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
- Tags: how-to-guide
- Published: 2026-07-25

---

**Kimi-CLI stores conversation history in a `Context` object that persists messages to disk under `~/.kimi/sessions/<session-id>/`, with automatic compaction triggered at approximately 200 messages to optimize token usage.**

Managing conversation history in Kimi-CLI relies on a sophisticated context management system implemented in the MoonshotAI/kimi-cli repository. The CLI maintains a complete record of your dialogue using an in-memory `Context` class that automatically serializes to disk and compresses old messages when conversations grow lengthy.

## Understanding the Core Components

The history management architecture consists of four primary components working together:

**`Context` Class** ([`src/kimi_cli/soul/context.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/context.py)): The central data structure that holds a list of `Message` objects, timestamps, and checkpoint metadata in memory.

**`KimiSoul` Runtime** ([`src/kimi_cli/soul/kimisoul.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/kimisoul.py)): The core execution loop that manages the conversation flow, feeding context to the LLM and triggering maintenance operations.

**`Session` and `SubagentStore`** ([`src/kimi_cli/soul/agent.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/agent.py)): Handle persistence operations, saving the context to JSON between runs and restoring it when resuming sessions.

**`Compaction` Engine** ([`src/kimi_cli/soul/compaction.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/compaction.py)): Automatically compresses older messages into summary checkpoints when conversations exceed configurable thresholds.

## How Conversation History Works in Kimi-CLI

The conversation lifecycle follows four distinct phases:

1. **Appending Messages**: When you send input, `KimiSoul.run()` calls `context.add_user_message()` to append your query to the active context.

2. **Reading History**: Tools and agents access the conversation via `context.messages` for the full transcript or `context.checkpoints` for compressed summaries.

3. **Automatic Compaction**: When messages exceed the `MAX_MESSAGES` limit (default ~200), the compaction engine creates a checkpoint that replaces older messages with condensed summaries.

4. **Persistence**: At each turn's end, `Session.save_context()` serializes the context to the session directory, enabling `kimi resume` to restore exact conversation states.

## Accessing and Modifying Conversation History

Access the live conversation history programmatically through the Kimi-CLI runtime:

```python
from kimi_cli.app import KimiCLI

# Access the Context object from a running instance

ctx = cli.runtime.agent.context

# Iterate through all messages

for msg in ctx.messages:
    print(f"{msg.role}: {msg.content}")

```

Inject system messages or custom instructions mid-session:

```python

# Add a system message to alter behavior

ctx.add_system_message("You are now in troubleshooting mode.")

```

Retrieve compressed history after compaction:

```python

# Access the latest checkpoint summary

if ctx.checkpoints:
    latest = ctx.checkpoints[-1]
    print(f"Checkpoint summary: {latest.summary}")

```

## Persisting and Exporting History

Export your current session's conversation to JSON using the CLI:

```bash

# Export complete conversation history to a file

kimi --export-history > conversation.json

```

Programmatically load a saved session from disk:

```python
from kimi_cli.soul.context import Context
import json
import pathlib

# Load from the session storage directory

history_path = pathlib.Path.home() / ".kimi" / "sessions" / "my-session" / "context.json"
data = json.loads(history_path.read_text())

# Reconstruct the Context object

ctx = Context.from_dict(data)

```

## Managing Long Conversations with Compaction

According to the source code in [`src/kimi_cli/soul/compaction.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/compaction.py), the compaction system prevents token overflow in extended sessions. When `MAX_MESSAGES` (default approximately 200) is exceeded, the engine creates semantic checkpoints that preserve conversation flow while reducing token count. These checkpoints remain accessible via `context.checkpoints` and contain summarized representations of earlier dialogue turns.

## Summary

- **In-Memory Storage**: Kimi-CLI uses the `Context` class in [`src/kimi_cli/soul/context.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/context.py) to manage live conversation data.
- **Automatic Persistence**: The `Session` class saves context to `~/.kimi/sessions/<session-id>/` after each turn.
- **Message Compaction**: When conversations exceed ~200 messages, older content compresses into checkpoints to maintain performance.
- **API Access**: Access full history via `context.messages` or summarized content via `context.checkpoints`.
- **Programmatic Control**: Use `Context.from_dict()` to load saved histories and `add_system_message()` to modify context mid-session.

## Frequently Asked Questions

### Where does Kimi-CLI store conversation history on disk?

Kimi-CLI persists conversation history in JSON format under the `~/.kimi/sessions/<session-id>/` directory. The `Session.save_context()` method in [`src/kimi_cli/soul/agent.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/agent.py) handles this serialization automatically at the end of each conversation turn.

### How do I access the conversation history programmatically?

Access the active `Context` object through `cli.runtime.agent.context` where `cli` is your `KimiCLI` instance. The `context.messages` property returns the complete list of messages, while `context.checkpoints` provides access to compressed summaries after compaction.

### What happens when a conversation becomes too long?

When message count exceeds the `MAX_MESSAGES` threshold (default approximately 200), the compaction engine in [`src/kimi_cli/soul/compaction.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/compaction.py) automatically creates checkpoints. These checkpoints replace older messages with condensed summaries, reducing token usage while preserving context for the LLM.

### Can I resume a previous conversation after closing the CLI?

Yes. Kimi-CLI saves session state to disk after each turn, allowing you to resume conversations using the `kimi resume` command. The `Session` and `SubagentStore` classes in [`src/kimi_cli/soul/agent.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/agent.py) manage this persistence, reconstructing the exact conversation state including all messages and checkpoints.