# Memory Management Guide

> Use when deciding how memory is allocated, owned, and freed in manual-memory or buffer-passing code, in any language. Triggers on prompts about caller-owns-memory / caller-provided buffers, arena/bump/linear allocators, object pools and free lists, virtual-memory reserve/commit, scratch/temp allocators, object lifetimes, ownership (single-owner/borrow), leaks/use-after-free/double-free, even when the user doesn't say 'memory' or 'allocator'.

- Skill: `xonovex/memory-management-guide` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add xonovex/memory-management-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xonovex/memory-management-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: xonovex (https://skillmd.com/u/xonovex)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xonovex/memory-management-guide

---


# Memory Management Guidelines

General principles for allocating, owning, and freeing memory in manual-memory or buffer-passing code. Language-agnostic; examples are in C. Domain skills (e.g. C99, GPU device memory) keep their own specifics and link here for the underlying principle.

## Essentials

- **Caller owns memory** - APIs take caller-provided storage; never allocate internally, see [references/caller-owns-memory.md](references/caller-owns-memory.md)
- **Group by lifetime** - Allocate together what dies together; free as a unit, see [references/ownership-and-lifetimes.md](references/ownership-and-lifetimes.md)
- **One owner** - Exactly one owner frees; everyone else borrows, see [references/ownership-and-lifetimes.md](references/ownership-and-lifetimes.md)

## Allocation strategy

- **Arena / bump** - Pointer-bump from a block; reset frees everything at once, see [references/arenas-and-pools.md](references/arenas-and-pools.md)
- **Object pool** - Fixed-size slots + free list; O(1) alloc/free, stable, see [references/arenas-and-pools.md](references/arenas-and-pools.md)
- **Scratch / temp** - Per-frame/per-request arena reset each cycle, see [references/arenas-and-pools.md](references/arenas-and-pools.md)
- **Virtual-memory reserve/commit** - Reserve a large range, commit pages on demand; stable addresses, no realloc copy, see [references/arenas-and-pools.md](references/arenas-and-pools.md)
- **Virtual-memory tricks** - Cap-free arrays, page-aligned growth, gapless ring buffers, end-of-page bounds checks, see [references/virtual-memory.md](references/virtual-memory.md)

## Ownership

- **Lifetime by scope** - Tie allocation lifetime to a clear scope/phase, see [references/ownership-and-lifetimes.md](references/ownership-and-lifetimes.md)
- **Handles over pointers** - Reference relocatable storage by index/handle (layout detail in data-oriented-design-guide), see [references/ownership-and-lifetimes.md](references/ownership-and-lifetimes.md)

## Gotchas

- Bump allocation has no bounds safety unless you check capacity; always assert/return on overflow.
- Two owners means double-free or leak; decide ownership explicitly, don't infer it.
- Pointers into a growing/reset allocation dangle. Prefer offsets/handles across a boundary (a virtual-memory reserve/commit block is the exception: it never moves).

## Progressive Disclosure

- Read [references/caller-owns-memory.md](references/caller-owns-memory.md) - Load when designing an API's allocation boundary or a non-allocating library
- Read [references/arenas-and-pools.md](references/arenas-and-pools.md) - Load when choosing an allocator: arena, pool, scratch, or virtual-memory backed
- Read [references/virtual-memory.md](references/virtual-memory.md) - Load when using address-space reservation for cap-free arrays, ring buffers, page-aligned growth, or end-of-page bounds checking
- Read [references/ownership-and-lifetimes.md](references/ownership-and-lifetimes.md) - Load when deciding who owns/frees memory and how long it lives