Technology
ICP Stable Memory Explained
When a canister is upgraded — new code, a bug fix, a feature — its state must survive. Ordinary program variables do not. The Internet Computer solves this with stable memory: a persistent storage layer inside the canister that lives across upgrades. Here is how it works and why it is the foundation of every on-chain app.
August 16, 2026 · 6 min read
Two kinds of canister memory
A canister has two memory regions:
- Wasm heap — ordinary memory used while code runs. Fast, but wiped when the canister is upgraded.
- Stable memory — a persistent region that survives upgrades and can grow to many gigabytes.
The rule of thumb: if a value must still exist after the next deploy, it belongs in stable memory — or in a framework that moves it there automatically.
Why upgrades survive
Deploying a new canister version replaces the WebAssembly code. Without stable memory, every upgrade would erase the user data, balances, and state the canister spent months building. With stable memory, the new code starts by reading the persistent region and resumes exactly where the old code left off.
In Motoko the mechanism is the stable attribute plus stable memory and preupgrade hooks; in Rust you manage it explicitly. Projects also run migrations — code that reshapes stored data as the schema evolves between versions.
Stable memory is your database
This is the conceptual shift: on the Internet Computer you do not reach for PostgreSQL. The canister's stable memory is the persistent store. Bucket metadata, file records, user profiles, transfer history — all of it lives in stable memory, replicated across the subnet and served by the same canister that runs the logic.
For an ICPay Cloud canister, that means:
- Bucket metadata — names, capacity, visibility, expiry.
- File metadata and the file bytes themselves.
- Owner principals and permission records.
- API keys and billing state.
Capacity and cost
Stable memory scales far beyond the Wasm heap — canisters can hold gigabytes of data, which is what makes file storage inside a canister practical. The cost follows the cycle model: storage burns cycles per month, pegged to XDR, with storage-only rates quoted around a few dollars per gigabyte per year depending on the subnet.
The trade-off against a managed database is real: you get atomic, replicated persistence with no external service, but you are responsible for migration discipline as your schema grows.
Migrations: the discipline that makes it safe
Because state is permanent, changing your data model requires a migration — code that runs on upgrade to reshape stored records. ICPay's backend, for example, carries migrations for every schema change, so a version bump reshapes old records in place rather than losing them. This is why "upgrade the canister without losing users" is a solved problem on ICP, and why stable memory is the backbone of custodial and storage apps.