Storage

Persistent key-value store scoped per-macro, survives app restarts

The storage object lets a macro silently save and load data to disk without any UI. Data persists across runs and app restarts. Each macro has its own isolated store — two macros using the same key will not interfere with each other.

Values must be JSON-serializable (strings, numbers, booleans, arrays, plain objects). A circular reference throws on set. A function value silently fails (returns false, writes nothing) rather than throwing.

storage.set(key, value)

Persists a value to disk under the given key. The value is serialized with JSON.stringify internally.

Parameter	Type	Description
`key`	string	Storage key, unique within this macro.
`value`	any	Any JSON-serializable value.

Returns boolean — true if saved, false if the write was refused (quota exceeded or no macro running). A refused write never destroys the key's previous value.

storage.set("counter", 0);
storage.set("config", { speed: "fast", retries: 3 });
storage.set("history", [1, 2, 3]);

// Check quota
var ok = storage.set("bigData", someHugeObject);
if (!ok) print("Storage full!");

storage.get(key, defaultValue?)

Reads a persisted value. The stored JSON string is deserialized with JSON.parse automatically.

Parameter	Type	Description
`key`	string	Storage key to look up.
`defaultValue`	any	Returned if the key doesn't exist. Defaults to `undefined`.

Returns T — the stored value, or defaultValue if the key doesn't exist

var count = storage.get("counter", 0);
count++;
storage.set("counter", count);
print("Run #" + count);

var config = storage.get("config", { speed: "normal", retries: 1 });
print(config.speed);

storage.delete(key)

Removes a single key from the macro's storage.

Parameter	Type	Description
`key`	string	Storage key to remove.

Returns void

storage.delete("counter"); // next get("counter") returns defaultValue

storage.clear()

Removes all keys from the macro's storage. Does not affect prompt caches or global variables.

Returns void

// Reset all stored data for this macro
storage.clear();

Quotas

To prevent runaway scripts from filling up device storage, limits are enforced per macro:

Limit	Value	Description
`Per key`	64 K chars	Maximum length of a single serialized value. Counted in characters of JSON, not bytes, so non-ASCII content fits less than a byte budget would suggest.
`Per macro`	512 K chars	Total length of all serialized values combined, counted the same way.

When a set call would exceed either limit, it returns false and the value is not written. Existing data is not affected.

Storage vs Variables: setGlobalVar / getGlobalVar are in-memory and last only for the run — every run resets the table to the macro's declared variables, so nothing carries over even without an app restart. storage writes to disk and survives both. Use variables for cross-thread communication during a run, and storage for data that must persist.