# How Prime Agent Preserves Kernel State During Context Compaction

> Learn how Prime Agent preserves kernel state during context compaction with dill snapshots. Ensure seamless continuity for your IPython kernel processes.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: internals
- Published: 2026-08-15

---

**Prime Agent preserves IPython kernel state across context compaction by taking a `dill`-based snapshot of the kernel namespace before trimming the chat transcript, then restoring that snapshot to either the running kernel or a fresh process afterwards.**

The Prime Agent project maintains a persistent Python execution environment that survives conversation turns, tool calls, and automatic context management. When token limits trigger **context compaction**—the process of summarizing or dropping older messages to stay within budget—the system must ensure that variables, imports, and helper functions created by the model remain available. This article explains the complete kernel state preservation mechanism as implemented in the `PrimeIntellect-ai/prime-agent` codebase.

## The Kernel Persistence Challenge

Long-running agent sessions accumulate two distinct types of state:

- **Conversational context**: the message history sent to and from the language model
- **Execution kernel state**: live Python objects, imports, and defined functions in the IPython namespace

Trimming the conversation transcript is computationally straightforward, but naive approaches would destroy the kernel's in-memory environment. Prime Agent solves this by serializing the entire kernel namespace to disk before compaction, then reloading it afterward.

## The State Snapshot Workflow

The preservation logic follows a three-phase pattern orchestrated by [`src/core/compaction/compaction.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/core/compaction/compaction.ts).

### Phase 1: Capturing the Kernel Snapshot

Before any messages are removed, `KernelManager.saveSnapshot()` writes the complete kernel namespace to the session's artifact directory.

```typescript
// src/core/kernel/state-snapshot.ts
await this.kernelManager.saveSnapshot(artifactDir);

```

The implementation in [`state-snapshot.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/state-snapshot.ts) uses the **`dill` serialization library**, which extends Python's standard `pickle` to handle complex objects including:

- Nested functions and lambdas
- Module references
- Custom class instances
- Closures and dynamically generated code

Two files are produced:

- `kernel-state.dill` — the binary serialized namespace
- [`kernel-state.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/kernel-state.json) — metadata tracking snapshot version and creation timestamp

### Phase 2: Compaction Executes

With the snapshot secured, the compaction algorithm processes the message transcript in [`src/core/compaction/compaction.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/core/compaction/compaction.ts):

```typescript
// src/core/compaction/compaction.ts (high-level flow)
async function compactSession(session: AgentSession) {
  await session.kernelManager.saveSnapshot(session.artifactDir);
  const result = await runCompactionAlgorithm(session.messages);
  await session.kernelManager.restoreSnapshot(session.artifactDir);
  return result;   // includes a `compactionSummary` message
}

```

The kernel continues running during this phase. If memory pressure or version compatibility requires a restart, the serialized state on disk enables full recovery.

### Phase 3: Restoring Kernel State

`KernelManager.restoreSnapshot()` handles two scenarios:

- **Hot restore**: If the original kernel process is still alive, the snapshot is reloaded into its namespace directly
- **Cold restore**: If the kernel was terminated, a fresh process is spawned and the snapshot is un-pickled into the new namespace

```typescript
// src/core/kernel/state-snapshot.ts
await this.kernelManager.restoreSnapshot(artifactDir);

```

The restored kernel contains identical objects, function definitions, and imported modules. From the model's perspective, execution continues seamlessly.

## Session Bookkeeping and UI Integration

### Compaction Event Tracking

[`src/modes/agent-connection/snapshot.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/modes/agent-connection/snapshot.ts) maintains session metadata during compaction:

- Emits `compaction_start` and `compaction_end` events
- Increments `compactionCount` for session analytics
- Records timing and token savings metrics

This telemetry feeds into [`src/core/telemetry.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/core/telemetry.ts) for debugging and usage analytics.

### User-Facing Compaction Indicators

The UI communicates state preservation through [`src/modes/interactive/components/compaction-summary-message.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/modes/interactive/components/compaction-summary-message.ts):

```typescript
// src/modes/interactive/components/compaction-summary-message.ts
// Renders a UI banner like “[compaction] context reduced, kernel state preserved”

```

The feature hint system in [`src/modes/interactive/feature-hints.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/modes/interactive/feature-hints.ts) explicitly informs users that **"Prime Agent keeps IPython variables and helpers between turns and compactions."**

| Component | Source File | Purpose |
|-----------|-------------|---------|
| Snapshot serialization | [`src/core/kernel/state-snapshot.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/core/kernel/state-snapshot.ts) | `dill`-based namespace capture and restoration |
| Compaction orchestration | [`src/core/compaction/compaction.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/core/compaction/compaction.ts) | Coordinates snapshot → trim → restore workflow |
| Event tracking | [`src/modes/agent-connection/snapshot.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/modes/agent-connection/snapshot.ts) | Session state updates during compaction |
| UI notification | [`src/modes/interactive/components/compaction-summary-message.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/modes/interactive/components/compaction-summary-message.ts) | User-visible compaction status |
| Feature documentation | [`src/modes/interactive/feature-hints.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/modes/interactive/feature-hints.ts) | In-product explanation of state preservation |
| Analytics | [`src/core/telemetry.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/core/telemetry.ts) | `compactionCount` and performance metrics |
| Correctness verification | [`test/kernel-state-roundtrip.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/test/kernel-state-roundtrip.test.ts) | Integration tests for snapshot fidelity |

## Asynchronous Operation and Input Queuing

The compaction workflow is **fully asynchronous**. User input received during an active compaction is held in a queue and processed only after `restoreSnapshot()` completes. This prevents race conditions where new code execution might interact with a partially-restored kernel state.

The queuing mechanism ensures that:

- Kernel restoration always precedes new execution requests
- Snapshot files remain locked during read/write operations
- Failed restorations trigger session recovery protocols rather than silent data loss

## Testing Kernel State Round-Trips

Correctness is validated in [`test/kernel-state-roundtrip.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/test/kernel-state-roundtrip.test.ts), which verifies:

```typescript
// Conceptual test structure from test/kernel-state-roundtrip.test.ts
// 1. Execute Python code to create complex objects
// 2. Trigger saveSnapshot()
// 3. Simulate compaction (optionally restart kernel)
// 4. Trigger restoreSnapshot()
// 5. Assert all objects are identical and functional

```

These tests cover edge cases including circular references, dynamically created classes, and large NumPy arrays—all objects that `dill` handles but standard `pickle` cannot.

## Summary

- **State snapshots use `dill` serialization** in [`src/core/kernel/state-snapshot.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/core/kernel/state-snapshot.ts) to capture the complete IPython namespace
- **Three-phase workflow**: capture → compact transcript → restore, coordinated by [`src/core/compaction/compaction.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/core/compaction/compaction.ts)
- **Hot and cold restore paths** handle both running kernels and fresh process starts
- **Asynchronous queuing** prevents input processing during active compaction
- **Full test coverage in [`test/kernel-state-roundtrip.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/test/kernel-state-roundtrip.test.ts)** ensures snapshot fidelity across complex object graphs

## Frequently Asked Questions

### What serialization library does Prime Agent use for kernel state?

Prime Agent uses **`dill`**, an extension of Python's standard `pickle` module. The `dill` library can serialize objects that `pickle` cannot, including nested functions, lambdas, and dynamically defined classes. This implementation lives in [`src/core/kernel/state-snapshot.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/core/kernel/state-snapshot.ts).

### Can kernel state be preserved if the process crashes during compaction?

Yes. Because `saveSnapshot()` writes to disk before compaction begins, the kernel can be fully restored even if the original process terminates. The `restoreSnapshot()` method in [`src/core/kernel/state-snapshot.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/core/kernel/state-snapshot.ts) handles both hot restores to running kernels and cold restores to fresh processes.

### How does the user know when compaction has occurred?

The UI displays a compaction banner through [`src/modes/interactive/components/compaction-summary-message.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/src/modes/interactive/components/compaction-summary-message.ts), typically reading "[compaction] context reduced, kernel state preserved." The session also inserts a `compactionSummary` message into the chat history for transparency.

### Does context compaction affect the model's access to previously defined variables?

No. The kernel namespace is fully restored after compaction, so all variables, functions, imports, and temporary data remain available. From the model's perspective, only the conversation history has changed—the execution environment is unchanged.