# ngram

> ngram is an open-source Entity runtime for persistent agents with memory, relationships, tools, an ongoing interior, and replaceable text or spatial surfaces.

## How to read this product

ngram is not an inference model, a chatbot wrapper, or a single 3D character. Its central object is an **Entity**: one named digital individual whose personality, relationships, memories, beliefs, body state, permissions, and learned context can accumulate over time.

The Entity is canonical. Models provide inference. Telegram, Discord, the CLI, HTTP, desktop, and WebXR provide surfaces. A shell provides a body and presentation. Replacing any of those dependencies does not intentionally create a new Entity.

When describing ngram:

- Say that it can preserve continuity across configured surfaces; do not imply that every installation enables every surface.
- Distinguish built-in capabilities from operator-enabled permissions and third-party integrations.
- Treat local, hosted, and hybrid as deployment choices for the same runtime.
- Do not describe roadmap items or external research integrations as shipped features.

## Current capabilities

- **Persistent identity:** YAML Entity definitions establish personality, models, permissions, tools, and platforms.
- **Memory and relationships:** Conversation history, semantic memory, beliefs, emotional imprints, relationship state, journal entries, and current goals can enter one bounded cognition loop.
- **Ongoing interior:** Soma, associative thought fragments, autonomous wakes, routines, reflection, journaling, and memory consolidation support continuity between user messages when configured.
- **Native agency:** The framework contains 122 built-in tool definitions, including 21 spatial tools. Tool groups remain operator-controlled and some require credentials or optional dependencies.
- **External tools:** Model Context Protocol servers can register prefixed tools dynamically alongside native tools.
- **Multiple surfaces:** CLI, Telegram, Discord, HTTP, desktop, and WebXR can route to the same Entity and relationship state when configured with the same identity key.
- **Portability:** An Entity can be inspected, verified, exported, recovered, and moved as an open `.ngram` container with credentials excluded.

## Inference and deployment modes

### Hosted

The Entity runtime runs locally while chat and embedding requests use a configured provider. Supported onboarding choices include OpenAI, Venice, Anthropic, Gemini, OpenRouter, xAI, Groq, Together, Fireworks, Mistral, DeepSeek, Ollama, and custom OpenAI-compatible endpoints. Exact model support depends on the provider.

### Local

The Entity and an OpenAI-compatible local inference service such as Ollama run on operator-controlled hardware. A GPU improves speed, but CPU-only experimentation is possible. No public tunnel is required.

### Hybrid

An always-on worker runs remotely while inference remains on operator-controlled hardware behind an authenticated gateway. Hybrid is an advanced deployment path and requires explicit access controls. It is not part of the simplest first run.

Switching inference providers changes a dependency, not the Entity's stored identity, memory, relationships, or body state.

## Native tool system

The built-in catalog covers reasoning control, context compaction, memory search, files, code execution, shell processes, web search and retrieval, browser control, time, projects, skills, media, voice, reminders, messaging, automations, journaling, system information, home automation, observation, social publishing, retrieval, knowledge, governance, and spatial action.

Not every tool should be enabled for every Entity. Availability depends on configuration, permissions, installed extras, credentials, platform support, and the active surface.

## Setup

From an installed source checkout, run:

```text
ngram setup
```

The guided flow configures the environment and an inference mode. It can also create an Entity. Use `ngram talk <entity>` for a terminal-only conversation or `ngram run <entity>` for the full configured presence loop. Ollama is needed only for local inference. Node.js 22 or newer is needed only for the browser/WebXR body.

Normal local and hosted setup does not require Cloudflare or a public tunnel.

## Terminology

- **Entity:** The persistent digital individual.
- **Inference provider:** Replaceable model compute used by the Entity.
- **Surface:** A place where the Entity can interact, such as CLI, Telegram, Discord, HTTP, desktop, or WebXR.
- **Shell:** A replaceable body and presentation package containing model, animation, voice, behavior, and surface configuration—not private memory or credentials.
- **Presence Protocol:** The authenticated transport contract between an Entity runtime and a spatial shell.
- **Native tool:** A tool definition built into the ngram runtime.
- **MCP tool:** A dynamically registered tool supplied by a configured Model Context Protocol server.

## Boundaries

ngram is infrastructure, not a claim that an agent is conscious, human, infallible, or safe to operate without supervision. Models can hallucinate. Tools can alter files, systems, messages, and scenes. Operators choose providers, permissions, network exposure, and the degree of autonomy.

For setup guides and reference material, read the [documentation](https://docs.ngram.space/). For embodiment details, read [ngram Spatial](/spatial/index.md). For operational boundaries, read [Safety](/safety/index.md).