RisuAI Lorebooks and Memory (2026): How Entries Trigger, the 800-Token Budget, Decorators and HypaMemory

A RisuAI lorebook is a set of entries that are added to the prompt only when they are needed: each entry has activation keys, and it is sent to the model when one of those keys appears in the last few messages. RisuAI’s own help text calls it “a user-made dictionary for AI”. It is how a world with fifty places and thirty people fits into a prompt that has room for five of them.

RisuAI’s wiki explains the idea in a page of about 200 words, under a notice that the wiki is outdated. The rules that decide whether your entry actually reaches the model are only in the code. This guide is built from that code: the commit of 10 October 2026 (version 2026.8.250), read on 12 October 2026. We did not test these behaviours in a running chat, so everything below is what the code does, described in plain words.

New to RisuAI? Start with the RisuAI guide. Coming from SillyTavern? See RisuAI vs SillyTavern and SillyTavern lorebooks for the differences.

The Short Answer

Scan depth is 5 messages on a new install. A key mentioned six messages ago does not count.
The budget is 800 tokens for all activated entries together. It does not grow when you raise your context size. Raise it yourself.
Higher insert order wins. When the budget is full, entries with a higher insert order are kept and lower ones are dropped. Higher ones are also placed where they affect the model more.
Matching ignores spaces by default, so short keys match in more places than you expect.
Entries can trigger each other. Recursive scanning is on by default.
Extra settings are written as @@ decorators at the top of the entry’s prompt.
Long-term memory is off until you choose a system and switch it on for the character.

Where Lorebooks Attach

RisuAI collects entries from three places and treats them as one list.

Where	Applies to	Use it for
Character lorebook	Every chat with that character	The character’s world, people and history
Chat lorebook	That one chat only	Facts that became true in this story
Module lorebooks	Every character, while the module is switched on	A shared world or rule set you reuse

A module is a RisuAI file (.risum) that bundles lorebooks, regex scripts and trigger scripts. Switching a module on adds its lorebook to whatever character you are talking to. It is the closest thing RisuAI has to a global lorebook.

When you import a character card that has a lorebook inside it, the entries arrive in the character lorebook.

What an Entry Contains

From the app’s help texts:

Name. “It doesn’t affect the Ai.” It is a label for you.
Activation keys. Separated by commas. “If one of the activation key exists in context, the lore will be activated and prompt will go in.”
Insert order. “If insert Order is higher, it will effect the model more, and it is less likely to be cut when many lores are activated.” The old wiki recommends leaving it at 100 if you are not sure.
Prompt. The text the model receives.
Always active. The entry is added on every message, with no key needed.
Selective. “If Selective mode is toggled, both Activation Key and Secondary key should have a match to activate the lore.”
Use regex. The keys are read as regular expressions in /pattern/flags form.

One rule from the code is easy to miss: an entry with no key that is not always active is skipped. It is never checked at all.

How Matching Really Works

Before each reply, RisuAI takes the last messages of the chat, up to the scan depth, and looks for each entry’s keys in them. Both your messages and the character’s messages are searched.

Scan depth is 5 by default. A character can have its own value that replaces the global one.

Matching is not case-sensitive. Dragon and dragon are the same.

By default, spaces are removed first. This is the part that surprises people. In the default mode, RisuAI removes every space from the message and from the key, and then checks whether the key is inside the message. Three results follow:

Key	Message	Fires?	Why
`red dragon`	”a red dragon landed”	Yes	”reddragon” is in the text
`red dragon`	”the tired dragon slept”	Yes	”tired dragon” becomes “tireddragon”, which contains “reddragon”
`cat`	”we looked at the catalog”	Yes	”cat” is inside “catalog”
`cat`	”a magic attack”	Yes	”magic attack” becomes “magicattack”, which contains “cat”

Short keys are the risk. A three-letter key will fire in many messages that have nothing to do with it, and each time it fires it spends part of the budget.

Full word matching is the alternative, and it has its own traps. With full word matching on, RisuAI splits the message at spaces and checks whether one of the pieces is exactly the key. From the code, this means:

A key with a space in it, such as red dragon, can never match, because no single piece contains a space.
A word followed by punctuation does not match. dragon does not fire on “the dragon.” because the piece is “dragon.” with the full stop.
A word at the end of a line can fail in the same way, because the split is on spaces only, not on line breaks.

Full word matching is off by default and can be switched on for a character. A single entry can choose its own mode with the @@match_full_word or @@match_partial_word decorator.

Our advice from these rules: keep the default mode, and write keys that are long and specific. Use Aldric,Captain Aldric and not Al. Use Thornwall Keep and not keep.

Regex mode. If an entry uses regex, every key must be written as /pattern/flags. If one key in the entry is not in that form, the code gives up on the whole entry and it never matches. Regex keys are tested against the message as written, so add the i flag if case should not matter.

Selective mode needs two matches: one from the activation keys and one from the secondary keys.

The Budget and the Insert Order

After RisuAI has a list of activated entries, it decides which ones fit.

It sorts the activated entries by priority, highest first. The priority is the insert order, unless a decorator changes it.
It adds entries one by one while the total stays within the token budget. An entry that does not fit is left out. A smaller entry further down the list can still be added if it fits.
It then arranges the kept entries by insert order for the prompt, with the highest insert order placed last, nearest to the newest text.

The budget is 800 tokens on a new install. That is a fixed number, not a share of your context. As a rough guide, 800 tokens is about 600 words. Four entries of 150 words each will fill it.

So on a default install, with a rich world, this happens: seven entries activate, the four with the highest insert order are sent, and the other three are dropped without a message. To the player it looks as if the lorebook did not work.

Two fixes:

Raise the lorebook token budget in the settings, or set a higher budget for that character. If your Max Context Size is 32,000, a budget of 2,000 to 4,000 is reasonable.
Set insert order on purpose. Give the entries that must never be dropped the highest numbers.

The token count is taken after RisuAI has processed any curly-brace syntax in the entry, so an entry with a condition is measured at the size it will really have.

Recursive Scanning

Recursive scanning is on by default. When an entry activates, its prompt text is added to the text being searched, and RisuAI searches again. An entry about “Thornwall Keep” that mentions “Captain Aldric” can activate the entry for Captain Aldric, even if nobody said his name.

This is useful, because a place can bring its people with it. It is also the fastest way to fill an 800-token budget. If your entries mention each other freely, one key can pull in six entries.

You can switch recursive scanning off for a character. You can also control it for one entry:

@@unrecursive: this entry’s text is not searched for other entries’ keys.
@@recursive: this entry’s text is searched, even if recursive scanning is off for the character.
@@no_recursive_search: this entry can only be activated by the chat, not by another entry’s text.

Decorators: Settings Inside the Entry

RisuAI puts most advanced settings in the entry’s prompt as decorators. A decorator is a line that starts with @@, at the top of the prompt. RisuAI reads it and removes it before the prompt is sent.

@@depth 2
@@probability 50
Thornwall Keep is a ruined fortress on the north road. Its well is dry.

These are the decorators the code handles, grouped by what they do.

When the entry activates

Decorator	Effect
`@@activate`	Always activates, whatever the keys say
`@@dont_activate`	Never activates
`@@probability 30`	Activates 30% of the time when its conditions are met
`@@activate_only_after 10`	Only once the chat has at least 10 messages, counting the greeting
`@@activate_only_every 5`	Only when the message count divides by 5
`@@keep_activate_after_match`	After its first match, stays active for the rest of that chat
`@@dont_activate_after_match`	After its first match, never activates again in that chat
`@@is_greeting 1`	Only in chats that started from that alternate greeting (1 is the first alternate)

Which keys count

Decorator	Effect
`@@additional_keys castle,keep`	A second set of keys that must also match
`@@exclude_keys dream,memory`	If any of these appears, the entry does not activate
`@@exclude_keys_all a,b`	The entry is blocked only if all of these appear
`@@scan_depth 10`	This entry looks back 10 messages, not the global 5
`@@match_full_word` / `@@match_partial_word`	Matching mode for this entry

Where the entry goes

Decorator	Effect
`@@depth 2`	Inserted into the chat history, 2 messages from the end
`@@role system`	Sent as a system, user or assistant message
`@@position after_desc`	Placed after the character description (`before_desc`, `personality` and `scenario` also work)
`@@priority 500`	Changes which entries survive the budget, without changing where it is inserted
`@@ignore_on_max_context`	First to be dropped when the budget is full

Two decorators are worth knowing by name. @@keep_activate_after_match turns an entry into a permanent fact once the story reaches it: the moment someone says “the king is dead”, that entry stays for the rest of the chat. @@scan_depth lets one important entry look further back than the rest.

The code also names some decorators for “instruct mode” and ignores them, with a comment that instruct mode does not exist in RisuAI.

Importing and Exporting

The lorebook import accepts a .json or .lorebook file in two shapes:

RisuAI’s own format.
A file with an entries list, which is the format SillyTavern world info files use.

For the second kind, RisuAI converts what it stores differently. An entry with a probability below 100 gets @@probability at the top of its prompt. An entry set to appear “at depth” gets @@depth and @@role. Open an imported entry and you will see those lines; they are settings, not mistakes.

After importing a SillyTavern lorebook, check two things. First, the budget: SillyTavern’s default is 25% of the context, and RisuAI’s is 800 tokens, so a lorebook that fitted there may be cut here. Second, short keys: SillyTavern and RisuAI match keys differently, and a key that was safe there may fire too often here.

Long-Term Memory

A lorebook holds facts you wrote. Long-term memory holds what happened in the chat. In RisuAI it is a separate system, and it is off on a new install.

The setting has four options:

Option	What it is
SupaMemory	The original. When the context is full, it asks a model to summarise old messages, and summarises the summaries again when needed
HypaMemory V2	Summaries plus similarity search
HypaMemory V3	The newest, with the most settings
Hanurai Memory	A separate method with its own token setting

You choose one in the settings, and then switch memory on for the character you want it for. The memory systems use an embedding model to find similar text, and a summarising model that can be your Auxiliary Model.

HypaMemory V3 in numbers

The defaults, from the code:

Setting	Default	Meaning
Memory tokens ratio	0.2	The memory block gets 20% of Max Context Size
Max chats per summary	6	One summary covers up to 6 messages
Recent memory ratio	0.4	40% of the block: the newest summaries
Similar memory ratio	0.4	40% of the block: summaries most like the current chat
Random	the rest	20% of the block: summaries chosen at random
Query chat count	3	The last 3 messages are used to find similar summaries

Here is what that means at two context sizes:

Max Context Size	Memory block	Recent	Similar	Random
4,000 (the default)	800 tokens	320	320	160
32,000	6,400 tokens	2,560	2,560	1,280

At the default context size, the “similar” share is 320 tokens, which is two or three short summaries. Long-term memory in RisuAI only becomes useful after you raise Max Context Size. That is the same first step we recommend in the RisuAI guide.

The random share is a design choice we have not seen in other front ends. It means an old event that is neither recent nor similar to the current scene still has a chance of coming back.

Lorebook or memory?

Use both, for different things.

Lorebook: facts that must be exact. A name, a rule of the world, who rules which city. You control the words.
Memory: what happened. It is a summary written by a model, so details can be lost or changed.

If something in your story becomes a fixed fact, such as a death, an oath or a new title, write it into the chat lorebook by hand. A summary may keep it. A lorebook entry will.

Why an Entry Never Fires: A Checklist

Is there a key? An entry with no key and no “always active” is skipped.
Was the key said in the last 5 messages? If not, raise the scan depth or add @@scan_depth.
Is the budget full? With an 800-token budget, a few long entries use it all. Raise the budget, or raise this entry’s insert order.
Is full word matching on? Then a key with a space never matches, and a word followed by a comma or a full stop does not match.
Is selective mode on? Then a secondary key must also appear.
Is it a regex entry? Every key must be in /pattern/flags form, or the entry never matches.
Is there a decorator in the way? @@probability, @@activate_only_after, @@exclude_keys and @@dont_activate_after_match all stop an entry on purpose.
Is the lorebook attached where you think? A chat lorebook belongs to one chat. A module lorebook only works while the module is switched on.
Is the whole prompt too large? If you see “Error: The minimum required token is greater than the Max Context Size”, the problem is the context size, not the lorebook.

And the opposite problem, an entry that fires too often: the key is too short. In the default mode it matches inside and across other words. Use a longer key.

Frequently Asked Questions

How does a RisuAI lorebook work?

Each lorebook entry has activation keys and a prompt. Before every reply, RisuAI searches the most recent messages for the keys. If a key is found, the entry’s prompt is added to what the model reads. Entries that are set to always active are added every time. All activated entries together must fit inside the lorebook token budget, and the ones that do not fit are left out.

Why is my RisuAI lorebook entry not triggering?

The usual causes are that the key was last mentioned more than five messages ago, that the 800-token budget was already used by entries with a higher insert order, that full word matching is on and the key has a space or the word is followed by punctuation, or that the entry is in selective mode and its secondary key did not appear. An entry with no key that is not set to always active is skipped completely.

What is the default scan depth and token budget in RisuAI?

A new RisuAI install scans the last 5 messages for lorebook keys and gives all lorebook entries together a budget of 800 tokens. Both can be changed in the settings, and each character can have its own values that replace the global ones.

What are decorators in a RisuAI lorebook?

Decorators are lines that start with two at signs at the top of an entry’s prompt, such as @@depth 2 or @@probability 30. RisuAI reads them as settings for that entry and does not send them to the model. They control where the entry is inserted, how far back it scans, how often it activates, and which other keys must or must not be present.

Can RisuAI import a SillyTavern lorebook?

Yes. The lorebook import accepts a JSON file in RisuAI’s own format or one with an entries list, which is the SillyTavern world info format. RisuAI converts settings it stores differently into decorators, so an entry’s probability becomes @@probability and an at-depth position becomes @@depth and @@role.

Does RisuAI have long-term memory?

Yes, but it is off on a new install. RisuAI has four options: SupaMemory, HypaMemory V2, HypaMemory V3 and Hanurai Memory. They work by summarising older messages and putting the summaries back into the prompt. You choose one in the settings and then switch it on for a character.

How much of the context does HypaMemory V3 use?

By default, HypaMemory V3 gives its memory block 20% of the Max Context Size. Inside that block, 40% goes to the most recent summaries, 40% to summaries most similar to the current chat, and the remaining 20% to summaries picked at random. Each summary covers up to 6 messages.

The default scan depth and token budget, the three lorebook sources, the key matching logic, the budget and ordering steps, recursive scanning, the decorator list, the import formats and conversions, the memory options and the HypaMemory V3 defaults are from RisuAI’s source code in the kwaroran/Risuai repository on GitHub (commit of 10 October 2026, version 2026.8.250), read on 12 October 2026. Quoted help texts are from the app’s English language file, and the SupaMemory description and the insert order advice from the project’s wiki, which the project marks as outdated. We read the code and did not test these behaviours in a running chat. The word counts given for token amounts are rough conversions. We have no commercial relationship with the RisuAI project.

RisuAI and SillyTavern are the property of their respective owners. Arcanum is not affiliated with either.