# How Child Registries Are Managed During Prime Agent's Context Compaction

> Discover how Prime Agent manages child registries during context compaction. Learn how the conversation transcript is trimmed and a synthetic summary preserves registry state.

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

---

**Prime Agent preserves the child registry intact during context compaction, only trimming the conversation transcript and inserting a synthetic compaction summary that exposes the registry state to the model.**

Prime Agent is an open-source coding agent framework that maintains hierarchical sessions with sub-agents. When a session's context grows beyond token limits, the system performs **context compaction** — a process that must carefully handle the **child registry**, the source of truth for the `rlm.list_subagents` API. This article examines how Prime Agent's source code manages this registry throughout the compaction lifecycle, referencing actual file paths and implementation details from the PrimeIntellect-ai/prime-agent repository.

## What Is the Child Registry in Prime Agent

The **child registry** is an internal data structure that tracks all active sub-agents spawned from a parent session. It powers the model-facing `rlm.list_subagents` API, allowing LLM-based tooling to inspect, manage, and communicate with child agents dynamically.

In [`packages/coding-agent/src/core/rlm-runtime.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/rlm-runtime.ts), the runtime layer exposes this registry to the kernel with a clear architectural intent:

```typescript
/** Expose the current parent session's RLM child registry to its kernel. */

```

This comment appears near line 182 of the runtime file, establishing the registry as a first-class abstraction passed between the session manager and the execution kernel.

The registry is stored as `session._childRegistry` in [`packages/coding-agent/src/core/agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session.ts), making it accessible for both normal operations and compaction scenarios.

## The Context Compaction Lifecycle

Prime Agent triggers compaction in two scenarios:
- **Token threshold reached** — automatic compaction when the transcript exceeds `maxTokens`
- **Manual compaction** — explicit `compact()` call with custom `keepRecentTokens` policy

Regardless of trigger, the child registry follows a consistent preservation pattern across seven coordinated steps.

### Step 1: Snapshot the Current Child Registry

Before any transcript modification occurs, the session captures the registry state:

```typescript
// session._childRegistry holds the authoritative registry
const registrySnapshot = this._childRegistry;

```

This snapshot is referenced in [`packages/coding-agent/src/core/agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session.ts) around line 9163. The registry object itself is never serialized or copied — the snapshot is simply a reference used to generate the compaction summary.

### Step 2: Emit the `compaction_start` Event

The session manager records compaction initiation with contextual metadata:

```typescript
{
  type: "compaction_start",
  reason: "manual" | "threshold",
  timestamp: Date.now()
}

```

Test assertions in [`packages/coding-agent/test/suite/agent-session-compaction.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/suite/agent-session-compaction.test.ts) (lines 138-139) verify this event fires correctly, providing observability hooks for downstream systems.

### Step 3: Prune the Transcript

The actual context reduction applies only to the conversation transcript according to the `keepRecentTokens` policy. Critically, **the child registry is excluded from this pruning** — it remains fully intact in memory.

This separation ensures that:
- Sub-agent handles remain valid
- In-flight operations on children can complete
- The `rlm.list_subagents` API returns consistent results pre- and post-compaction

### Step 4: Insert the Compaction Summary

After pruning, Prime Agent synthesizes a summary message with `role: "compactionSummary"`. This message contains a compacted representation of the child registry — sufficient for the model to understand which sub-agents exist without requiring the full transcript history.

```typescript
const summaryMessage = {
  role: "compactionSummary",
  content: generateRegistrySummary(registrySnapshot),
  metadata: {
    compactionTime: Date.now(),
    childrenRetained: registrySnapshot.size
  }
};
this.transcript.push(summaryMessage);

```

The summary acts as a **checkpoint** — the model can reason about child agents even though their creation history has been erased from context.

### Step 5: Emit the `compaction_end` Event

Completion is signaled with severity classification:

```typescript
{
  type: "compaction_end",
  errorSeverity: "warning" // for benign compaction without state loss
}

```

Lines 2149-2154 of the compaction test suite validate this event structure, ensuring the severity field properly distinguishes between routine and problematic compactions.

### Step 6: Runtime Registry Exposure

The kernel maintains access through `RLMChildRegistry` as established in [`rlm-runtime.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/rlm-runtime.ts). Since the registry object was never modified, the runtime's reference remains valid:

```typescript
// List children remains functional throughout compaction
const children = await rlm.list_subagents(); // unchanged behavior

```

This continuity is essential for long-running agent workflows where compaction may occur mid-task.

### Step 7: Post-Compaction Continuation

Queued operations — such as pending `followUp` calls or scheduled refinements — are deferred until after the `compaction_end` event. Test coverage at lines 242-250 verifies that inputs queued before compaction are treated as "queued work" and proceed normally afterward.

## Practical Code Example

```typescript
import { AgentSession } from '@prime-intellect/agent-core';

async function demonstrateRegistryPreservation() {
  // Initialize session
  const session = await AgentSession.create();
  
  // Spawn a sub-agent (adds to registry)
  await session.run(`Create a coding assistant named "refactor-helper"`);
  
  // Verify registry contains the child
  const beforeCompaction = await session.rlm.list_subagents();
  console.log(beforeCompaction); 
  // → [{ name: "refactor-helper", id: "sub-uuid-123", ... }]
  
  // Trigger manual compaction with aggressive token limit
  await session.compact({ keepRecentTokens: 1 });
  
  // Registry remains accessible and identical
  const afterCompaction = await session.rlm.list_subagents();
  console.log(afterCompaction); 
  // → [{ name: "refactor-helper", id: "sub-uuid-123", ... }]
  
  // Transcript now contains summary instead of full history
  const lastMessage = session.transcript[session.transcript.length - 1];
  console.log(lastMessage.role); // "compactionSummary"
  console.log(lastMessage.metadata.childrenRetained); // 1
}

```

## Key Implementation Files

| File | Purpose | Key Line References |
|------|---------|---------------------|
| [`packages/coding-agent/src/core/rlm-runtime.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/rlm-runtime.ts) | Exposes parent session's child registry to kernel | Line 182 (registry exposure comment) |
| [`packages/coding-agent/src/core/agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session.ts) | Stores `_childRegistry` and orchestrates compaction | Line 9163 (registry property) |
| [`packages/coding-agent/test/suite/agent-session-compaction.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/suite/agent-session-compaction.test.ts) | Validated compaction events, summary insertion, registry preservation | Lines 138-139 (`compaction_start`), 2149-2154 (`compaction_end` severity), 242-250 (queued work handling) |

## Summary

- **Preservation, not pruning**: The child registry survives context compaction unchanged; only the transcript is reduced.
- **Summary synthesis**: A `compactionSummary` message captures registry state for model visibility without historical overhead.
- **Event-driven lifecycle**: `compaction_start` and `compaction_end` events provide observability and synchronization hooks.
- **Runtime continuity**: The [`rlm-runtime.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/rlm-runtime.ts) layer maintains kernel access to the registry throughout compaction, ensuring `list_subagents` behaves consistently.
- **Test coverage**: The compaction test suite validates registry preservation across manual and threshold-triggered scenarios.

## Frequently Asked Questions

### Does context compaction delete sub-agents or just hide them from the transcript?

Sub-agents remain fully operational. The child registry is preserved in memory, and only the conversation transcript is pruned. The compaction summary message ensures the model retains awareness of existing children without their full creation history.

### How does `rlm.list_subagents` work after compaction if the creation context was removed?

The API queries the live `session._childRegistry` object, not the transcript. Since this registry is never modified during compaction, `list_subagents` returns identical results before and after. The model uses the `compactionSummary` message to understand the registry state without requiring historical messages.

### What happens to in-flight operations on child agents during compaction?

Operations queued before compaction are deferred until after the `compaction_end` event, as validated in [`agent-session-compaction.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/agent-session-compaction.test.ts) lines 242-250. Active operations continue uninterrupted because the registry reference remains stable throughout the compaction process.

### Can I configure how much of the child registry appears in the compaction summary?

The current implementation in [`agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/agent-session.ts) generates a complete registry summary. The `childrenRetained` count in summary metadata reflects the full registry size. For customized summary granularity, you would extend the `generateRegistrySummary` function in your Prime Agent fork.