World Lore

{
  "worldLore": {
    "<key>": {
      "text": "string"
    }
  }
}

{
  "worldLore": {
    "The Old War": {
      "text": "The Old War ended sixty years ago but its consequences define every political relationship in the realm. Three kingdoms fought over the Thornfield Basin for a generation. No party won outright; a ceasefire was signed when all three crowns ran out of soldiers. Contested borders, unresolved grievances, and two generations raised to distrust their neighbors are its legacy."
    },
    "Gnoll": {
      "text": "Gnolls are hyena-headed scavengers and opportunist raiders operating in competing packs across the frontier regions. Average combatant tier: strong. They avoid pitched battles against organised resistance, preferring ambushes of isolated travellers and undefended settlements. Pack alphas carry crude but effective weapons; rank-and-file gnolls fight with clubs, stolen gear, and numbers."
    },
    "Guest Right": {
      "text": "Guest right is among the most sacred obligations in the realm — any guest who has eaten food or drunk water under a host's roof is protected from harm for the duration of their stay, and the host is equally protected. Violating guest right is considered a profound moral transgression that damages reputation across all factions. The protection ends when the guest formally departs or the host formally ends the relationship."
    }
  }
}

#Engine behavior

#World lore is not region-filtered

NPC and location memories are filtered by the party's current region during retrieval — world lore is not. Every worldLore entry is always a candidate for retrieval regardless of where the player is. This makes it the right place for global world rules, cross-regional history, and facts that should be accessible anywhere in the world.

Retrieved entries reach the AI as narrator-only setting information: it uses them but won't reveal them to players without narrative justification.

#Authoring tips

#Key naming

Use Title Case with natural spacing: "The Old War", "Guest Right", "Gnoll". The key exists for authoring clarity; the AI only sees text, so the text has to name its own subject.

Two approaches to the "key title not in context" problem both work in practice:

• Grammatical subject opener: make the subject name the first word of the first sentence ("Guest right is among the most sacred...") — clean prose, no redundancy.
• Inline colon notation: open with "Subject Name: description..." embedded in the text itself ("Gnoll: Hyena-headed scavengers...") — explicit, impossible to miss, reads mechanically.

Type-prefix pattern for keys ("Creature: Hollow", "Hazard: Black Tide") keeps a large library easy to scan while authoring.

#What belongs in worldLore

The most consistently valuable entry categories across well-developed worlds:

• Historical events — wars, catastrophes, founding moments whose consequences still shape current politics or culture. Keep to current consequences, not blow-by-blow chronicles.
• Creature and monster ecology — appearance, behavior, power tier, habitat, and combat relevance. Open by naming the creature and its power tier.
• Magic and technology systems — how the system works, its costs and limits, who can use it. Make it narratable, not just named.
• Social customs and institutions — behavioral rules the AI must know: hospitality codes, honor obligations, religious taboos, feudal duties, trial procedures. This is the most underused high-value category. Entries that teach the AI "what happens when X occurs" produce more consistent world behavior than entries that only describe what X is.
• Faction mirrors — pair each entry in factions with a worldLore entry under the same key whose text matches the faction's basicInfo. The lore copy is found by semantic search and the faction by its key, so the same content has two retrieval paths. Nothing enforces the pairing. See the Faction + World Lore sync rule on the factions page.
• Faction depth beyond basicInfo — internal structure, rank systems, secret operations, historical origin. Use a separately keyed worldLore entry for content that exceeds what a faction's basicInfo can hold; do not overwrite the mirror entry.

#What does not belong here

• Location descriptions that belong in locations.basicInfo — short geography stubs add noise with minimal retrieval value.
• NPC personality and backstory that belongs in npcs.basicInfo / hiddenInfo — duplicating NPC content in worldLore creates maintenance inconsistency with no retrieval benefit.

#Entry length

A good lore entry is dense and self-contained, covering one topic without leaning on other entries, since retrieval may surface it alone. System-level entries (a magic system, an organization's hierarchy) can run longer; an entry covering several topics usually retrieves better split into separate entries.

#Entry count and context pressure

WorldLore is not region-filtered, so every entry competes for retrieval in every scene. Tightly scoped entries retrieve more accurately than broad or overlapping ones, so favour specificity over coverage.

#First-sentence rules

Make the first sentence carry the entry. It should:

• Establish the subject explicitly so the entry reads as a self-contained fact
• Function as a diagnostic summary including the most retrieval-relevant property
• For creatures: include tier/power and key capability
• For institutions: role and leverage
• For hazards or locations: what it is and why it matters

#Narrator-only secrets

For information the AI should know but not surface prematurely, frame the entry explicitly as narrator-only context:

"Lord Aldric is working for the enemy. He passes information through his servant Marcus. The player should not learn this until they find evidence themselves."

The narrator uses these for consistent behind-the-scenes behavior but will not state them directly until the story supports it.