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

> Discover how the RLM child registry survives parent session compaction by serializing entries to an RlmSpawnLedger file, ensuring child agent metadata persistence through shutdowns.

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

---

**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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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

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

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

```typescript
// 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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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.