---
id: LSN-0015
ticket: legacy-runtime-learn-import
title: Save Memory and MEMCARD
created: 2026-03-27
tags: [migration, tech-debt]
---

# Save Memory and MEMCARD

Status: pedagogical
Companion spec: [`../specs/08-save-memory-and-memcard.md`](../../specs/08-save-memory-and-memcard.md)
Historical snapshot: [`historical-game-memcard-slots-surface-and-semantics.md`](LSN-0005-historical-game-memcard-slots-surface-and-semantics.md)

PROMETEU treats persistence as explicit hardware, not as invisible save behavior.

## Mental Model

MEMCARD is not save state. It is a persistence device controlled by the game.

That implies:

- known size;
- observable cost;
- the need for `commit()`;
- the possibility of failure;
- a data format under the game's control.

## Slot Thinking

The right model is not "the game saves files". The right model is "the game talks to slots".

That changes how you think about persistence:

- capacity is finite and known;
- each slot has identity and state;
- ownership belongs to the cart's `app_id`;
- the game does not get broad access to the host filesystem.

That choice exists to preserve:

- portability;
- isolation between apps;
- predictable save UX;
- a contract that runs on desktop and dedicated hardware.

## Staged Versus Committed

An important MEMCARD intuition is the difference between:

- changing content in staging;
- making the write actually persistent.

`commit()` existe para separar essas duas fases.

That teaches a more honest model of persistence:

- writing is not yet persisting;
- persisting has a cost;
- persisting can fail;
- atomicity matters.

## Why Explicit Commit Matters

`commit()` exists to make persistence a visible technical decision.

Without it, there is no illusion that "saving simply happened". The game must decide when it wants to:

- materialize a write;
- accept the cost;
- deal with the risk of loss or corruption.

## Runtime-Owned Metadata

Even when the payload belongs to the game, some aspects of the slot belong to the machine:

- integrity;
- generation/versioning;
- slot state;
- ownership isolation.

That prevents each game from reinventing its own basic persistence semantics and lets tooling and Hub/OS present save data coherently.

## Hub/OS Role

PROMETEU separates clearly:

- the game writes and reads its own slots;
- the Hub/OS handles export, import, copy, and save presentation.

That separation prevents userland from becoming a mini file manager and keeps system operations in the right layer.

## Tooling Surface

External tools may expose utilities such as:

- create or reset MEMCARD;
- import and export `.mem`;
- inspect size and usage;
- associate cards with projects.

Those surfaces are auxiliary. They do not change the machine contract.

## Why This Is Better Than Broad FS For Games

For the `game` profile, the slot model is better than exposing a broad filesystem because:

- it reduces ambiguity around path, permission, and ownership;
- it makes controlled import/export easier;
- it improves compatibility across hosts;
- it makes it clearer what a "valid save" means to the machine.

## Why This Fits PROMETEU

This model fits well with the project's console heritage and DIY focus: persistence is part of the machine design, not convenience hidden inside the host.