# Terminal Memory Reclamation in Nodeterm: 6 Mechanisms Explained

> Discover how Nodeterm reclaims terminal memory with 6 mechanisms: off-screen release, park-budget timeouts, idle-session reapers, Eco hibernation, session-memory services, and memory-pressure killers. Preserve tmux continuity w...

- Repository: [eneskirca/nodeterm](https://github.com/eneskirca/nodeterm)
- Tags: internals
- Published: 2026-08-25

---

**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`](https://github.com/eneskirca/nodeterm/blob/main/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`](https://github.com/eneskirca/nodeterm/blob/main/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`](https://github.com/eneskirca/nodeterm/blob/main/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`](https://github.com/eneskirca/nodeterm/blob/main/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`](https://github.com/eneskirca/nodeterm/blob/main/src/core/session-memory-service.ts) and [`src/core/session-memory.ts`](https://github.com/eneskirca/nodeterm/blob/main/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`](https://github.com/eneskirca/nodeterm/blob/main/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:

```typescript
// 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`](https://github.com/eneskirca/nodeterm/blob/main/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`](https://github.com/eneskirca/nodeterm/blob/main/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`](https://github.com/eneskirca/nodeterm/blob/main/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`](https://github.com/eneskirca/nodeterm/blob/main/src/renderer/terminal/hibernation-policy.ts)) kills heavy agent CLIs while keeping terminal viewers active.
- **Session-memory service** ([`src/core/session-memory-service.ts`](https://github.com/eneskirca/nodeterm/blob/main/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`](https://github.com/eneskirca/nodeterm/blob/main/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`](https://github.com/eneskirca/nodeterm/blob/main/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.