Your first Entity

Start in a terminal. You can add messaging and a spatial body once your Entity can respond.

Before you begin

You need Python 3.11+, Git, and uv. Choose one inference route:

Route	You need	Where the Entity runs
Hosted API	A supported provider account and API key	Your computer
Local Ollama	Ollama and hardware that can run your model	Your computer

Hosted inference does not require a local GPU. Node.js and a headset are optional until you add spatial presence.

Get the runtime

git clone https://github.com/ngramspatial/ngram.git
cd ngram
uv sync --extra dev
uv run ngram --help

The help output confirms the command is installed. While the application repository is private, your GitHub account needs access to clone it.

Create and configure your Entity

Hosted API
Local Ollama

uv run ngram setup --profile hosted

Name your Entity, choose your provider and chat model, and supply the API key at the prompt. The wizard configures the local .env and Entity YAML.Memory also needs embeddings. Use the wizard’s provider defaults where available; if your chat provider does not serve embeddings, configure the separate embedding route it offers.

uv run ngram setup --profile local

The repository defaults are gemma4:26b for chat and nomic-embed-text for embeddings. Choose a model your hardware can run. Pull the selected models if they are not installed:

ollama pull gemma4:26b
ollama pull nomic-embed-text

Start a conversation

Run the exact command the wizard prints. If you named your Entity rook:

uv run ngram talk rook

uv run ngram talk rook --ollama

Ask a concrete question. A successful first run reaches the terminal conversation and returns a reply without provider or embedding errors.

What you just created

The Entity’s YAML defines its identity and behavior. Its runtime stores memory and state separately from the source code. The default local state lives under ~/.ngram/entities/; an explicit execution workspace or portable container can change those paths. Inspect the configured Entity:

uv run ngram status rook

The command argument selects the YAML file stem. For configs/entities/rook.yaml, use rook, even if the display name inside the file differs.

Keep it running

talk is a terminal conversation. run starts the daemon and configured surfaces:

uv run ngram run rook

For local inference, add --ollama. Background work can call your inference provider while you are not chatting. Read usage and stop controls before leaving a hosted Entity running. Stop a foreground run with Ctrl+C. Exit the terminal conversation when you finish. State persists; stopping the process does not wipe the Entity.

Give it a body

Connect the same Entity to a browser or headset.

Make it yours

Edit identity, voice, tools, and platforms.

If the first reply fails, start with troubleshooting. Do not change your memory database to work around an inference error.

Getting started

Entities

Surfaces

Explore

Your first Entity

Before you begin

What you just created

Keep it running

Give it a body

Make it yours

​Before you begin

​What you just created

​Keep it running

Give it a body

Make it yours

Before you begin

What you just created

Keep it running