Terminal Memory Reclamation in Nodeterm: 6 Mechanisms Explained

Nodeterm employs six complementary mechanisms—off-screen release, park-budget timeouts, idle-session reapers, Eco hibernation, session-memory services, and memory-pressure killers—to reclaim RAM across viewer, process, and session layers while preserving tmux continuity.

Nodeterm stores terminal output, PTY client state, and agent processes across multiple memory layers. To prevent uncontrolled RAM growth and maintain application responsiveness, the codebase implements a comprehensive terminal memory reclamation architecture that operates independently yet hierarchically. According to the eneskirca/nodeterm source code, these mechanisms ensure that hidden or idle terminals free resources progressively—from UI buffers up to full process trees—without destroying user work.

The Reclamation Hierarchy

Nodeterm organizes memory cleanup into three distinct levels. Viewer-level reclamation removes Xterm UI instances and PTY client buffers (approximately 15 MiB). Process-level reclamation terminates heavy agent CLI processes while keeping the terminal UI intact. Session-level reclamation destroys entire tmux sessions, freeing the largest memory chunks including shell environments and subprocess trees. This tiered approach ensures short-lived viewers are reclaimed before persistent sessions are destroyed.

Off-Screen Release

The offscreen-policy mechanism detaches the Xterm UI and disposes the PTY client while keeping the underlying tmux session alive. This reclaims approximately 15 MiB per terminal when a node remains completely outside the viewport for the duration specified by settings.offscreenTerminalMinutes (default 10 minutes).

In src/renderer/terminal/offscreen-policy.ts, the mayDisposeOffscreen function first verifies that the node is not visible, not remote, and not selected. It then arms a timer via offscreenDisposeMs (lines 36-40). If the timer fires while the node remains off-screen, planOffscreenVisibility (lines 88-99) tears down the viewer. The system specifically protects remote SSH sessions through offscreenCoreIsRemote, preventing disposal that would require re-establishing ControlMaster connections.

Park-Budget Timeout

The TERM_PARK_MS mechanism keeps the Xterm instance and PTY client in memory but stops rendering after the user pans away. The terminal enters a "parked" state for up to 5 minutes (configurable), after which the PTY client is killed while the tmux session persists.

As documented in src/core/pty-manager.ts at line 751, this represents the first step in a three-step ordering: park → off-screen → idle reap. When a node becomes invisible, a debounce timer starts. If the node is not brought back into view before TERM_PARK_MS elapses, the PTY client detaches, freeing renderer resources while maintaining session state.

Idle-Session Reaper

The REAP_IDLE_MS mechanism terminates entire tmux sessions—including their shell and agent processes—when activity ceases for extended periods (default 30 minutes). This reclaims the full process tree, potentially hundreds of megabytes.

Implemented in src/core/pty-manager.ts, this reaper runs after the off-screen and park steps complete. By waiting for viewer-level cleanup first, the system ensures that transient terminals are reclaimed efficiently before destroying persistent sessions that might contain long-running background jobs.

Eco Hibernation

The hibernation-policy stops the agent CLI inside a tmux pane (potentially hundreds of megabytes) while leaving the terminal UI intact and interactive. This targets agent nodes specifically when they are done, off-screen, and idle for settings.agentHibernationIdleMinutes (default 30 minutes).

In src/renderer/terminal/hibernation-policy.ts, the shouldDeferReleaseForEco function (lines 43-66) evaluates these criteria. A sweep runs every 5 seconds to identify qualifying nodes, killing the heavy agent process while preserving the lightweight terminal viewer.

Session-Memory Service

The session-memory-service provides on-demand reclamation through the RAM pill UI. Located in src/core/session-memory-service.ts and src/core/session-memory.ts, this service scans all tmux sessions on the host, gathers per-process RSS metrics, and allows users to kill individual sessions manually.

This mechanism activates when users open the session-memory panel or when the system detects memory pressure, offering granular control over which specific sessions to terminate rather than applying automatic heuristics.

Memory-Pressure Killer

The memory-pressure module reacts to OS-level low-memory notifications by proactively terminating the largest detached tmux sessions. When macOS or Linux reports critical memory pressure, the system updates the UI to show reclaimed sessions and frees substantial RAM by targeting detached sessions first.

The implementation in src/core/memory-pressure.ts ensures that only sessions not currently attached to viewers are candidates for termination, preventing disruption of active work while alleviating system memory constraints.

Configuration and Usage

You can customize reclamation behavior through the settings API:

// Reduce off-screen timeout to 5 minutes
settings.offscreenTerminalMinutes = 5;

// Enable Eco hibernation for agent processes
settings.agentHibernationEnabled = true;
settings.agentHibernationIdleMinutes = 30;

// Manually kill a specific tmux session via the RAM pill
await window.nodeTerminal.sessionMemory.kill('nt-abc123');

Summary

• Off-screen release (src/renderer/terminal/offscreen-policy.ts) disposes PTY clients and Xterm UIs after 10 minutes off-screen, reclaiming ~15 MiB while preserving tmux sessions.
• Park-budget timeout (src/core/pty-manager.ts) pauses rendering and eventually detaches PTY clients after 5 minutes of invisibility.
• Idle-session reaper (src/core/pty-manager.ts) terminates complete tmux sessions after 30 minutes of idle time, freeing entire process trees.
• Eco hibernation (src/renderer/terminal/hibernation-policy.ts) kills heavy agent CLIs while keeping terminal viewers active.
• Session-memory service (src/core/session-memory-service.ts) provides manual session termination via the RAM pill UI with per-process RSS visibility.
• Memory-pressure killer (src/core/memory-pressure.ts) automatically reclaims the largest detached sessions when the OS reports low memory.

Frequently Asked Questions

What is the difference between parking and off-screen release in Nodeterm?

Parking (TERM_PARK_MS) stops rendering the terminal but keeps the PTY client in memory for up to 5 minutes, allowing quick restoration if you pan back. Off-screen release completely detaches the Xterm UI and disposes the PTY client after 10 minutes, reclaiming the full 15 MiB viewer memory while the tmux session persists in the background.

How does Nodeterm protect remote SSH sessions from memory reclamation?

The offscreenCoreIsRemote check in src/renderer/terminal/offscreen-policy.ts (lines 8-11) prevents off-screen disposal for remote nodes. This protection ensures that reviving a remote session does not require re-establishing a ControlMaster connection, avoiding latency and authentication overhead for SSH-based terminals.

Can I configure the automatic memory reclamation timeouts?

Yes. You can set settings.offscreenTerminalMinutes to change the off-screen disposal delay (default 10 minutes) and settings.agentHibernationIdleMinutes to adjust the Eco hibernation threshold (default 30 minutes). These settings apply per-workspace and take effect immediately without requiring a restart.

What happens to my running processes when Nodeterm reclaims terminal memory?

It depends on the mechanism. Viewer-level reclamation (off-screen/park) preserves all processes within the tmux session. Eco hibernation kills only the agent CLI process. Session-level reclamation (idle reaper/memory-pressure) terminates the entire tmux session and all its subprocesses. Your work remains safe unless the idle reaper or memory-pressure killer activates on a detached session.

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