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
| Element | Required | Description |
|---|---|---|
SuperMemoCollection | Yes | Root element produced by export. |
Count | Exported | Total number of SuperMemoElement nodes in the document. Import does not rely on this value. |
SuperMemoElement | Yes | One knowledge-tree element. Elements may be nested to represent the contents tree. |
<SuperMemoCollection>
<Count>2</Count>
<SuperMemoElement>
...
<SuperMemoElement>...</SuperMemoElement>
</SuperMemoElement>
</SuperMemoCollection>
Element Structure
| Child | Cardinality | Written by export | Read by import |
|---|---|---|---|
ID | 0..1 | Yes | Yes. Missing or zero ID means the element is added as new. |
Title | 0..1 | Yes for branch nodes and elements without a question. | Yes. Defaults to Content/Question when absent. |
Type | 1 | Yes | Yes. Values: Item, Topic, Concept, Task. Unknown values import as Topic after an error. |
Ordinal | 0..1 | Only if the export option is enabled. | Only if the import ordinals option is enabled. Values must parse as a real number. |
Content | 0..1 | Yes for elements with component data. | Yes. Holds text, images, and sounds. |
LearningData | 0..1 | Unless removed by export option. | Yes during synchronization or when adding a new element. |
SuperMemoElement | 0..n | Yes 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
| Child | Cardinality | Description |
|---|---|---|
Question | 0..1 | Main 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. |
Answer | 0..1 | Main answer text. A second meaning of Answer exists under media nodes; see below. |
Image | 0..n exported; first two imported | Image component metadata and URL. |
Sound | 0..n exported; first two imported | Sound component metadata, transcription text, and URL. |
| Other component-type nodes | 0..n exported in some option combinations | The 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
- XML text is stored as node text, so XML-significant characters are escaped by MSXML on save.
- Exporter strips control characters
#8,#3, and#26. - When title-only branch nodes are exported, line breaks are converted to
<br>and the title is HTML-prepared. - On import, question, answer, and title pass through
CleanImportString. Titles are additionally filtered throughFilterHTMLand shortened withShortTitle. - References are encoded inside question text by the reference helper. Import separates them with
CutReferenceExtand stores them only if reference import is enabled.
Media Nodes
The implemented importer recognizes Content/Image and Content/Sound. Only the first two images and first two sounds are imported.
| Node | Child | Description |
|---|---|---|
Image | URL | Path or URL to the image file. [SecondaryStorage] is expanded during import. |
Image | Name | Registry name of the image. |
Image | Answer | Optional flag. T means the image belongs to the answer side. |
Sound | Text | Sound transcription text from the text registry. |
Sound | URL | Path or URL to the sound file. [SecondaryStorage] is expanded during import. |
Sound | Name | Registry name of the sound. |
Sound | Answer | Optional 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
| Child | Required for import | Format | Description |
|---|---|---|---|
Interval | No | Integer days | Current interval. Defaults to 0 if absent. |
Repetitions | Yes after LastRepetition | Integer | Number of repetitions. |
Lapses | No | Integer | Number of memory lapses. Defaults to 0 if absent. |
LastRepetition | Yes | dd.mm.yyyy or - | Last repetition date. - means no repetition. |
AFactor | Yes | Real number | A-Factor. Invalid values fall back to 1.3. |
UFactor | No | Real number | U-Factor. Missing or zero values are inferred. |
RepHist | No | HTML-encoded text with <br> line breaks | Repetition 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
- A plain import adds XML elements as new SuperMemo elements.
- Synchronization uses
IDto match existing elements. If an XML ID is larger than the current item-info size, the database is filled up to that ID. Deleted elements can be undeleted. - If an XML element has no valid ID, it is added as a new element even during synchronization.
- When adding elements, old XML IDs are stored in an internal renumbering table so child nodes can be attached to their newly created parents.
- If "Ignore topics" is enabled, topic leaves are skipped. Topic nodes that have children may still be traversed so their descendants can be processed.
- Text synchronization can update recent texts, update all, append prior text, ask per element, skip, suggest only, or force updates.
- When text is appended, prior question/answer text is placed after a
###Text beforetimestamp marker. - Media and references are updated only if their corresponding import options are enabled and the text reconciliation step allows the update.
Export Options
| Option | Effect |
|---|---|
| Remove HTML codes | Exports question/answer text from components without HTML. |
| Remove references | Does not append reference HTML to question text. |
| Remove learning data | Omits LearningData. |
| Apply text filter | Runs the selected replacement filter before export. |
| Export images | Allows image components to be exported. |
| Export sound | Allows sound components to be exported. In the current code this option also affects export of non-text, non-image component types. |
| Create storage | Copies exported media files to the XML sibling storage folder and writes [SecondaryStorage] URLs. |
| Export ordinals | Writes Ordinal nodes. |
Import Options
| Option | Effect |
|---|---|
| Update texts | Enables text synchronization. If disabled, text update mode is tuNone. |
| Ignore topics | Skips topic leaves and final topic updates. |
| Ignore references | Prevents transferred references from being saved. |
| Import images | Allows image media updates. |
| Import sounds | Allows sound media updates. |
| Import ordinals | Allows positive Ordinal values to update element ordinals. |
| Modify secondary storage | Permits 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
- The importer requires at least one
SuperMemoElement. It reports an error if none are found. Typeis expected and is not nil-checked before readingNode.Text.- The XML importer is intentionally narrower than the exporter for media: images and sounds are supported, while other component nodes are not imported by this XML path.
- The public export enum
TXMLExportTypeis currently passed through the export path but not used by the implementation. - XML validity depends on MSXML serialization plus the limited control-character filter in
FilterXMLText.
Source: XMLExport.pas, XMLImport.pas, Component.pas, and DBDat.pas.