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

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, the runtime layer exposes this registry to the kernel with a clear architectural intent:

/** 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, 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:

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

This snapshot is referenced in 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:

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

Test assertions in 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.

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:

{
  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. Since the registry object was never modified, the runtime's reference remains valid:

// 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

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	Exposes parent session's child registry to kernel	Line 182 (registry exposure comment)
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	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 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 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 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.

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