open source
ngram is open infrastructure for bringing persistent AI agents out of chat windows and into spatial reality.
One ngram carries its memory, relationships, tools, judgment, and inner life from software into the room
around you.
Run locally, use a frontier API,
or connect both.
git clone https://github.com/ngramspatial/ngram.git
cd ngram
ngram setupA persistent digital being built to exist beyond the screen.
An ngram is one digital individual with memory, relationships, personality, tools,
goals, and a history that accumulates over time.
You give it a beginning: a personality, voice, drives, capabilities, and boundaries. Experience shapes
what comes next: memories, habits, beliefs, relationships, private reflections, and an evolving identity.
It can talk with you through software, act with tools, and enter spatial environments through XR while preserving the continuity it has built over time.
An ngram can reflect, journal, consolidate memories, maintain routines, and carry unfinished
thoughts forward.
Conversations become experiences it can remember rather than isolated sessions. Over time, those
experiences can shape its beliefs, relationships, habits, and behavior.
Give an ngram tools and it can search, browse, work with files, run code, speak, create, send
messages, use software, and interact with spatial environments.
You choose what it can access and what it is allowed to do. Its memory, relationships, goals, and
context inform how it acts.
Run it through a frontier model, a local model, or something that does not exist yet. Change its
machine, interface, voice, intelligence provider, or 3D body. Those are replaceable parts.
Its accumulated identity, memory, relationships, and history are what persist.
AGENCY
ngram ships with 122 native tools, including 21 built specifically for spatial environments.
They let an ngram search, build, remember, communicate, automate, observe, move, and interact with the environments around it.
Enable only the capabilities you want it to have. Extend it further through MCP whenever it needs something new.
Search the web, retrieve information, read documents, and work with files.
Use websites, terminals, workspaces, Python, JavaScript, and other software.
Speak, listen, transcribe, search media, and communicate beyond text.
Keep routines, schedule actions, set reminders, and act over time.
Remember experiences, maintain a private journal, and build structured knowledge.
Reach people through connected platforms like Telegram and Discord.
REPLACEABLE INTELLIGENCE
inference options
the constant underneath
.ngram container.
The CLI wizard ngram setup walks you through environment,
inference, and an optional hybrid deployment. Here is the happy path in
order — skip anything you do not need yet.
Download ngram and open a terminal at the project root. The branded setup flow checks the environment and guides optional components. Ollama is needed only for fully local inference; Node.js is needed only for a browser body.
ngram setup
Creates or updates a git-ignored .env. Choose hosted for the fastest
start, local for Ollama on this machine, or hybrid for a home
gateway plus an always-on worker. Cloudflare is not part of normal first-run setup.
Use the built-in entity step or run ngram create. You get a YAML under
configs/entities/ — personality, models, tools, and platforms live there.
Add Telegram or Discord under presence.platforms in
your entity YAML; put bot tokens in .env to match token_env. For
hybrid workers, use durable S3-compatible attachment storage so photos survive
redeploys.
ngram talk <entity> starts a terminal session.
ngram run <entity> starts the configured chat surfaces and autonomous
heartbeat. Add a body later without creating a second ngram.
open commons
Open source by design. Read the runtime, inspect the Entity format, build a body, and keep control of the infrastructure that carries your relationships and memory.
pillars
ngram is open source: read the code, run it as-is, fork it for experiments, and self-host without asking permission. Bugs, ideas, and trade-offs stay visible; deployment and privacy boundaries stay explicit.
Quick answers about running ngram locally, memory, platforms, tools, and how the pieces fit together.
Entitative is our shorthand for entity-first: the system is organized around a single, named digital self you configure (persona, channels, tools, data paths) — not around anonymous chat threads or a grab-bag of unrelated tasks. The word grows out of entity: one coherent subject the runtime keeps alive over days and weeks.
In practice that means memory, habits, and voice accumulate for that ngram across sessions and surfaces (CLI, Telegram, Discord, etc.). You are not “starting fresh” every time by default; you are continuing the same presence, with resets and tools available when you intend to use them. ngram’s YAML entities, storage layout, and presence loop are all shaped around that idea.
It is a design stance, not a buzzword: many tools optimize for stateless or disposable conversations. We optimize for a persistent self you own — an agent that experiences the world alongside you — while keeping real engineering choices underneath: local inference, your disks, your rules, hybrid mode, gateways, and optional APIs.
Neither is mandatory. Hosted mode needs a provider credential but no local GPU. Local mode uses Ollama and can run on CPU for experiments, though a suitable GPU improves speed. Both paths run the same Entity runtime.
Start with Python 3.11+, then run ngram setup for guided checks.
Add Ollama only for local inference, and Node.js 22+ only when you build or run the WebXR body.
Hosted setup can begin without local model infrastructure.
Run ngram setup. The guided flow works with .env.example and
configs/default.yaml (see
deployment and inference sections) to
wire your environment.
Hybrid keeps the brain at home behind your gateway and tunnel while an always-on worker can run on a host such as Railway with Postgres — so you get persistence and reachability without sending inference to a third-party API by default.
ngram talk and ngram run?
ngram talk <entity> starts a terminal-only conversation:
no background daemon and no Telegram, Discord, or other configured platforms.
It is ideal for quick tests and debugging.
ngram run <entity> starts the full presence loop: the
daemon plus every platform listed under presence.platforms in your entity YAML (and
an optional CLI REPL if you enabled CLI there).
/reset delete my ngram’s long-term memory?
No. Platform commands like /reset clear rolling chat
turns for the session — they do not wipe episodic memory, beliefs,
relationships, or other data in the database.
A full experiential wipe is intentional and host-side:
ngram wipe <entity> --yes (see the readme). Always back up first if you are
unsure.
By default each ngram uses a SQLite file under your ngram data path
(see memory.database_path in runtime defaults). When DATABASE_URL or
memory.database_url is set — typical for a hybrid worker on Postgres
— the runtime uses that instead.
Native tools are built into the runtime (web search, scoped filesystem access,
automations, messaging helpers, optional browser/voice stacks, and more). You toggle groups in
configs/default.yaml; heavier stacks often need a pip extra such as
ngram[full] when you enable them.
MCP
lets you attach stdio servers in entity config so tools appear at runtime with
prefixed names, alongside native ones. Both paths are documented in the readme
and configs/entities/example.yaml.
Add a telegram or discord entry under
presence.platforms in your entity YAML. Tokens come from environment variables named by
token_env (commonly TELEGRAM_TOKEN / DISCORD_TOKEN in
.env).
You can restrict who may talk to the bot with optional allowlists
(allowed_user_ids, allowed_chat_ids on Telegram). Start the ngram with
ngram run so those platforms connect.
In local mode, images and audio from chats are written to a disk folder under your user data path. On ephemeral cloud disks (e.g. a Railway worker), those files would disappear on redeploy.
Set NGRAM_ATTACHMENTS_BACKEND=object_s3_compat and the
NGRAM_S3_* variables so blobs land in object storage (any
S3-compatible API). ngram setup can prompt for this on the hybrid path.
knowledge.md?
Each ngram can have a knowledge file you edit on disk. Sections marked
[locked] are yours only; unlocked sections can be updated by the ngram over time.
Use ngram knowledge <entity> to create or open it in your editor.
ngram does not require paid web APIs. If you add a
Firecrawl API key, the runtime can prefer it for richer fetch_url /
search_web behavior when configured — entirely optional.
ngram is open source under the MIT License — usable for personal and commercial projects, subject to that license’s terms.
Read the documentation for setup guides and reference material. Use the repository's Discussions area for community questions and Issues for reproducible bugs.