SuperMemo XML Format Specification

Documented from the current implementation in XMLExport.pas and XMLImport.pas.

Scope

This document describes the XML format currently written and read by SuperMemo's XML export and synchronization code. It is a descriptive specification of the implemented format, not a strict XSD contract.

The exporter writes a tree of SuperMemoElement nodes inside SuperMemoCollection. The importer reads every SuperMemoElement in document order and uses the XML tree to infer parents.

Top-Level Document

ElementRequiredDescription
SuperMemoCollectionYesRoot element produced by export.
CountExportedTotal number of SuperMemoElement nodes in the document. Import does not rely on this value.
SuperMemoElementYesOne knowledge-tree element. Elements may be nested to represent the contents tree.
<SuperMemoCollection>
  <Count>2</Count>
  <SuperMemoElement>
    ...
    <SuperMemoElement>...</SuperMemoElement>
  </SuperMemoElement>
</SuperMemoCollection>

Element Structure

ChildCardinalityWritten by exportRead by import
ID0..1YesYes. Missing or zero ID means the element is added as new.
Title0..1Yes for branch nodes and elements without a question.Yes. Defaults to Content/Question when absent.
Type1YesYes. Values: Item, Topic, Concept, Task. Unknown values import as Topic after an error.
Ordinal0..1Only if the export option is enabled.Only if the import ordinals option is enabled. Values must parse as a real number.
Content0..1Yes for elements with component data.Yes. Holds text, images, and sounds.
LearningData0..1Unless removed by export option.Yes during synchronization or when adding a new element.
SuperMemoElement0..nYes for child elements.Yes. Parent is taken from the XML parent node's ID.

Tree and Parent Handling

Export reconstructs the element path and nests elements accordingly. If a parent already exists in the output tree, it is reused instead of duplicated. During import, a node's parent is the enclosing SuperMemoElement. If no parent ID is available, new elements are added under the current import concept.

Content

ChildCardinalityDescription
Question0..1Main question text produced from the element's text components. May contain HTML unless the "Remove HTML codes" export option is used. References may be appended to this field unless removed.
Answer0..1Main answer text. A second meaning of Answer exists under media nodes; see below.
Image0..n exported; first two importedImage component metadata and URL.
Sound0..n exported; first two importedSound component metadata, transcription text, and URL.
Other component-type nodes0..n exported in some option combinationsThe exporter can emit nodes named by component type, such as Video, OLE, Script, or Binary, but the XML importer only consumes Image and Sound media nodes.

Text Rules

Media Nodes

The implemented importer recognizes Content/Image and Content/Sound. Only the first two images and first two sounds are imported.

NodeChildDescription
ImageURLPath or URL to the image file. [SecondaryStorage] is expanded during import.
ImageNameRegistry name of the image.
ImageAnswerOptional flag. T means the image belongs to the answer side.
SoundTextSound transcription text from the text registry.
SoundURLPath or URL to the sound file. [SecondaryStorage] is expanded during import.
SoundNameRegistry name of the sound.
SoundAnswerOptional flag. T means the sound belongs to the answer side.

Secondary Storage

When "Create storage" is enabled on export, media files are copied into a sibling folder named after the XML file:

Export file:       Collection.xml
Storage folder:    Collection_files\Elements
XML media URL:     [SecondaryStorage]\relative\file.ext
Import expansion:  Collection_files\elements\relative\file.ext

Import replaces the literal token [SecondaryStorage] with the derived storage path. Synchronization can also modify the collection's secondary storage when the import option permits it.

LearningData

ChildRequired for importFormatDescription
IntervalNoInteger daysCurrent interval. Defaults to 0 if absent.
RepetitionsYes after LastRepetitionIntegerNumber of repetitions.
LapsesNoIntegerNumber of memory lapses. Defaults to 0 if absent.
LastRepetitionYesdd.mm.yyyy or -Last repetition date. - means no repetition.
AFactorYesReal numberA-Factor. Invalid values fall back to 1.3.
UFactorNoReal numberU-Factor. Missing or zero values are inferred.
RepHistNoHTML-encoded text with <br> line breaksRepetition history. Import decodes HTML, converts <br> back to line breaks, and saves decoded repetition history when possible.

Learning data is conservative during synchronization. Updates are skipped for low text similarity unless forced, for elements repeated today, for future dates after clamping, and for suspicious repetition discrepancies. When adding a new element, learning data is imported with maximum text similarity.

Import and Synchronization Behavior

Export Options

OptionEffect
Remove HTML codesExports question/answer text from components without HTML.
Remove referencesDoes not append reference HTML to question text.
Remove learning dataOmits LearningData.
Apply text filterRuns the selected replacement filter before export.
Export imagesAllows image components to be exported.
Export soundAllows sound components to be exported. In the current code this option also affects export of non-text, non-image component types.
Create storageCopies exported media files to the XML sibling storage folder and writes [SecondaryStorage] URLs.
Export ordinalsWrites Ordinal nodes.

Import Options

OptionEffect
Update textsEnables text synchronization. If disabled, text update mode is tuNone.
Ignore topicsSkips topic leaves and final topic updates.
Ignore referencesPrevents transferred references from being saved.
Import imagesAllows image media updates.
Import soundsAllows sound media updates.
Import ordinalsAllows positive Ordinal values to update element ordinals.
Modify secondary storagePermits the collection secondary storage path to be changed for XML media import.

Example

<SuperMemoCollection>
  <Count>2</Count>
  <SuperMemoElement>
    <ID>1</ID>
    <Title>Biology</Title>
    <Type>Topic</Type>
    <SuperMemoElement>
      <ID>25</ID>
      <Type>Item</Type>
      <Ordinal>12.5</Ordinal>
      <Content>
        <Question>What carries genetic information?</Question>
        <Answer>DNA</Answer>
        <Image>
          <URL>[SecondaryStorage]\biology\dna.png</URL>
          <Name>dna.png</Name>
        </Image>
        <Sound>
          <Text>DNA</Text>
          <URL>[SecondaryStorage]\biology\dna.mp3</URL>
          <Name>dna.mp3</Name>
          <Answer>T</Answer>
        </Sound>
      </Content>
      <LearningData>
        <Interval>30</Interval>
        <Repetitions>4</Repetitions>
        <Lapses>0</Lapses>
        <LastRepetition>24.05.2026</LastRepetition>
        <AFactor>1.300</AFactor>
        <UFactor>1.100</UFactor>
        <RepHist>...</RepHist>
      </LearningData>
    </SuperMemoElement>
  </SuperMemoElement>
</SuperMemoCollection>

Compatibility Notes

Source: XMLExport.pas, XMLImport.pas, Component.pas, and DBDat.pas.