Stable Memory

If you're building on Internet Computer, this is your guide to not losing user data when you upgrade a canister. It covers the persistent actor pattern in Motoko (where `let` and `var` just work automatically) and StableBTreeMap with MemoryManager in Rust (because thread_local RefCell gets wiped on every deploy). The mistakes section is genuinely useful: it walks through the pre_upgrade instruction trap that bricks canisters, the type change gotchas in Motoko, and why Bound::Unbounded beats Bound::Bounded for forward compatibility. Includes working code for both languages with CBOR serialization. Read this before your first canister upgrade, not after you've lost production data.

skills.sh installs: 320
GitHub stars: 39
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add dfinity/icskills --skill stable-memory --agent claude-code

Installs into .claude/skills of the current project.

Files

Stable Memory & Canister Upgrades

What This Is

Stable memory is persistent storage on Internet Computer that survives canister upgrades. Whether ordinary variables survive depends on the language:

Rust -- heap data (thread_local! { RefCell<T> }, plain statics) is wiped on every upgrade. Any data you care about must live in stable memory, either through ic-stable-structures or by serializing it yourself in pre_upgrade/post_upgrade.
Motoko -- enhanced orthogonal persistence is on by default, so let and var in a persistent actor already survive upgrades with no stable keyword and no upgrade hooks. Only transient declarations are wiped.

Prerequisites

For Motoko: mops with core = "2.0.0" in mops.toml, and moc >= 1.7.0 (dot notation on Map/List needs it)
For Rust: ic-stable-structures = "0.7" in Cargo.toml