Search was one of the reasons Atlavium came to exist. In the first blog post, I wrote about my Dungeon Master and his OneNote. The notes were there, but the information we needed always seemed to be in a different section. My own character diary does not make things any easier over time. After each session there is more to add, and eventually I want to find a name I can only vaguely remember.

The document search has grown into a much larger project since then. Its original job is still there. That is why I reworked search again with version 1.16. The short version is in the changelog. Here I want to take a little more time to explain what happens when you search and why I made some of these choices.

What search knows about your Realm

First, search needs something to look through. When you save an entry, Atlavium adds its title, tags and searchable text to a search index. Think of it as the index at the back of a book, but for your Realm. It lets you find a sentence in the middle of a long document without remembering which folder it lives in.

For Documents, this includes the saved text. For World Entities, it includes their description. When you create a character such as Mira Fenn and write down her history, search can find her through that description too. If you add a Profile to a World Entity, you choose which fields count through “Include in search”. A counter on a character sheet does not need to join every search.

The “Use in Search and Keeper” switch lets you leave an entire entry out. You can still read it, but it will appear neither as a search result nor as a source for the Keeper. Search also stays inside the Realm you currently have open. It does not look through your other Realms or the history of your Keeper conversations.

A name is often only the beginning

Take Mira Fenn from the Mistmarch demo Realm. When you enter her name, her own entry is an obvious match. But she might also appear in a letter or a longer document about the Harbor Archive. You want to find those Documents too, without having to decide whether you are looking for a World Entity or a text first.

Search weighs several things together. Does the title match? Is the word in a tag or somewhere in the text? How much does it distinguish this entry from the rest? A rare term tells us more than a word on almost every page. Names and tags carry more weight than a passing mention in a paragraph. The last update also plays a part, with the bonus for recent changes fading over time. An old note does not simply disappear from search because of its age.

Words do not always have to be written exactly the same way either. Atlavium uses word stems based on your Realm's language, so “ship” and “ships”, for example, can match. It also allows for small typos, especially in names and tags. It is more cautious with body text, so that every word with a vaguely similar spelling does not produce another result.

All of this contributes to a shared order. Documents and World Entities have no reserved places in the list. You can also sort by name or last updated when that suits your search better.

Connections belong in search too

In a role-playing world, some of the knowledge sits between entries. Mira Fenn is a member of the Harbor Archive. That Relationship is recorded in Mistmarch's World Graph. So when you search for Mira, the Harbor Archive can appear too, even if her name is absent from its description. The note “Found through a connection with Mira Fenn” explains how search arrived there.

Simplified example of searching for Mira Fenn: her name leads to her World Entity and mentions in Documents. Her recorded membership can also lead to the Harbor Archive. The example does not show a fixed ranking.

The connections you record in your Realm have a job to do when you look something up. For me, that belongs to the original idea behind Atlavium: a world grows through the connections we discover while playing. If you already write those down, search should be able to use them. It draws on the saved connections. It does not invent a new Relationship while searching.

When the group uses different words

A group rarely sticks to its own terminology all the time. A place has a long name, people shorten it in conversation, and the notes may still use an older spelling. Allowing for typos alone cannot solve that.

That is what Search vocabulary under Settings → Search is for. You can connect a preferred term with aliases, synonyms and abbreviations. If your group calls the Harbor Archive “HA”, for example, you can record that abbreviation there. Atlavium then considers these additional terms automatically in search and for the Keeper. Your original query stays part of the search. Your texts and Canon are not rewritten.

You do not have to work through your whole Realm to get started. A clear title and a few useful tags already help a lot. Search vocabulary is for the terms your group regularly uses differently from what is written in the Compendium.

When too much or too little appears

A name or a few specific words will usually help with a quick lookup. If you know the information is in a letter, you can narrow the search to Documents. If you want a character or a place, choose World Entities. Advanced Search also offers categories, tags and favorites. You can put a fixed phrase in quotation marks.

Search collects a limited selection from each content type for the shared result list. If you see a notice about that limit, a more specific term or a filter will help. Very weak matches are hidden too. An empty list can mean that search did not find anything close enough. If you miss a particular entry, it is worth checking its tags and the search switches for the entry or its individual Profile fields.

You can explore the public Mistmarch demo Realm without an account. Try searching for “Harbor Archive”, for example. Public reading uses a simpler text search without the language-specific word stems, though. It is not a full comparison with search inside your own Realm.

How the Keeper receives relevant passages

In global search, you look for an entry that you then open yourself. When you ask the Keeper a question about a document, Atlavium finds relevant passages and provides them as the basis for his answer. For a question about rebuilding the Harbor Archive, these may be individual passages from a long chronicle. The Keeper receives those selected passages together with their context in the document.

For this search, Atlavium prepares the document text in smaller passages. Headings and subheadings organize it into coherent sections. Splitting can follow that structure and keep related text together as far as the technical size limits allow. Each passage also retains the sequence of headings it belongs under.

Search considers both the words in the passages and their headings. It selects relevant evidence for the specific question. Along with the passages, the Keeper receives their heading sequence and a reference to the document. His answer is based on that selection. Your saved texts stay unchanged.

Suppose you write a long document titled “The History of the Harbor Archive”. It tells the story of its founding, its first centuries, a great fire and the rebuilding that followed. Part of the outline could look like this:

## The founding years
The first books at the port.

## The first centuries
How the collection grew.

## The great fire
### Saving the records
What could be rescued.

### Rebuilding the archive
New rooms for old books.

## The archive today
The changes since then.

The passage “New rooms for old books” then belongs under “The great fire → Rebuilding the archive”. The sentence itself does not mention the fire. Its headings give search extra clues for finding it when the question concerns the rebuilding. When passages like this are selected, the Keeper receives their context too: they belong to the rebuilding after the fire. That information survives even if the chapter later runs to many pages. You still record the Relationships between the people and places involved in the World Graph.

That is why it helps to use actual headings in the editor, such as “The first centuries” or “Rebuilding after the fire”. Subheadings divide a topic further. A line written only in bold does not count as a heading in this outline. Keep related information together and start a new section when you change the subject. You do not have to turn every note into a reference book.

A long text without headings is still searchable. Without that structure, splitting has to rely mainly on technical size limits. This can separate a connected explanation in the middle of a train of thought. Headings help us form more meaningful sections and avoid those cuts where possible.

The technical limits also apply to a well-structured document. A very long chapter still has to be split into several passages. Its parts remain connected through the outline and associated with their shared section, though. This helps preserve context across necessary splits.

As part of the rework, I removed semantic search from global search. It can find passages through their meaning even when they use different words. To do that, the query first needs to be converted into a form that allows this similarity to be compared. That takes time. When looking up a name in the middle of a game, I want to avoid that extra wait.

For the Keeper, I want to bring vector search back. That is still a plan. A question to him is often longer and needs more context than a single search term. Finding a useful passage with entirely different wording can help there. The extra time remains a drawback that I need to weigh against the benefit.

Passage selection through words and headings already works today. Vector search is planned to add matches through meaning later. Search vocabulary and the saved connections in your current Realm help the Keeper too. He shows relevant sources and makes suggestions. You still decide what becomes Canon.

Concrete examples are the best way for me to learn whether a result list helps in everyday use. What did you enter, and which entry did you expect to find? You can leave quick feedback below the search results. Or come by the Discord and have a chat with me. Especially with search, an example like that helps me more than guessing what other people might look for.