How Subagents Function with the LaborMarket Registry and SubagentStore Persistence in Kimi CLI

The Kimi CLI orchestrates subagents through the LaborMarket registry, which instantiates agent types on demand, while SubagentStore persists each agent's state to disk, enabling seamless recovery across CLI sessions.

The MoonshotAI/kimi-cli repository implements a sophisticated subagent architecture that separates agent instantiation from state management. This design relies on two core components: the LaborMarket registry, which acts as a factory for agent types, and the SubagentStore, which handles durable persistence. Understanding how these systems interact is essential for building resilient AI workflows that survive CLI restarts.

LaborMarket Registry Architecture

Located in src/kimi_cli/soul/agent.py, the LaborMarket maintains an internal registry dictionary mapping agent type strings to concrete Python classes. When a user requests a new subagent via an AgentLaunchSpec, the registry instantiates the appropriate class and injects runtime dependencies including the session, logger, and available toolsets.

The registry decouples agent implementation details from the orchestration layer. By looking up the type field in the AgentLaunchSpec, the LaborMarket can construct specialized agents such as ShellAgent or ToolAgent without the calling code needing to import those classes directly.

SubagentStore Persistence Mechanism

The SubagentStore class, defined in src/kimi_cli/subagents/store.py, manages the lifecycle of agent data on disk. It creates isolated directories under <session>/subagents/<agent_id>/ and maintains a manifest.json file containing the launch specification and context pointers.

When a subagent executes, the store writes the complete context from src/kimi_cli/soul/context.py along with metadata and artifact files. This separation allows the registry to remain stateless while the store handles durability, ensuring that agent progress survives unexpected CLI terminations.

The Subagent Lifecycle

Creation and Registration

When the Runtime receives a request to create a subagent, it delegates to LaborMarket.create_agent(). After construction, the agent ID is immediately registered with the SubagentStore, which writes the initial manifest to <session>/subagents/<agent_id>/manifest.json and prepares the storage directory for subsequent state writes.

Runtime Integration and State Saving

During execution, subagents periodically trigger store.save_state() to serialize their current context. This method, implemented around lines 64-112 of store.py, flushes the agent's working memory and any generated artifacts to disk.

Because persistence occurs after each significant operation, the system maintains crash resilience without requiring explicit user checkpoints.

Cross-Session Recovery

Upon startup, Runtime initializes SubagentStore for the current session and calls store.list_ids() to discover persisted agents. For each ID found, the system invokes store.load(id), which reconstructs the agent instance by retrieving the stored spec and hydrating the context from src/kimi_cli/soul/context.py.

This process effectively resurrects subagents exactly where they left off, including their conversation history and intermediate files.

Working with Subagents: Code Examples

The following examples demonstrate how to interact with the LaborMarket registry and SubagentStore persistence layer programmatically.

Launch a new subagent by constructing an AgentLaunchSpec and passing it to the LaborMarket:

from kimi_cli.subagents.core import AgentLaunchSpec
from kimi_cli.soul.runtime import Runtime

runtime = Runtime(session_path="~/.kimi/sessions/2024-09-01")
spec = AgentLaunchSpec(
    type="ShellAgent",          # Must match a type registered in LaborMarket

    name="my-shell",
    args={"cmd": "ls -R"}      # Agent-specific arguments

)

# LaborMarket creates the agent and SubagentStore registers it

subagent = runtime.labor_market.create_agent(spec)

Retrieve a previously persisted subagent using the store's loading mechanism:

from kimi_cli.subagents.store import SubagentStore
from kimi_cli.soul.runtime import Runtime

runtime = Runtime(session_path="~/.kimi/sessions/2024-09-01")
store = SubagentStore(runtime.session)

# List all stored sub-agents

ids = store.list_ids()                     # e.g. ["agent-1234", "agent-5678"]

my_agent = store.load("agent-1234")        # Restores the full Agent instance

Manually trigger persistence when custom save points are required:

subagent_id = subagent.agent_id
runtime.subagent_store.save_state(subagent_id)   # Flushes context & artifacts to disk

Summary

• The LaborMarket registry in src/kimi_cli/soul/agent.py acts as a factory that maps AgentLaunchSpec types to concrete agent classes, injecting runtime services during instantiation.
• SubagentStore in src/kimi_cli/subagents/store.py provides durable persistence by serializing agent context and metadata to <session>/subagents/<agent_id>/manifest.json.
• Agents transition through a lifecycle of creation, registration, periodic state saving via save_state(), and automatic recovery through list_ids() and load().
• This architecture decouples agent construction from storage, enabling crash resilience and multi-session support where each Kimi session maintains isolated subagent states.

Frequently Asked Questions

How does LaborMarket determine which agent class to instantiate?

The LaborMarket maintains an internal dictionary registry that maps string type identifiers to Python classes. When create_agent() receives an AgentLaunchSpec, it extracts the type field and performs a lookup to retrieve the corresponding class constructor.

What data does SubagentStore actually persist to disk?

The store persists the agent's context (conversation state and working memory), the original launch specification, creation metadata, and any artifact files generated during execution. All data is written as JSON and flat files under the session-specific subagents/<agent_id>/ directory.

Can subagents survive a complete CLI restart or system reboot?

Yes. Because SubagentStore writes state to disk immediately after tool execution, a complete restart allows Runtime to reconstruct all previously running agents by loading their manifests from the session directory and hydrating their contexts via store.load().

Where can I find the CLI commands to manage subagents interactively?

The command-line interface for creating, listing, and deleting subagents is implemented in src/kimi_cli/tools/agent/. These tools wrap the underlying LaborMarket and SubagentStore APIs, exposing commands like /agent:create and /agent:list to the user.

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