Storage

Plugin storage is backed by the same element interaction system that built-in elements like multichoice, wordbank, and mathresponse use. Understanding how that system works — specifically how element hashes are computed — is essential to predicting when stored state persists and when it resets.

Declare "storage" in your manifest's permissions field before using any storage method:

"permissions": ["storage"]

Element Hashes

Every plugin element is assigned a stable content hash derived from its attributes and body content. Storage is keyed by the composite (user_id, internote_id, element_hash), so state is automatically per-student, per-internote, per-element — you never need to include the hash in your storage keys manually.

The hash is available as InitContext.elementHash if you need to reference it directly:

internote.onInitialize(({ elementHash }) => {
  console.log('Element hash:', elementHash)
})

Changing any attribute or body content in Chalk changes the hash and makes previously stored state inaccessible. This mirrors the behaviour of native interactive elements — editing a multichoice question resets student answers for the same reason. Inform educators of this in your plugin description.

storage.get

Retrieves a value previously saved with storage.set. Returns null if nothing has been stored at that key for this user and element.

• key (string; required). The key to retrieve.
• Returns Promise<unknown | null>

const saved = await internote.storage.get('simulationState')
const state = saved ?? buildDefaultState()

storage.set

Saves a value under a key. Overwrites any existing value at that key. The value must be JSON-serialisable.

• key (string; required). The key to write.
• value (unknown; required). The value to store. Objects, arrays, strings, numbers, and booleans are all valid. Functions, undefined, and circular references are not.
• Returns Promise<void>

await internote.storage.set('state', { step: 3, answers: [1, 2] })

storage.delete

Removes a saved key. Has no effect if the key does not exist.

• key (string; required). The key to remove.
• Returns Promise<void>

await internote.storage.delete('temporaryDraft')

storage.clear

Removes all keys saved by this plugin for the current user at this element hash.

• Returns Promise<void>

Limits

• 10 MB total per user per plugin across all keys in all internotes
• storage.set rejects if writing would exceed this limit — always catch the error
• Keys are strings of up to 256 characters

Patterns

Restore on Initialize

internote.onInitialize(async ({ attrs }) => {
  const saved = await internote.storage.get('state')
  const state = saved ?? buildDefaultState(attrs)
  render(state)
  internote.ready()
})

Periodic Saves

onUnload is not guaranteed to fire in all termination scenarios. Save state on a debounced interval rather than relying solely on unload:

let saveTimer = null

function scheduleSave(state) {
  clearTimeout(saveTimer)
  saveTimer = setTimeout(async () => {
    try {
      await internote.storage.set('state', state)
    } catch (err) {
      console.error('Failed to save:', err)
    }
  }, 1000)
}

Handling Storage Errors

try {
  await internote.storage.set('state', largeObject)
} catch (err) {
  // Quota exceeded or network error — degrade gracefully
  console.warn('Could not persist state:', err.message)
}