How to Create Lorebooks - by NG

Scope and Purpose

This is meant to be a light-duty/quick guide written in plain English. Better / more complete documentation links are provided at end.
This covers Lorebooks as used in Silly Tavern / CHUB, and is based on my experience writing in Turbo 3.5 4K in mid-2023.
YMMV, and note these AI are emergent... some of below advice will change in time.
UPDATED JUNE 2023 for Turbo 16K - Budget impact.

What they are

TLDR: Lorebooks are long term memory for RP with AI's.

The Lorebook just provides additional information about the game's locations, characters, history, items, and other related aspects. They give the AI enriched understanding of the RP's narrative setting, offering background details and context that enhance the immersion and depth of the story.

Think of them as long term memory for the AI; things that it could recall, but isn't part of the short term memory (aka Context) for the rest of the chat.

How to use them

TLDR: Use Lorebook entries anytime you need to define a place, person, or thing that the AI couldn't generate on its own.

Lorebook entries can be used for any new thing that you want to closely define, rather than have the AI generate on its own. But keep in mind AI can generate a lot... for example, do you really need to closely define a "Restaurant?" Or a "Club?" If the setting is really important, then perhaps. If not, it might be better to let the AI fill in the blanks... it's really good at doing that. Random stranger? AI can generate that on the fly. Need the new NPC to be defined? Use a card.

Entries

TLDR: Entries are called by a word, and have a short definition attached.

Lorebook entries work by looking for certain words in the text (the Key), then inserting a lorebook entry when it sees the word.
Here are some examples from one of my simpler lorebooks: https://www.chub.ai/lorebooks/NG/american-high-school

Example Place

Here's an example from a fictional clothes store:

Key: clothes store,clothing store

Content: Place: Clothes Store Description: Owned by Carol. During the day it sells clothing.

So, when the AI sees the phrase "clothing store" in the chat, generated by either the AI or the User, it will insert the Content shortly below the most recent message.

Note that Content includes the Key... the Key is not added to the Content that Silly Tavern includes.
Also note that the Key has 2 names, separated by a comma with no spaces. Either one of those Key names will call this lorebook entry.

Here's an example from American High School:

Key: Class,Classroom
Content: Classroom,hallways

What's the purpose of this? When {{user}} enters to go to class, NPCs assigned to both the Hallway and the Classroom are pulled in.

Example Person

Here's an example from a fictional clothes store:

Key: Carol
Content: Name: Carol Occupation: Clothes Store owner Description: tall woman, blue eyes, long blonde hair, fashionable

Again, when the AI sees Carol, it inserts the Content shortly below the most recent message.
This allows you to add new NPCs to the chat without group chat, and closely define the NPCs.
Note that this format is open; you could also write it like this:

Key: Carol,store owner
Content: Carol is the Clothes Store owner. She is a tall woman with blue eyes, long blonde hair, and dresses fashionably

The above is more or less equivalent. Interestingly, the token count is almost identical because of the need for transitioning words, so I usually use the former as it's easier to organize. Really, any format that works for the cards will work for these lorebooks.

What's fun about Named NPCs is that the AI engine will drop them where they go. If the AI knows that {{user}} is in at the Clothes Store, and Carol works there... Carol will appear, and may interact with either {{user}} or {{char}}

Here's an example teacher from American High School:

Key: Johnson,Math,Calc,Calculus,Trig,Trigonometry

Content: Mrs. Johnson is a strict yet highly knowledgeable math teacher. She is known for challenging her students and pushing them to excel in mathematics.

And a student:

Key: Michael,overachiever,Class

Content: Michael is an ambitious overachiever who spends most of his time in the classroom

So, if {{user}} goes to Math Class, they'll encounter both Mrs. Johnson, as well Michael and any other students flagged in Classroom.

Or, let's say you want all the jocks to show up at one place...

Key: Chad,jock,jocks,field

Content: Chad is a charismatic quarterback who hangs out on the field.

Now, anytime {{user}} sees a group of jocks, or goes on the field... there is Chad.

Example of what not to do

Bad example #1

Key: Collar

Content: Collar is a thin leather collar studded with fake jems, and the word "YORKIE" inscribed on it.

So... does any of that above information help the AI? Does it matter to the story?
I did something like above for a lorebook, and realized it was a waste of tokens. The AI doesn't need this information, won't likely use it, and anyway can guess what a collar would look like based on a 1 word definition e.g. decorative collar, stiff collar, thick collar, etc.
Experiment, and if you don't see the AI using the information, or it doesn't impact the RP... ditch it.

Bad example #2
Key: Club

Content: Club is a vibrant night club with music, dancing, and lively ambiance. DJ beats, dazzling lights, and drinks flowing. People socialize, party, and create memorable experiences.

Above is about 40 tokens and descriptive. So what's wrong with it?

  1. It's AI-redundant. It's literally what ChatGPT spit out when I asked for a 50 token nightclub description. Just telling AI "{{user}} went to a night club" would have been enough for the AI to build the above definition, without the need to spend tokens. If you're going to define the Club, add information that the AI wouldn't know, i.e. Brad works there, it's attached to a laundromat, the floor randomly consumes dancers, etc.
  2. Key is too generic; Club could be anything (night club, strip club, book club, etc.). It would be better to give a proper name in this case i.e. Rumors, or some such, then define it.

Other Examples

Other potential entries: very specific objects, drugs / substances, clothing items, tasks/duties for {{char}}. The list of potentials is endless but note that unless the object is very unique, it may not need a definition... the AI can figure something out. Review other lorebooks for ideas on how authors use them.

Recursion

With the above example, note that Carol includes Clothes Store. With recursion turned on, if Carol is mentioned, Silly Tavern will also pull the lorebook entry for the clothes store as well. With Recursion turned off, this association won't be made.

Recursion can also be used to group a bunch of simpler NPCs together. Here's an example from American High School:

Key: Stacy,Cheerleader,field
Content: Stacy is a blond cheerleader that hangs out on the field

Key: Carrie,nerd,library
Content: Carrie is a brunette nerd that hangs out in the library

Key: Brad,Jock,field
Content: Brad is a hispanic jock that hangs out on the field

Key: Carl,hipster,lot
Content: Carl is a skinny brown-haired hipster that hangs out in the parking lot

With these Key(s), the can be popped into the story everytime a Nerd (Carrie) or Jock (Brad) is referenced.
Using Recursion, you can add additional associations, like so:

Key: bookworms
Content: Carl, Carrie are nerds
Key: Popular
Content: Stacy, Brad are popular

Now, when "Popular" comes up, Silly Tavern will see this includes Brad and Stacy. With Recursion, it will go back through the lorebook, and pull the complete NPC definitions for Brad and Stacy as well.

Budget

TLDR: You have a limited budget. Keep it short.
UPDATE: *Figure a 5% Lorebook budget. 4,000 Tokens = 200 for Lorebook. 16,000 tokens = 800 for Lorebook. Same for Entries - 4X for 16K
UPDATE 2: Silly Tavern now just uses % budget for Lorebook

For Silly Tavern, the default Budget for the lorebook is 200 tokens (Note: This was set when Turbo was 4K context). The point of the lorebook is to only pull in what you need, not the whole thing every time. Ideally, lorebook entries are either short (and you get a few) or long (and you get one.)
I generally try to keep lorebook entries under 50 tokens, so that every round Silly Tavern can pull in 3-4 of them, as needed.
For example, that might be 2 Named NPCs, as well as their surroundings.

Why not expand the token budget? Well, for base Turbo you get about 4000 tokens. That 200 Lorebook budget is fighting for space with your character definition(s), NSFW prompt, JB, Author Notes, etc. What's left goes to Context, and generally more Context = Better RP. Generally, I've found lower token count is better for several reasons:

  1. AI responds better to tighter / shorter definitions
  2. Forces bot author to be efficient... do you really need more?
  3. Less tokens = more past chat in Context
  4. How many Lore entries do you really need?
    In the future, when Context is larger... 3 won't matter as much but I'd bet 1 and 2 still do. As for 4: if you need 200 tokens to create your lore entry, just make sure your budget supports that. My goal: 3-4 lore entries tops, in a budget of 200 tokens. So lore entries need to be ~50 each.

UPDATE JUNE 2023: The future is now. If you're running Turbo 16K, you've 4X the context of 4K. I'd argue could reasonably go up 4X on your descriptions, which means a total budget of 200 tokens per entry and a total budget of 800. The basic logic IMHO is the Lorebook should be around 5% of the total context budget, and there should be sufficient budget for 3-4 entries per API submission.

Random Events via Lorebook in Silly Tavern

As of Silly Tavern v1.8, there'a new function to add random events via the lorebook. You can create trigger events, randomly, through the lorebook setting by using "Use Probability" setting. Some notes on this:

Simple Random Events Trigger

  1. "Use Probability" nests with "Constant" or "Key" values.
    a) Example event, 10% probability: Constant: Checked. Use Probability, 10. Keyword: Blank
    b) Example event, 10% probability when "ABC" Key condition met: Constant: Unchecked. Use Probability, 10. Keyword: ABC
  2. Note that for above, if you have several random events, any or all of them could be triggered.

Random Selected Event Trigger

If you want to set up events that only trigger one at a time, see example below:

Add three lorebook entries tagged with the Keyword "xaab", "xaac" and "xaad" and one with a blank keyword

Keyword: [blank] Content: {{random:xaab,xaac,xaad}} Constant: Checked, Placement: Before Char
Keyword: xaab Content: You are surrounded by a lush forest. Placement: Author's Note Bottom
Keyword: xaac Content: You are surrounded by putrid swamp. Placement: Author's Note Bottom
Keyword: xaad Conten: You are surrounded by a pleasant meadow. Placement: Author's Note Bottom

By setting the first one to constant (the keyword doesn't actually matter) and set to appear before character definitions, the nonsense prompt return will have no impact on the context, past triggering the randomly selected Keyword.
The other three are set to appear after the author's notes. This way, the "key" (example: xaac) will be high up in the context, while description (example: putrid swamp) would be near prompt.
Make sure to set recursive scan! Otherwise the above it won't work.

Oddnesses

  • You may observe Silly Tavern seems pulling in seemingly uncalled definitions: By default, Sillytavern does not match on word boundaries. That means for example that an entry with the keyword "cat" will match (and include it) when you're talking about caterpillars, scat, education, and so on. There's an option to stop this behavior (Match whole words), but you can only set this globally.

My pointers guide on character card creation: https://rentry.org/NG_CharCard
Official Silly Tavern Worldbook info: https://docs.sillytavern.app/usage/core-concepts/worldinfo/
KobaldAI pro-tips, note entries on World Description: https://github.com/KoboldAI/KoboldAI-Client/wiki/Pro-Tips
Other example lorebooks on CHUB: https://www.chub.ai/lorebooks

About the author

My work's posted here, including lorebooks. One of the best ways to learn is to play with bots, and take what works.
https://www.chub.ai/users/NG

Edit
Pub: 12 Jun 2023 16:09 UTC
Edit: 22 Jan 2024 01:31 UTC
Views: 11155