Skip to content

Convex-Dev/convex / .claude/skills/memory

memory

Verified

Memory accounting and allowances — the cost of on-chain storage, and how to minimise and reclaim it. Use when reasoning about state growth, diagnosing a :MEMORY failure, or designing actors that store data.

FileKindSize
SKILL.mdskill md5.1 KB
---
name: memory
description: Memory accounting and allowances — the cost of on-chain storage, and how to minimise and reclaim it. Use when reasoning about state growth, diagnosing a :MEMORY failure, or designing actors that store data.
---

# Memory Accounting

Memory prices **storage**. Unlike juice, it is a stock: held as an allowance,
consumed when state grows, and **refunded when state shrinks**. Computation is
priced separately — see the `juice` skill.

On-chain storage is potentially permanent, and every peer bears it. Memory
accounting exists so that whoever creates that burden accounts for it.

Normative spec: `https://docs.convex.world/docs/cad/memory`.

## Storage Size

```
storage size = 64 + (bytes of the cell's own encoding) + (memory size of child cells)
```

Two consequences worth internalising:

- **The 64-byte constant is per non-embedded cell.** Cell *count* costs, not
  just bytes. A structure split across many small cells is far more expensive
  than the same data embedded.
- **Embedded cells have a memory size of zero.** Their bytes are already inside
  the parent's encoding. Embedding is genuinely free storage — see the
  `cad3-encoding` skill for the 140-byte embedding limit.

## Consumption

Measured per transaction, at the end:

```
Memory Consumption = state size at end − state size at start
```

When consumption is positive, resolved in this order:

1. Deduct from the user's **memory allowance**, if sufficient.
2. Otherwise **buy from the memory pool**, paying at most
   `remaining juice × juice price`. This is where memory and juice meet — a
   transaction can fail for memory because it spent its juice elsewhere.
3. Otherwise fail with **`:MEMORY`**, roll back all state changes, and still
   charge the juice.

When consumption is **negative, the allowance is refunded** by the amount
released. Freeing storage pays.

## Minimise Allocation

Treat on-chain storage as the scarcest thing you are spending. In order of
leverage:

- **Embed rather than branch.** Small values inside a parent encoding cost
  nothing extra; each separate cell costs 64 bytes of overhead before its
  content.
- **Keep cell counts low.** Prefer one compact structure over many small ones.
- **Store the minimum that satisfies the requirement.** Derive what can be
  derived, and keep off-chain what does not need consensus. Storing a hash or a
  reference is usually enough when the payload itself need not be on-chain.
- **Do not store what a query can compute.** On-chain caching of derived values
  trades permanent storage for transient compute — usually the wrong way round.
- **Actors should allocate sparingly when called by users.** The *caller* pays
  for what your actor allocates, so a wasteful actor makes every interaction
  with it expensive. This is a competitive property, not just good manners.

Note that de-duplication does not help the allocating user: identical
encodings are stored once network-wide, but you still pay allowance for what
you allocate. Do not design around it.

## Reclaim Aggressively

Every byte released is allowance refunded, so cleaning up is directly
rewarded — for users and actors alike.

- **Delete data you no longer need.** Definitions in your own account
  environment are yours to remove, and safe to remove if you hold backups —
  the data can always be restored later.
- **Give actors clean-up functions.** A well-designed actor lets participants
  remove what is finished with: read messages, filled orders, zero-balance
  holder records, expired offers, de-registrations. Without such a function the
  storage is stranded permanently.
- **Expect callers to use them.** The party who cleans up claims the refund, so
  clean-up paths get used. That is the intended incentive — a responder can
  come out ahead by tidying up after an interaction.
- **Give actors a way to reclaim their own allowance.** Actors hold allowances
  but normally do not spend them: the transaction *origin* pays. The exception
  is **scheduled execution**, where the actor is itself the origin. An
  allowance that accumulates in an actor with no reclaim path is unreachable
  forever, and cannot be retrofitted without an upgrade.

Allowances may also be transferred directly between accounts, which is how
actors and multi-account users manage them without allocate/deallocate tricks.

## The Memory Pool

An automated market maker. Seeded at genesis with 1,000,000 bytes against
1,000 Convex Coins (~1 Coin/KB), and grown at a fixed rate (currently 1 MB per
day).

Growth is deliberate: it avoids a hard supply ceiling and penalises hoarding,
since new supply dilutes accumulated allowances.

## Implementation Notes

Memory size is computed lazily and **cached per cell**; peers MUST cache it to
meet performance requirements. Cells are immutable, so a cached size is never
invalidated — that is what keeps accounting O(1) per allocated cell.

The accounting subsystem is designed to cause **no net cell allocations
itself**, so it cannot drive the state growth it exists to control. Preserve
that if you change it: update embedded fields on existing cells rather than
allocating new ones.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall