> For the complete documentation index, see [llms.txt](https://xoul-ai-official-documentation.gitbook.io/xoul.ai-official-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xoul-ai-official-documentation.gitbook.io/xoul.ai-official-guide/navigation-and-information/navigation-and-interfaces/content-creation/lorebooks.md). # Lorebooks ## 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](https://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."* {% columns %} {% column width="16.666666666666664%" %} {% endcolumn %} {% column width="66.66666666666667%" %} {% hint style="success" %} 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. {% endhint %} {% endcolumn %} {% column width="16.66666666666665%" %} {% endcolumn %} {% endcolumns %} *** ## 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. {% hint style="info" %} **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. {% endhint %} *** ## 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. {% columns %} {% column %} {% hint style="warning" %} **With that said, remember, less is more.** Keywords should be the **exact word or phrase** you want to **always** force this entry to appear. {% endhint %} {% endcolumn %} {% column %} {% hint style="success" %} Keywords are **not** case-sensitive or brittle. `grapefruit` will successfully pull this entry if `Grapefruits`, `grapfruits`, or `Grapefruit` is written in the chat. {% endhint %} {% endcolumn %} {% endcolumns %} ### 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. {% hint style="warning" %} 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. {% endhint %}
### 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. {% columns %} {% column %} {% hint style="success" %} 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. {% endhint %} {% endcolumn %} {% column %} {% hint style="danger" %} **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. {% endhint %} {% endcolumn %} {% endcolumns %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://xoul-ai-official-documentation.gitbook.io/xoul.ai-official-guide/navigation-and-information/navigation-and-interfaces/content-creation/lorebooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.