Frequently asked questions

It is an engine that keeps its state in one SQLite file, .umw. You do not write SQL: you record events, Facts and Holdings, and you ask questions such as “does Ana know this, in chapter 6?”.

The file is yours. It works offline and opens on Windows, Linux and macOS.

No. Umwelt never runs or calls a model. Games, novels and tabletop tools use it without any AI.

When you do use a model, Umwelt decides what may enter its prompt (context.admit) and checks what it says (check.utterance).

Retrieval finds text that looks relevant. Umwelt answers who knows it: a record the character never learned is refused however well it matches, a later event never leaks into an earlier scene, and a lie stays a lie the character believes.

Umwelt can also search by meaning, with vectors from your own model, inside those same rules. The two work together: retrieval proposes, Umwelt admits.

Never. Who tells whom, how memory fades, who trusts whom and what a secret costs are your code. Umwelt records the result and reports what follows, including beliefs that contradict canon, which it never corrects.

No. The engine has no network code: it reads and writes one file. The TypeScript client talks to it over standard input and output, and the .NET binding loads it into your own process.

Being present grants nothing. Knowledge needs a Holding whose holder is that person. Use witness to give everyone at a scene the same Holdings in one call.

Yes, and stay wrong. A Holding that contradicts canon is valid: a lie someone believes, a rumor, a mistaken memory. contradictions lists them, and check.utterance tells a held belief from a guess.

Your curve decides how much is lost. holding.adjustBatch records a new confidence or accessibility, and transition.batch with forgotten ends a memory. Reads before the change still see it.

By a Holding of its own. Members knowing something is never the group knowing it: groupCoverage shows which members hold a claim, and whether the group itself does.

Confirmed history is never edited or deleted. Write a new event that retracts or supersedes a record, or work in a draft and promote it only when it is right. Reads at an earlier version still see the old state.

TypeScript (@kallamo/umwelt), .NET 6 and later (Kallamo.Umwelt), the command line, and any language that can start a process and speak the JSON protocol, or load the C library.

On a laptop, asking whether one character knows something takes 55 to 65 µs in a file with 504,040 Holdings, and recording a night of 2,000 conversations takes under half a second.

Semantic search over a large narrator view is slower, and meant for building prompts, not for every frame.

The benchmark town, 40 characters over 3,360 days with 504,040 Holdings, is 397.9 MiB. Vectors for semantic search add to that: 339,421 vectors of 384 dimensions take 665 MiB.

One process owns a .umw file at a time; another gets FILE_LOCKED. Run one umwelt serve or one engine per file and send every request through it.

A free game, mod, interactive fiction or tabletop tool that makes no money may use Umwelt without releasing its code, as long as it credits Umwelt: that is the Free Play Exception.

Donations, pay what you want with a minimum of zero, and game jams still count as free.

Release your project under the AGPL, or buy a commercial license. Development, prototypes and private use need nothing more: a license is needed once the product is publicly released or can earn revenue.