Elements: topics, extracts, items

A Topic, an Extract, and an Item are all Elements — the same kind of object playing different roles. This page explains the model and why it is unified.

One object, three roles

Kioku treats every piece of knowledge as an Element, and the role it plays is what tells the kinds apart. A Topic, an Extract, and an Item are therefore not three separate things — they are three roles the same kind of object can play.

• A Topic is imported reading material: an article, web page, or PDF you read incrementally.
• An Extract is a passage you pull out of a Topic (or another Extract) because it’s worth remembering.
• An Item is a flashcard — the smallest unit of recall, scheduled by FSRS.

There is also a Concept: a lightweight label you can use in Browse to group related material together. A Concept holds no content of its own and never enters a review queue.

Treating these roles as one kind of object is what lets Kioku handle reading and recall as a single, continuous workflow rather than two disconnected apps. Every Element carries the same shape — a title, content, and a priority — so the same queue, the same tree, and the same provenance trail apply everywhere.

Reading and recall are scheduled differently, though. Items are driven by FSRS, while Topics and Extracts follow Kioku’s reading schedule. For a Topic or Extract, “no scheduled date yet” means “ready now,” not “never” — see Spaced repetition for how the two schedules diverge.

How an Item is shown and hidden is recorded on its Card. A basic Card stores a front and a back; a cloze Card hides a portion of a passage; an image-occlusion Card masks regions of an image. One Item can own several Cards — a passage with both a {{c1::…}} and a {{c2::…}} deletion becomes a single Item with two cloze Cards.

The reading-to-recall pipeline

The three roles form a pipeline, and Kioku models it literally: each Element can point at a parent. The path from reading to recall is a parent-and-child tree.

Topic  →  Extract  →  Item

When you carve an Extract out of a Topic, the new Extract’s parent is that Topic. When you turn an Extract into a flashcard, the new Item’s parent is that Extract. You can also extract from an Extract, nesting reading units as finely as the material demands. Items, by contrast, are always leaves: an Item can’t have children, so the pipeline always terminates at recall.

This tree is more than bookkeeping. Deleting a parent cascades to its descendants, so removing a Topic removes the Extracts and Items grown from it. Priority flows down the tree too, so a Topic stays ahead of the fragments it spawned and an Item inherits its parent’s priority by default.

The hands-on side of this pipeline — highlighting, extracting, and writing clozes — is covered in Incremental reading. Here the point is structural: reading material and the flashcards it produces are branches of one tree, not entries in two unrelated lists.

How references connect Elements

The parent link describes structure — which Element an Extract or Item was carved from. A separate mechanism, the reference, describes provenance: where the content originally came from. These are two different connections, and it’s worth keeping them apart.

A reference records a Source title, a Source URL, and a short snippet of the parent’s surrounding text. When you create an Extract or an Item, Kioku copies the parent’s reference down and captures a slice of the parent’s content as context. The result is that a flashcard, several levels deep in the tree, still remembers both the original Source it came from and the passage it sat inside. This is why a Card reviewed weeks later can still link you back to the article that produced it.

Two links, two jobs:

• Parent link — the structural tree edge: which Element this one was carved from.
• Reference — the propagated provenance: which Source and surrounding context this Element inherited.

Keeping provenance separate from structure means you can reorganize or prune the tree without losing the trail back to the original material.

Related

• Collections — how Elements are kept isolated from one another.
• Glossary: Element — the canonical definition.