> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ngram.space/llms.txt
> Use this file to discover all available pages before exploring further.

# One Entity, many surfaces

> Understand the boundaries that let identity persist while models, tools, and bodies change.

ngram organizes the system around an **Entity**: a continuing agent with identity, memory, relationships, and runtime state. A conversation is one event in its history.

## The pieces

| Concept                | Owns                                                           | Example                                |
| ---------------------- | -------------------------------------------------------------- | -------------------------------------- |
| **Entity**             | Identity, memory, relationships, and judgment                  | The same Rook in a chat and a headset  |
| **Harness**            | Cognition, scheduling, tool execution, and state management    | The Python runtime                     |
| **Inference provider** | Chat generation and, where supported, embeddings               | Ollama or a hosted API                 |
| **Surface**            | Input and output for a particular environment                  | Telegram, Discord, CLI, WebXR          |
| **Shell**              | Model asset, voice, animation, and body behavior               | A WebXR avatar defined in `shell.yaml` |
| **Binding**            | The connection from a spatial gateway to an agent              | `ngram_entity`                         |
| **Soma**               | Simulated drive bars, affects, and associated internal context | Curiosity, comfort, tension            |

The Entity is the source of identity. A shell can influence presentation without becoming a second identity store.

## What persists

ngram keeps several kinds of state: recent conversation, episodic memories, relationship records, knowledge and journal documents, identity evolution, and body state. They have different retention, retrieval, and consolidation behavior.

Persistence does not mean the entire history appears in every prompt. The runtime selects context, retrieves relevant memories, and compacts working conversation as needed. See [memory](/architecture/memory) and [cognition](/architecture/cognition).

## What a model switch changes

Switching inference changes the backend that produces responses. It does not intentionally create a new Entity or replace its identity and stored state. Models differ in tool use, response style, context handling, and supported request fields.

Embedding compatibility is a separate concern. A new embedding model can produce a different vector space even when its output has the same number of dimensions. Preserve the existing embedding route during a chat-model switch unless you also plan a memory migration.

## What a surface switch changes

A terminal session has text interaction. A messaging surface adds platform-specific delivery and identity. A WebXR surface adds structured spatial context and actions.

For relationship continuity, use the same person mapping when pairing a new surface. A shared Entity runtime does not make every platform's user identifier automatically identical.

## A note on embodiment

ngram uses terms such as drives, affects, inner voice, and dreams for implemented computational mechanisms. These names describe how state influences behavior. They do not establish subjective experience, consciousness, or human-like memory.

<CardGroup cols={2}>
  <Card title="Follow a turn" icon="diagram-project" href="/architecture/overview">See how the runtime assembles a response.</Card>
  <Card title="Explore the spatial boundary" icon="cube" href="/spatial/protocol">See what an agent can send to a body.</Card>
</CardGroup>
