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

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. 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.

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

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

// 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, 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)

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

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

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

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

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	Schema definitions: HardwareSnapshot, HardwareMemoryDomain, MemoryAssessment, MemoryDomainId, HardwareDeviceMemoryLimit
packages/icn/src/hardware/index.ts	IcnHardware service implementation
packages/icn/src/observed-state.ts	IcnObservedState / IcnMutableObservedState reactive wrappers
packages/icn/src/provider/source.ts	Provider‑side MemoryAssessment production
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, 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 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.

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