How the RLM Child Registry Survives Parent Session Compaction in Prime Agent

The RLM child registry persists through parent session compaction by serializing the RlmSubagentRegistryEntry array to a standalone RlmSpawnLedger file in the session directory, ensuring child agent metadata survives in-memory state flushes and complete shutdowns.

The PrimeIntellect-ai/prime-agent repository implements a Recursive Language Model (RLM) framework where parent agents spawn child sub-agents tracked in a runtime registry. When an AgentSession undergoes compaction—a process that flushes in-memory state to disk to reduce resource usage—this child registry must survive to maintain the parent-child relationship hierarchy according to the source code implementation.

Understanding the RLM Child Registry Structure

The child registry lives inside the parent AgentSession runtime and maintains a record of every spawned sub-agent.

RlmSubagentRegistryEntry Interface

In packages/coding-agent/src/core/rlm-runtime.ts at lines 24-31, the registry entries follow the RlmSubagentRegistryEntry interface. Each entry tracks the RLM child ID, session name, current status, and session location, creating a comprehensive map of the parent agent's offspring.

The registry exists as an in-memory array within the active runtime, but its persistence relies on integration with the session's serialization lifecycle rather than transient memory alone.

The Compaction Survival Mechanism

When a parent session is compacted—meaning its in-memory state reduces to a lightweight persisted form—the registry is not discarded. Instead, the session implements a specific persistence protocol to anchor child metadata to disk.

Serializing to RlmSpawnLedger

The serialization process centers on the RLM spawn ledger (RlmSpawnLedger), which records every child spawn with its ID, name, status, and session location. During compaction, the parent AgentSession writes this ledger to the session directory before flushing its runtime state.

This write operation occurs in packages/coding-agent/src/core/rlm-spawn-ledger.ts (implicitly referenced in the codebase), ensuring the registry data is committed to storage prior to any memory release.

Session Directory Storage

The serialized data lives as a standalone file within the session's directory structure. Because the ledger file exists independently of the parent's in-memory runtime, the child registry survives even complete shutdown of the parent session, not just compaction events.

Restoring Registry Entries After Compaction

Upon session reload, the restoration process reconstructs the registry from the persisted ledger. In packages/coding-agent/src/core/rlm-runtime.ts, the AgentSession.restore() logic reads the ledger file from the session directory and repopulates the rlmSubagentRegistry array with RlmSubagentRegistryEntry objects.

This restoration ensures that parent agents regain knowledge of their children immediately upon reactivation, maintaining continuity in recursive agent workflows.

Kernel Exposure via Host Handlers

The registry remains accessible to external tooling regardless of compaction state through dedicated host handlers implemented in the runtime.

createRlmListSubagentsHostHandler

At lines 95-100 of packages/coding-agent/src/core/rlm-runtime.ts (with the list-subagents implementation at lines 195-200), the createRlmListSubagentsHostHandler exposes the current subagents array to the kernel. This handler returns the live registry state, whether freshly loaded from a compaction restore or actively maintained in memory.

Consequently, any kernel queries for child agents receive a consistent view of the registry, enabling reliable orchestration of multi-agent systems.

Practical Implementation Examples

The following patterns demonstrate how to interact with the persistent registry through the kernel and understand the underlying serialization mechanics.

Listing Parent RLM Children from the Kernel

// Kernel request (e.g., from a Python cell)
const result = await kernel.request("rlm.list_subagents");

// `result.subagents` contains the persisted registry entries
for (const child of result.subagents) {
  console.log(`Child ${child.session_name} (${child.rlm_child_id}) status: ${child.status}`);
}

Persisting the Registry During Session Compaction

// Inside AgentSession.compact()
await writeFile(
  join(this.sessionDir, "rlm-spawn-ledger.json"),
  JSON.stringify(this.rlmSubagentRegistry, null, 2)
);
// The in‑memory `rlmSubagentRegistry` is now safely stored on disk.

Restoring the Registry After Compaction

// Inside AgentSession.restore()
const ledgerPath = join(this.sessionDir, "rlm-spawn-ledger.json");
const persisted = JSON.parse(await readFile(ledgerPath, "utf8"));
this.rlmSubagentRegistry = persisted as RlmSubagentRegistryEntry[];

Summary

• The RLM child registry persists through compaction by serializing to a standalone ledger file in the session directory rather than remaining purely in memory.
• RlmSpawnLedger anchors child metadata during the compaction process, writing registry entries before the parent session flushes its state.
• Restoration occurs automatically when AgentSession.restore() reads the ledger and reconstructs the rlmSubagentRegistry array.
• Kernel access remains consistent via createRlmListSubagentsHostHandler, which exposes the current registry regardless of whether the session is compacted or active.
• Unit testing confirms durability in packages/coding-agent/test/suite/agent-session-runtime.test.ts at line 300, validating that the registry survives compact-restore cycles.

Frequently Asked Questions

What happens to the RLM child registry when a parent session is compacted?

When a parent session compacts, the registry is serialized to an RlmSpawnLedger file stored in the session directory. The in-memory subagents array is written to disk as JSON, ensuring no data loss occurs during the memory flush. This process occurs automatically within the AgentSession.compact() method before resources are released.

Where is the RLM child registry physically stored?

The registry is stored in a standalone ledger file, conventionally named rlm-spawn-ledger.json, located within the parent session's directory. This file contains the serialized RlmSubagentRegistryEntry array and persists independently of the runtime process, surviving both compaction events and complete application shutdowns.

How does the kernel access the child registry if the parent session is currently compacted?

The kernel accesses the registry through the createRlmListSubagentsHostHandler function defined in packages/coding-agent/src/core/rlm-runtime.ts. This handler returns the current subagents array maintained by the parent runtime. If the session is restored from a compacted state, the registry is already rehydrated from the ledger file, providing a consistent view to kernel callers immediately upon request.

Can child registry entries survive a complete system restart?

Yes, because the registry persists to the session directory's RlmSpawnLedger file rather than volatile memory alone. Upon system restart and session restoration, the AgentSession.restore() method reads the ledger file and reconstructs the full registry state, enabling long-term tracking of recursive agent hierarchies across multiple runtime sessions.

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