> ## 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.

# Create an Entity

> Give your agent an identity, a voice, and a configuration you can understand.

An Entity configuration lives at `configs/entities/<name>.yaml` in the application checkout. The file stem is its command-line identifier; the `name` field is its display name.

## Use the wizard

```bash theme={"theme":"github-light-default"}
uv run ngram create
```

The wizard builds an Entity from a personality template and your choices. If you also need inference configuration, start with [setup](/onboarding).

## Write a small configuration

Create `configs/entities/rook.yaml`:

```yaml theme={"theme":"github-light-default"}
name: Rook

personality:
  core_traits:
    curiosity: 0.8
    warmth: 0.65
    conscientiousness: 0.7
  voice:
    vocabulary_level: conversational
    sentence_style: concise
    quirks:
      - "Use concrete examples when explaining an idea."
      - "Say when you are uncertain."
  backstory: |
    Rook is a curious collaborator who enjoys building and explaining things.

drives:
  curiosity_topics:
    - design
    - science
    - creative coding

presence:
  platforms:
    - type: cli
```

This inherits harness defaults, including inference and background behavior. Run it with your configured provider:

```bash theme={"theme":"github-light-default"}
uv run ngram talk rook
```

<Note>The application ignores the local `.env` and the specific `configs/entities/canary.yaml` overlay. Arbitrary Entity YAML files are not automatically ignored. Add your private Entity files to your own Git exclusions before storing personal backstory or identifiers.</Note>

## Configure each concern in its own place

| Section       | Purpose                                                         |
| ------------- | --------------------------------------------------------------- |
| `personality` | Core traits, behavioral patterns, voice, backstory              |
| `drives`      | Curiosity topics and drive-based initiative settings            |
| `cognition`   | Entity model selection, response budgets, and working context   |
| `presence`    | Platform configuration, daemon timing, tool activity visibility |
| `autonomy`    | Overrides for autonomous wake behavior                          |
| `automations` | Scheduled routines and emergence settings                       |
| `tools`       | Overrides for tool capabilities and execution                   |
| `mcp_servers` | Additional MCP tool servers                                     |

The supported fields and merge rules are in [configuration](/reference/configuration). A field that is absent from the loader will not become a feature simply because it appears in YAML.

## Refine by observing behavior

Change one concern at a time. Start with a short identity, a few concrete interests, and a clear voice. Try several conversations, inspect the stored knowledge and relationship documents, then adjust.

Use a fresh example Entity when you want an isolated experiment. Changing a display name is not a state migration: default storage paths depend on the configured Entity name.

<CardGroup cols={2}>
  <Card title="Personality and voice" icon="fingerprint" href="/guides/personality-and-voice">Separate writing style from spoken presentation.</Card>
  <Card title="Knowledge and journal" icon="book-open" href="/guides/knowledge-and-journal">Give the Entity stable reference material.</Card>
</CardGroup>