Skip to main content

🌐 Entities

Entities are the building blocks of your world's knowledge graph — characters, places, events, objects, and context nodes that Sage AI can reason about and connect together.

👑 For Owners🛡️ For Moderators📖 For Readers👤 Characters📍 Places⏳ Events

On this page

  1. What are Entities?
  2. The five entity types
  3. Bookshelf vs World entities
  4. For Owners — setting up worlds and entities
  5. For Owners — AI entity extraction
  6. For Owners — entity groups
  7. For Moderators — managing entities
  8. For Readers — browsing the entity catalog
  9. For Readers — searching entities
  10. For Readers — understanding entity groups
  11. FAQ
🌐

What are Entities?

Entities are the named people, places, events, objects, and contextual concepts that make up your world. Think of them as the nodes in a knowledge graph — each entity can be linked to others, grouped with related entities, and queried by Sage AI.

Entities live on your room's bookshelf alongside books, documents, and other works. They are the bridge between raw content and structured knowledge — when Sage answers a question like “Who was at the warehouse on June 14th?”, it uses entities and their relationships to find the answer.

🔍 AI-Extracted

Sage can scan documents and automatically extract entities — characters, themes, locations, and plot points — from uploaded files and web content.

✍️ Manually Created

You can create entities by hand — add a character, place, or event directly to the bookshelf with a title, description, image, and confidence rating.

ℹ️Entities are stored as special works on the bookshelf. This means they can be discussed, bookmarked, annotated, and added to the Notaepedia — just like any other work in your room.
🏷️

The five entity types

Every entity has a type that tells the system what kind of thing it represents. The type determines the icon, colour, and how the entity appears across the platform.

👤

Characters (text/character)

People, personas, aliases, suspects, or any named individual. In investigative rooms these may be labelled “Suspects” or “Persons of Interest.”

📍

Places (text/place)

Locations — cities, buildings, rooms, crime scenes, or any geographically meaningful point. Can be plotted on the Entity Map.

⏳

Events (text/timeline)

Timeline entries — meetings, incidents, discoveries, or any temporally anchored occurrence. Supports date ranges and uncertainty.

📦

Objects (text/object)

Physical items — evidence, documents, weapons, vehicles, or any tangible thing relevant to your world.

📋

Context (text/context)

Conceptual nodes — themes, organisations, abstract ideas, or background information that does not fit the other categories.

💡Use Contextentities for things like “Forensic Evidence Protocols” or “The Cold War Era” — broad concepts that help Sage understand the background of your world without being a specific person, place, or event.
🔄

Bookshelf vs World entities

NotaeLibrary has two parallel entity systems that work together:

📚 Bookshelf Entities

Stored as StudyRoomWork rows on the bookshelf. These are the entities you see at /bookshelf/entities. They are simpler — title, description, type, and confidence. They can be discussed and bookmarked like any work.

🌍 World Entities

Stored as StudyRoomWorldEntityRecord rows in a World. These are richer — they support aliases, temporal data, merge tracking, linked relations, and media galleries. Used for the canonical world knowledge graph.

Bookshelf entities are the entry point — they are what members browse, search, and discuss. World entities are the deeper, canonical version used by AI and the Notaepedia. The WorldNavBar bridges both systems, letting you navigate between the entity catalog, the world graph, timelines, and the Notaepedia.

ℹ️For most rooms, you only need to think about bookshelf entities. World entities are automatically created when you promote entities to the Notaepedia or build a formal world knowledge graph.
👑

For Owners — setting up worlds and entities

1

Create or link a World

Entities need a World to live in. Go to your room's World tab. If no world exists yet, create one — give it a name and description. The world is the container for your entity knowledge graph.
2

Enable Notaepedia (optional but recommended)

In Settings → Notaepedia, toggle Enable Notaepedia ON. This activates the full entity pipeline — AI extraction, entity groups, and Notaepedia article generation. Without it, entities still work but AI features are limited.
3

Add works to the bookshelf

Entities are extracted from works. Upload documents, add books, or link web articles to your room's bookshelf. The more content you have, the richer your entity graph becomes.
4

Run entity extraction

Once you have content on the bookshelf, you can run AI extraction. Sage scans your works and identifies characters, places, events, objects, and themes — then adds them as entity works on the bookshelf.
💡Pro tip: Start with 3–5 key documents and run extraction. Review the results, merge duplicates, and create groups. Then add more documents incrementally. This keeps the entity catalog clean and manageable.
🤖

For Owners — AI entity extraction

Sage AI can automatically scan works on your bookshelf and extract entities. This is the fastest way to build your entity catalog.

1

Open the extraction tool

From the bookshelf, click the Extract Entities button (visible to owners and moderators). You can extract from a single work or batch-extract from multiple works at once.
2

Review extracted entities

Sage returns a list of detected entities — each with a suggested type, title, description, and confidence score. Review each one. You can accept, reject, or edit before they are added to the bookshelf.
3

Confirm and add

Accepted entities are added to the bookshelf as StudyRoomWork records with the appropriate entity file type. They appear immediately in the Entities tab.
4

Review AI-suggested groups

After extraction, Sage may propose entity groups — automatically detected clusters of related entities (e.g. all characters from the same family, or all evidence items from the same crime scene). Review and confirm these in the Entities page.
⚠️AI extraction is not perfect. Always review extracted entities before accepting them. Merge duplicates, correct misidentified types, and remove false positives to keep your entity catalog accurate.
🔗

For Owners — entity groups

Entity groups let you cluster related entities together — for example, grouping all members of a family, all evidence from a crime scene, or all locations in a city.

1

Create a group

On the Entities page, click Create Group(visible to owners and moderators). Give the group a name and description — e.g. “The Fronczak Family” or “Hospital Staff.”
2

Add members to the group

Select entities from the catalog to add to the group. You can also set a canonical entity — the primary identity that represents the group as a whole.
3

Manage group status

Groups have a status: Confirmed (verified by a human), Proposed (suggested by AI, awaiting review), Rejected (dismissed), or Split (broken into smaller groups).
4

Use groups in Notaepedia

Confirmed entity groups feed into the Notaepedia — Sage uses them to generate richer, more connected encyclopedia articles that understand relationships between entities.
🛡️

For Moderators — managing entities

Moderators have full access to entity management — you can create, edit, merge, and organise entities to keep the knowledge graph accurate.

✏️ Edit entity details

Click any entity to open its detail page. Edit the title, description, cover image, confidence rating, and type. All changes are tracked in the audit log.

🔀 Merge duplicate entities

AI extraction can produce duplicates — e.g. “Paul Fronczak” and “Paul J. Fronczak” might be the same person. Use the Merge tool to combine them into one canonical entity, preserving all relationships from both.

🤖 Review AI suggestions

The Entities page shows AI-suggested groups at the top (visible to mods only). Each suggestion includes a confidence score and rationale. Review, confirm, or reject them to keep the entity catalog curated.

🔍 Scan for connections

Click Scan Connectionsto have Sage analyse your entities and suggest relationships — e.g. “was present at,” “married to,” “worked for.” These become entity links in the knowledge graph.

🗑️ Remove entities

Delete entities that are incorrect, obsolete, or duplicates that have been merged. Removed entities are soft-deleted and can be restored if needed.

📖

For Readers — browsing the entity catalog

The Entities page is your directory of every named person, place, event, object, and concept in the room's world. Here is what you will see:

🧭 World navigation bar

At the top, the WorldNavBar lets you jump between World Overview, Relations graph, Timeline, Entities catalog, and Notaepedia — all the ways to explore the world's knowledge.

🏷️ Type filter pills

Filter by entity type — click All to see everything, or narrow to just Characters, Places, Events, Objects, or Context. The active filter is highlighted in indigo.

🃏 Entity cards

Each entity appears as a card with its icon, title, type badge (colour-coded), description preview, and confidence rating. Click any card to open the full entity detail page.

🔗 Entity groups

Groups of related entities appear as expandable cards at the top of the page — e.g. “The Fronczak Family (4 members).” Expand a group to see all its members and their relationships.

👥

For Readers — understanding entity groups

Entity groups help you understand how entities relate to each other. Rather than browsing a flat list, groups show you the natural clusters in the world.

📂 What groups look like

Each group is an expandable card showing the group name, a description, and the number of members. Expand it to see individual entity cards for each member, with their type badges and descriptions.

⭐ Canonical entities

A group may have a canonical entity— the “primary” member that represents the group as a whole. For example, in a group of aliases for the same person, the canonical entity is their main identity.

📋 Ungrouped entities

Entities that do not belong to any group appear below the groups in a grid. These are “standalone” entities — they may eventually be grouped as the world grows.

❓

FAQ

▶What is the difference between an entity and a regular work?

A regular work is a book, document, article, or media file. An entity is a named concept extracted from or related to those works — a character, place, event, object, or context node. Entities are typed and can be linked together in a knowledge graph. Both live on the bookshelf.

▶How do I get entities into my room?

Three ways: (1) AI extraction — Sage scans works and auto-detects entities. (2) Manual creation — add an entity directly to the bookshelf. (3) Batch extraction — run extraction across multiple works at once.

▶What does the confidence rating mean?

Confidence is a 1–5 scale: 1 = Very Low (AI guessed, unverified), 3 = Moderate (likely correct), 5 = Definitive (verified by a human moderator). Higher confidence entities are prioritised in AI responses and Notaepedia articles.

▶Can entities be linked to each other?

Yes. Entities support typed relationships — e.g. 'married to,' 'was present at,' 'worked for.' These links form the knowledge graph that Sage uses for reasoning. Moderators can scan for connections and manually create links.

▶Do I need to create a World to use entities?

Entities on the bookshelf work without a formal World. However, creating a World enables richer features — the WorldNavBar, entity maps, timelines, Notaepedia articles, and the full knowledge graph. It is recommended but not required.

▶Are my entities visible to non-members?

It depends on your room's visibility. Public rooms show entities to anyone. Private rooms only show entities to members. Check your room's visibility settings.

▶Can I export or import entities?

Currently, entities live within the platform. Cross-room entity importing via the World system is supported — you can link a World across multiple rooms. Full export is on the roadmap.

Ready to explore entities?

Visit the entity catalog in the example room below, or head to your own Study Room to start building your world's knowledge graph.

🌐 View Example Entities →📚 Study Rooms Tutorial📖 Notaepedia Tutorial