Data model

Every world is an entity–relationship graph: typed nodes (entities) joined by typed, directed edges (relationships), with long-form prose (lore) and labels (tags) hanging off the nodes. This page describes that shape in technical detail.

Every world starts from the same default schema — the entity types and relationship types listed below — which you can extend as your world grows. So your world always has at least these types, and possibly more if you’ve added some. To read your world’s live schema at any time, have a connected AI tool call get_world_context — see the MCP tool reference for how that works.

The entity record

An entity is one node in the graph. Every entity, whatever its type, carries the same envelope:

Field	What it holds
entity_id	The entity’s slug — its stable, public identifier.
entity_type	Which type it is (person, place, event, …), drawn from the world’s schema.
name	The display name.
description	A short summary line (returned as short_description).
properties	The custom fields for this type, shaped by its property schema.
tags	Labels from the world’s shared vocabulary.
relationships	The typed edges to other entities.
lore	Long-form prose chunks attached to the entity.
created_at / updated_at	Timestamps (ISO 8601).

Entity IDs (slugs)

Every entity is identified by a composite slug in the form {entity_type}/{slugified_name} — for example person/john_smith or place/riverside_cafe. The slug is generated from the type and name when the entity is created, and it’s the identifier used everywhere in MCP calls — as arguments and in responses. You won’t see internal database IDs; slugs are the public handle.

Property schemas

Each entity type defines a property schema — the set of typed fields entities of that type can carry. Fields are typed as string, number, boolean, or array. For example, a person type’s schema might describe:

Property	Type	Description
email	string	Email address
occupation	string	What they do
birthday	string	Date of birth
personality_traits	array	Personality traits

Note

Property schemas are advisory, not strictly enforced. An entity needn’t fill every field, and a stored value that doesn’t match its declared type is tolerated rather than rejected — so the graph survives messy, real-world data. The schema guides agents toward consistent structure; it isn’t a hard validator. If you want enforcement, encode it in your world prompt (see the examples cookbook).

Many string properties act as informal categories — a place’s place_type, an event’s event_type. Their common values are surfaced as enumerations (see tags below): a descriptive list of the values entities currently use, not a closed set you’re locked into.

Relationships

Relationships are the directed, typed edges of the graph — LIVES_AT, MEMBER_OF, LED_TO. Each edge has:

• A source and a target entity (the direction).
• A relationship type (the verb), with a human-readable label and an inverse label for reading the edge the other way (PARENT_OF reads as CHILD_OF from the target’s side).
• Optional properties.
• Optional temporal validity — started and ended dates. Setting ended marks the edge historical (someone who used to belong to a group) without deleting it. Queries return active edges by default and can opt into history.

Relationship types are grouped into categories keyed by the types they connect — for instance person_to_place (LIVES_AT, WORKS_AT, FREQUENTS, VISITED) or event_to_event (LED_TO, OCCURRENCE_OF). A category lists the verbs valid between those endpoint types. The catch-all cross_entity category (RELATED_TO) connects any two types when nothing more specific fits.

Caution

Some verbs are polymorphic — the same verb is valid for several source/target type pairs. Source membership and target membership are checked independently, so a structurally valid edge can still be semantically wrong. When you author through an agent, the relationship type you describe should match the pair of entities you’re connecting.

Semantic predicates

Alongside the structural relationship types, a world defines a set of semantic predicates — meaning-based, conceptual links that aren’t tied to specific endpoint types. Examples: inspired_by, similar_to, derived_from, influenced_by, consequence_of, prerequisite_for, symbolic_of. Use them to capture why or how two entities relate conceptually, where a structural verb would overstate the connection.

Tags

A tag is a label from the world’s shared vocabulary, applied across entities to keep terms consistent (so you don’t end up with both running and jogging). Tag matching is case-sensitive. The aggregated tag list — every tag and how many entities carry it — is itself queryable, which makes it useful for auditing taxonomy drift.

Closely related are enumerations: for each enumerable property, the dictionary of values entities currently use. Enumerations are descriptive and advisory — a guide to the established vocabulary, not a closed allow-list. New standard values can be registered as the world grows.

Lore

Lore is long-form prose attached to an entity — its history, description, and detail — stored as one or more titled chunks. Lore is indexed for semantic search, so an agent can find entities by meaning rather than exact wording. See Lore.

The default schema

Every world is created with the same starting set of entity types and relationship types. It’s a general-purpose schema for modelling people, places, and the things that connect them — and a starting point, not a ceiling. You’re free to extend it: add your own types and relationships as your world demands (a fiction world might add a Character type, an ops world a Contract type), and shape how it’s used with your world prompt.

Default entity types

Type	Represents
Person	The people (and pets) in your world.
Place	Locations and businesses — homes, destinations, venues, shops, services.
Event	Things that happen — gatherings, trips, appointments, milestones.
Group	Organizations and groups — families, teams, clubs, communities.
Project	Ongoing efforts with timelines — renovations, plans, side projects.
Interest	Hobbies and pursuits — photography, cooking, running, gaming.
Item	Things of note — a car, an instrument, a camera, an heirloom.

Default relationship types

The starting verbs are geared toward connecting people, places, groups, and events — for example Parent Of, Sibling Of, Spouse Of, Partner Of, Friends With, Works With, Mentors, Caretaker Of, Lives At, Works At, Frequents, Visited, Member Of, Leads, Attended, Organized, Practices, Owns, and Works On, with the catch-all Related To for anything that doesn’t fit a more specific verb. See Relationships above for how these are categorized and how direction and history work.

Discovering your world’s schema

None of the specifics above are guessed at runtime — an agent reads them. A single call to get_world_context returns the world’s complete vocabulary:

• entity_types — each type with its property_schema.
• valid_relationships — relationship categories and the verbs in each.
• semantic_predicates — the conceptual predicates available.
• enumerations — the current value dictionaries for enumerable properties.
• stats (optional) — entity counts by type and recently updated entities.

A connected tool calls this once at the start of a session, before reading or writing, so its work conforms to your world’s actual structure. For the full call surface — parameters, responses, and the other tools — see the MCP tool reference.