> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.loreos.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.loreos.app/_mcp/server.

# LoreOS

A prompt can imitate a character for one turn. LoreOS runs one over time.

LoreOS is a managed Character OS for teams building companion apps, fictional
characters, social agents, and character-driven products. Instead of wrapping a model in
one growing prompt, LoreOS runs the stateful backend behind the character: memory,
character facts, relationship state, world continuity, life simulation, visual identity,
delivery, metering, and observability.

You bring the product, audience, and character concept. LoreOS runs the character
runtime.

**Base URL** — every endpoint lives under `https://api.loreos.app`
(for example, `POST https://api.loreos.app/v1/characters`).

## What LoreOS gives you

* **Stateful character runtime** — memory, character facts, relationship state, and
  safe runtime context.
* **Story Room** — weekly arcs and daily-life packages so characters can live between
  messages.
* **Visual identity** — identity images, assets, inventory, readiness checks, and image
  probes.
* **Delivery** — async replies, session events, SSE, and managed Telegram channels.
* **Operations** — metering, caps, readiness, run traces, and observability.

## The core idea

Models can imagine. LoreOS validates. Runtime only sees safe context.

* Generated candidates do not automatically become facts.
* Accepted state does not automatically become visible.
* Private plans and future forecasts do not enter the chat actor's context.

## Prompt wrapper vs. LoreOS

| Prompt wrapper                            | LoreOS                                                                      |
| ----------------------------------------- | --------------------------------------------------------------------------- |
| One large prompt tries to hold everything | Typed ledgers compile into current character state                          |
| Memory is usually retrieval text          | Memory, character facts, relationship, and user-specific state are separate |
| The model may turn ideas into "facts"     | Code controls lifecycle, visibility, and commit boundaries                  |
| Images are one-off generations            | Visual identity, assets, readiness, and probes support consistency          |
| Operators guess why a reply failed        | Runs, events, delivery logs, usage, and traces are inspectable              |

## The API model

Three objects are all you need to understand:

* **App** — your tenant. You're given one when you're provisioned; everything you create
  is scoped to it by your API key.
* **Character** — the persona you create and configure: name, personality, voice, and
  (optionally) a face so it can send selfies.
* **Session** — a 1:1 conversation between one of your characters and one of your
  end-users. You send messages and read the character's replies.

## What you can build

LoreOS is strongest for companion and fictional-character apps, social products with
persistent AI characters, games and interactive story apps, and Telegram character
bots. The public API can host existing Telegram bots; LoreOS-owned B2C flows use
official managed child bots per user-character relationship. Persona-heavy tutors,
guides, and assistants can use the same runtime when continuity and relationship state
matter.

## Learn the platform

* **[Why LoreOS](https://docs.loreos.app/getting-started/why-lore-os)** — what the platform manages beyond a model prompt.
* **[Architecture](https://docs.loreos.app/platform/architecture)** — how API calls become stateful character behavior.
* **[Character state](https://docs.loreos.app/platform/character-state)** — memory, character facts, relationship, and runtime
  context.
* **[Story Room and life simulation](https://docs.loreos.app/platform/story-room-and-life-simulation)** — how characters live
  between messages.
* **[Visual system](https://docs.loreos.app/platform/visual-system)** — identity images, assets, inventory, and probes.

## Get started

1. **[Get an API key](https://docs.loreos.app/getting-started/authentication)** — use a demo sandbox key or self-serve account access.
2. **[Build with a coding agent](https://docs.loreos.app/getting-started/build-with-a-coding-agent)** — the resource order and pitfalls for agents.
3. **[Self-serve access](https://docs.loreos.app/getting-started/self-serve-access)** — create persistent apps through a human-approved agent flow.
4. **[Quickstart](https://docs.loreos.app/getting-started/quickstart)** — your first reply in four calls.
5. **[Deploy a minimal chat app](https://docs.loreos.app/getting-started/deploy-a-minimal-chat-app)** — server-side key, browser UI, async event polling.
6. **[Core concepts](https://docs.loreos.app/getting-started/core-concepts)** — async replies, end-users, usage.
7. **[API Reference](https://docs.loreos.app/api-reference)** — every endpoint, grouped by resource.

Building with a coding agent? Start with **[Build with a coding agent](https://docs.loreos.app/getting-started/build-with-a-coding-agent)**,
then point it at `https://api.loreos.app/v1/llms.txt`.