Create an Entity

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

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.

Write a small configuration

Create configs/entities/rook.yaml:

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:

uv run ngram talk rook

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.

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

Personality and voice

Separate writing style from spoken presentation.

Knowledge and journal

Give the Entity stable reference material.

Getting started

Entities

Surfaces

Explore

Create an Entity

Use the wizard

Write a small configuration

Configure each concern in its own place

Refine by observing behavior

Personality and voice

Knowledge and journal

​Use the wizard

​Write a small configuration

​Configure each concern in its own place

​Refine by observing behavior

Personality and voice

Knowledge and journal

Use the wizard

Write a small configuration

Configure each concern in its own place

Refine by observing behavior