# Magnitude ICN Memory Abstractions: A Complete Guide to Hardware-Aware Agent Orchestration

> Explore Magnitude ICN memory abstractions including HardwareSnapshot, HardwareMemoryDomain, MemoryAssessment, and IcnObservedState. Learn how Magnitude orchestrates agents for heterogeneous hardware environments.

- Repository: [Magnitude/magnitude](https://github.com/magnitudedev/magnitude)
- Tags: deep-dive
- Published: 2026-09-06

---

**Magnitude's ICN (Inter‑Component Network) uses typed, schema‑driven abstractions—`HardwareSnapshot`, `HardwareMemoryDomain`, `MemoryAssessment`, and `IcnObservedState`—to model memory capacity, allocation, and assessment across heterogeneous hardware environments.**

Magnitude's ICN memory abstractions enable agent orchestration systems to reason about hardware resources in a type‑safe, observable manner. These abstractions are defined in the **`icn-protocol`** schema package and consumed by the **`icn`** runtime, providing a deterministic view of system memory for model loading and workload placement decisions.

## Core Memory Types in the ICN Protocol Schema

The foundational memory abstractions live in [`packages/icn-protocol/src/generated/schemas.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/icn-protocol/src/generated/schemas.ts). These types capture everything from raw capacity measurements to workload‑specific memory requirements.

### HardwareSnapshot: The System‑Wide Memory View

**`HardwareSnapshot`** represents a complete point‑in‑time capture of system hardware, including CPU details, architecture, and—critically—an array of `memory_domains`.

```typescript
// Location: packages/icn-protocol/src/generated/schemas.ts#L1112
// Represents: CPU, arch, and memory_domains[]

```

This snapshot serves as the single source of truth for memory state across the ICN.

### HardwareMemoryDomain: Logical Memory Regions

**`HardwareMemoryDomain`** describes a logical memory partition—system RAM, physical device memory, or unified memory pools. Each domain exposes:

- **`total_capacity_bytes`**: Total bytes available in the domain
- **`current_free_bytes`**: Optional free space measurement
- **`shares_system_memory`**: Boolean flag indicating participation in the system‑wide memory pool
- **`devices`**: Array of `HardwareDevice` objects with their own memory limits

```typescript
// Location: packages/icn-protocol/src/generated/schemas.ts#L1088
// Key fields: capacity, free bytes, device associations

```

Every `HardwareMemoryDomain` is identified by a **`MemoryDomainId`**—a branded string type that prevents accidental mixing of domain identifiers across different contexts.

### MemoryAssessment: Workload‑Level Memory Requirements

When providers (such as model loaders) need to determine if a workload fits in available memory, they construct a **`MemoryAssessment`**. This type quantifies:

| Field | Purpose |
|-------|---------|
| `requiredBytes` | Bytes needed by the workload |
| `remainingBytes` | Bytes still available after allocation |
| `capacityBytes` | Total domain capacity |
| `compatibilityReserveBytes` | Safety margin for OS/kernel overhead |
| `memoryDomainId` | Target `MemoryDomainId` for placement |

```typescript
// Location: packages/icn-protocol/src/generated/schemas.ts#L1418
// Consumed by providers to report model load feasibility

```

### HardwareDeviceMemoryLimit: Per‑Device Constraints

Within each `HardwareMemoryDomain`, individual devices may carry **`HardwareDeviceMemoryLimit`** objects. These describe *recommended working set* limits that constrain how much of a device's memory should be allocated to any single model—preventing over‑commitment that could degrade performance.

## Runtime Observation Abstractions

The ICN runtime adds observable, effect‑based wrappers around the static schema types.

### IcnObservedState and IcnMutableObservedState

**`IcnObservedState`** and its mutable variant **`IcnMutableObservedState`** provide a reactive abstraction for any ICN schema type. Defined in [`packages/icn/src/observed-state.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/icn/src/observed-state.ts), these wrappers:

- Store a `SubscriptionRef` containing the current snapshot
- Expose a `refresh` effect that re‑reads the underlying ICN RPC
- Publish a new snapshot only when data diverges (deduplicated updates)

```typescript
// Location: packages/icn/src/observed-state.ts
// Pattern: SubscriptionRef + refresh effect + change notifications

```

### IcnHardware: The Concrete Memory Service

**`IcnHardware`** in [`packages/icn/src/hardware/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/icn/src/hardware/index.ts) builds on `IcnObservedState<HardwareSnapshot>`. It:

1. Subscribes to ICN hardware events
2. Periodically refreshes the hardware snapshot
3. Surfaces the latest memory view to the rest of the platform

```typescript
// Create the hardware service layer (refreshes every 2 seconds)
import { IcnHardware, makeIcnHardware } from "@magnitudedev/icn";

const hardwareLayer = makeIcnHardware({ refreshInterval: "2 seconds" });

```

## How Memory Abstractions Compose: The Data Flow

The ICN memory abstractions work together in a predictable pipeline:

1. **Snapshot acquisition** — `IcnHardware` calls `client.system.getHardware({})` to fetch a fresh `HardwareSnapshot`.

2. **Domain enumeration** — The snapshot's `memory_domains` array exposes all logical memory regions, each with a unique `MemoryDomainId` and `shares_system_memory` flag.

3. **Device limit application** — Within each domain, `devices` carry `HardwareDeviceMemoryLimit` values that bound per‑model allocation.

4. **Assessment construction** — Providers create `MemoryAssessment` objects linking byte‑level requirements to specific `memoryDomainId` targets.

5. **Observable propagation** — `makeIcnObservedState` wraps everything in a reactive layer; callers use `get`, `changes`, and `refresh` for consistent, non‑polling access.

## Working with ICN Memory Abstractions: Code Examples

### Consuming Hardware Snapshots in Effects

```typescript
import { Effect } from "effect";
import { IcnHardware } from "@magnitudedev/icn";

const reportMemory = Effect.gen(function* () {
  const hardware = yield* IcnHardware;           // Resolve the service layer
  const snapshot = yield* hardware.get;          // Latest HardwareSnapshot
  const domains = snapshot.state.memory_domains; // HardwareMemoryDomain[]

  for (const d of domains) {
    console.log(
      `Domain ${d.id} (type ${d.kind}) – ` +
      `free: ${d.current_free_bytes?.value ?? "N/A"} / ` +
      `total: ${d.total_capacity_bytes}`
    );
  }
});

```

### Constructing a MemoryAssessment

```typescript
import { MemoryAssessment, MemoryDomainId } from "@magnitudedev/icn-protocol";

const assessment: MemoryAssessment = {
  capacityBytes: 8_589_934_592,           // 8 GiB domain total
  compatibilityReserveBytes: 512_000_000,  // OS/kernel reserve
  memoryDomainId: "system" as MemoryDomainId,
  remainingBytes: 5_000_000_000,
  requiredBytes: 2_147_483_648,            // 2 GiB model requirement
};

```

### Manual Refresh Triggering

```typescript
import { Effect } from "effect";
import { IcnHardware } from "@magnitudedev/icn";

const forceRefresh = Effect.gen(function* () {
  const hardware = yield* IcnHardware;
  yield* hardware.refresh;  // RPC call + snapshot update on change
});

```

## Key Source Files

| File | Responsibility |
|------|---------------|
| [`packages/icn-protocol/src/generated/schemas.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/icn-protocol/src/generated/schemas.ts) | Schema definitions: `HardwareSnapshot`, `HardwareMemoryDomain`, `MemoryAssessment`, `MemoryDomainId`, `HardwareDeviceMemoryLimit` |
| [`packages/icn/src/hardware/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/icn/src/hardware/index.ts) | `IcnHardware` service implementation |
| [`packages/icn/src/observed-state.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/icn/src/observed-state.ts) | `IcnObservedState` / `IcnMutableObservedState` reactive wrappers |
| [`packages/icn/src/provider/source.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/icn/src/provider/source.ts) | Provider‑side `MemoryAssessment` production |
| [`packages/icn/src/instances/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/icn/src/instances/index.ts) | Per‑instance memory domain management |

## Summary

- **Magnitude ICN memory abstractions** are schema‑driven types in `icn-protocol` with reactive runtime wrappers in `icn`.
- **`HardwareSnapshot`** provides the system‑wide view; **`HardwareMemoryDomain`** breaks this into logical, identifiable regions via **`MemoryDomainId`**.
- **`MemoryAssessment`** lets providers declare workload memory needs with explicit domain targeting.
- **`IcnObservedState`** and **`IcnHardware`** turn static snapshots into observable, refreshable services using Effect's `SubscriptionRef` pattern.
- The architecture eliminates polling overhead, guarantees type safety across RPC boundaries, and enables deterministic hardware‑aware orchestration.

## Frequently Asked Questions

### What is the difference between HardwareMemoryDomain and MemoryAssessment?

**`HardwareMemoryDomain`** describes available memory resources—capacity, free space, and device associations. **`MemoryAssessment`** describes memory *demand* from a workload—required bytes, remaining headroom, and the target domain. The ICN uses domain objects to represent supply and assessment objects to represent demand.

### How does IcnHardware avoid excessive RPC polling?

`IcnHardware` leverages `makeIcnObservedState` from [`packages/icn/src/observed-state.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/icn/src/observed-state.ts), which wraps the snapshot in a `SubscriptionRef`. The `refresh` effect re‑reads the ICN RPC, but downstream consumers only receive updates when the actual data diverges—deduplication happens automatically.

### Can a MemoryDomainId refer to non‑system memory?

Yes. While `"system"` is a common `MemoryDomainId` value for host RAM, the branded string type supports arbitrary identifiers. Device‑local memory and unified memory pools each receive their own `MemoryDomainId`, and the `shares_system_memory` boolean on `HardwareMemoryDomain` indicates whether a domain participates in the system‑wide pool.

### Where do providers create MemoryAssessment objects?

Providers typically construct assessments in [`packages/icn/src/provider/source.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/icn/src/provider/source.ts) or equivalent provider implementation files. The assessment is then evaluated against the current `HardwareSnapshot` to determine if a model can safely load in the requested domain.