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

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): 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): 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): Handle persistence operations, saving the context to JSON between runs and restoring it when resuming sessions.

Compaction Engine (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:

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:

# Add a system message to alter behavior

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

Retrieve compressed history after compaction:

# 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:

# Export complete conversation history to a file

kimi --export-history > conversation.json

Programmatically load a saved session from disk:

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, 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 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 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 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 manage this persistence, reconstructing the exact conversation state including all messages and checkpoints.

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