Lorebooks

An overview of the Lorebook feature, and how to make the most of them!

Dynamic Memory

A Lorebook is a powerful tool for expanding the AI's knowledge beyond the limits of Xoul, Scenario and Persona cards. Think of it as a story's dynamic, searchable encyclopedia that the AI consults only when needed to enrich the narrative.

Targeted, On-Demand Information

Unlike static other features, a Lorebook is a collection of entry cards (up to 250 per Lorebook) that are referenced as necessary during a chat. Each entry is a "chunk" of information (up to 1500 characters) about a person, place, object, or concept in your world. They can be able anything you want them to be about.

You can have up to 3 Lorebooks in a single chat. This gives you a potential pool of 750 entries, over 1.1 million characters of world-building detail, that the AI can intelligently draw from, without overwhelming its active memory!

However, only three entries total are pulled into context for each AI reply, preventing context from being overloaded with information that isn't currently relevant.

Lorebooks vs. Other Features

Xoul	Defines the AI model's character(s) (appearance, personality, backstory, etc.)	12,000 character limit 17,000 character limit (Gold Subscribers)	The actor(s) on the stage.
Persona	Informs the AI model who your character is (the basics of what you look like and what it needs to know about you).	1,000 character limit 2,000 character limit (Gold Subscribers)	Your role in the story.
Scenario	Informs the AI model what the chat / story will be about.	3,000 character limit	The story premise.
Lorebook	Defines everything else (the world, side characters, lore).	Up to 750 entries	The stage, props, and supporting cast.

How Entries Are Pulled: Keywords + RAG

Lorebooks on Xoul.AI use a two-step, intelligent system to decide which three entries are the most relevant for any given reply. It checks for keywords first, then uses context.

Keyword Matching

Each entry has a Keyword field. This is a specific word or phrase that, if detected in the recent chat, will force that entry to be considered for inclusion.

Example Entry:

• Name: Sarah Green

• Keyword: Sarah, Mrs. Green

• Content: Sarah Green is a middle-aged woman with long blonde hair and blue eyes.

In Chat: You write, "Do you know who Sarah is?"

• Result: The keyword "Sarah" is detected. Sarah's entry is pulled into context, and the AI can reply accurately: "Oh yeah, she's the lady with the long blonde hair."

Retrieval-Augmented Generation - RAG

If no keywords are matched, the system uses RAG. This technology analyzes the meaning and context of your latest message and finds the entries whose content is most semantically related, even without exact word matches.

In Chat: You write, "Who is that blonde woman I saw earlier?"

• Result: No direct keyword is found. However, RAG analyzes your sentence, understands the core concept ("blonde woman"), finds the entry describing a "blonde woman," and pulls Sarah's card. The AI can then reply: "Oh, you must mean Sarah Green."

This dual system gives you two chances for an entry to be recalled and frees you from having to keyword every possible synonym or related term.

---

Effective Keywords

The goal of keywords is precision, not coverage. Think of them as unique activation codes.

Do: Keep it Minimal & Specific

• Use Unique Identifiers: Nicknames ("The Boss"), rare titles ("Keeper of the Veil"), specialized terms ("Project Icarus"), or full names for minor characters.

• Less is More: The system is not case-sensitive and understands basic plurality. Keyword "grapefruit" will catch "Grapefruit" and "grapefruits."

• Force What Matters: A keyword should be for something you always want to trigger that entry when mentioned.

Don't: Use Common or High-Frequency Words

• Avoid Common Names: If your main character is Sarah, keyword-ing just "Sarah" will cause the entry to fire constantly, diluting its usefulness. Reserve keywords for her less-used formal name "Sarah Green" or a nickname "Sunshine."

• Avoid Generic Concepts: For an entry about "Favorite Foods," do not keyword food, eat, hungry, snack. These terms are too common and will cause irrelevant triggers. Instead, keyword a unique dish like "Grandma's Stew" or rely on RAG to pull the entry when the context of "favorite food" is discussed.

Tip: If a word is said often in general chat, it's a poor keyword. A good keyword is said rarely.

The goal of a keyword should be "this will always trigger this entry". It should not be keyed to more than three entries.

---

Lorebook Entry Fields

Name

The title of your entry.

Not included in the prompt when the entry is pulled. What is written here is purely aesthetic and cannot be used to help the AI model contextualize what the entry is about.

Keywords

You will need to create at least one keyword, but there appears to be no limit on:

• How many keywords can be included.

• How many characters a single keyword can be.

With that said, remember, less is more.

Keywords should be the exact word or phrase you want to always force this entry to appear.

Keywords are not case-sensitive or brittle.

grapefruit will successfully pull this entry if Grapefruits, grapfruits, or Grapefruit is written in the chat.

Content

What is typed here is included verbatim within the context of the AI's knowledge when the entry is pulled.

Common Mistake!

He is 27. He has short brown hair and green eyes. He works as a librarian.

...Who?

The name of the entry, and keywords, are not included in the context.

The system that pulls the entry is not the same as the AI model that reads the chat and responds to it. If this entry provides no information as to what the entry is about the model will not know what to do with the information.

Unless the AI model can find this character's name inside the context it will reach the conclusion that it doesn't know anything about the character you just asked about and either fabricate information about them (the same way it can fabricate background characters for the story) or simply say it doesn't know who you're asking about.

David is 27, has short brown hair, green eyes and works as a librarian.

Now it knows who this entry is about and will not either tell you it doesn't know who "David" is or fabricate incorrect information.

This tip applies to all text in all features. Do not expect the model to read your mind or carry concepts between one paragraph and the next.

Models have a limited attention span and will focus on blocks or chunks of text, sentences and paragraphs. At bare minimum every paragraph should be written in a way that makes it abundantly clear exactly what the paragraph is about.

Type

Purely for organization / aesthetic purposes. The type tags have no bearing on how an entry will be chosen. Simply select whichever tag you think best fits.

---

Frequently Asked Questions

Won't using huge Lorebooks consume massive memory?

No. Only three entries (max 4,500 characters) are actively injected into the AI's context per reply. While this does slightly reduce the space available for chat history, it's a powerful trade-off. The AI gains precise, relevant knowledge exactly when it needs it, and those three entries constantly change as your story develops.

What's the main challenge in using Lorebooks?

Ensuring the three most relevant entries are pulled at any given moment. Success comes from writing clear, descriptive entry contents and using the keyword system strategically to "pin" critical information when absolutely necessary, while trusting RAG to handle the rest contextually.

What can a Lorebook be about?

Anything. Primarily Lorebooks tend to cover subjects or concepts you want to provide additional information for, but for most subjects the AI model doesn't need entries for a bunch of topics it already knows. Instead Lorebooks function best as a collection of information the model wouldn't otherwise know. Things like small character cards, information about fantasy creatures, magic spells, past events in a fictional story, a character's unique information can all be used to fill out a Lorebook.

Here are some potential Lorebook types:

• Stock Characters: A collection of characters like shopkeepers, bar tenders, random citizens that fill out your world.

• Bestiary: If you're creating an original fantasy world, a Lorebook can contain all the information about the various creatures and monsters found in that world. If you're doing a story based on a media franchise that isn't well known the model wont already know what the various creatures from that franchise are called or look like.

• Spell Book: For a fantasy story you may want to create a collection of magic spells.

• Memory Book: The Memories field has limited characters and should only focus on the most immediately relevant information, but past events from much earlier in your story can still be important to the story. You can create, edit, and attach a Lorebook to a chat at any time. Having one Lorebook slot available for past events that you build alongside the story is a powerful way to expand the AI's memory of the events from the story.

• Character Book: An individual character can know dozens of other characters, frequent many locations, have a storied history and a laundry list of preferences about all sorts of things. A Lorebook can be exclusively focused on just one character's full knowledge.

• Prompt Book: This requires a lot of careful design, but it's possible to create a Lorebook that provides prompts (e.g. the simple kind like instructions for handling explicit scenes or a prompt for how to handle a topic models tend to struggle to write well) that are included in context while it is helpful for the model to see it. It'll require clever keyword usage and a good understanding of how RAG interprets context, but it would be well worth the effort.

Feeling overwhelmed?

Take it piece-by-piece and create a backup of your Lorebook. They don't need to be completed in a single sitting or even completed before you use them.

• You can edit a Lorebook at any time and continue using it in a chat uninterrupted.

• You can add or remove Lorebooks from the chat at any time, it won't prevent you from continuing your story.

Google Sheets is a great place to build a Lorebook before you create it in Xoul.AI. You can more easily reorder your entries on sheets and create copies and backups.

SAVE FREQUENTLY when building a Lorebook.

The platform will attempt to restore a backup of your progress if anything happens, however, because a Lorebooks can require a great deal of time & effort it is never worth risking. Save out your Lorebook every few entries. It is better to be safe than sorry.