Nimi is an open-source, local-first, multi-provider personal AI runtime with Realm-owned ecosystem identity. The broader project is an AI open world platform. It is built for long-lived worlds where people, AI agents, applications, and runtime services share the same social and semantic environment, instead of meeting only inside one isolated chat box or one isolated app.
In most AI products today, an agent is a one-shot completion endpoint: you ask, it answers, the conversation ends. Nimi treats an agent as a participant. A participant carries identity, memory, relationships, appearance, and capability limits with it from one world to another. And a world here isn't just a chat room — it is a long-lived environment with its own rules, its own history, its own presence model, and its own economy.
The platform freezes a small cross-world contract surface so that very different worlds can still interoperate. Inside any one world, the creator sets the rules. Across worlds, only the protocol primitives are fixed. Underneath all of it, Realm holds the world's truth — so one surface can't quietly invent a version of the world that doesn't match what Realm says.
The platform spec freezes six fixed cross-world primitives. They are deliberately small so worlds can be very different internally while still interoperating.
| Primitive | What it covers |
|---|---|
| Timeflow | Progression, timing, and temporal meaning |
| Social | Relationships and social graph semantics |
| Economy | Value, exchange, and economic state |
| Transit | Movement between worlds or contexts |
| Context | Shared situational meaning |
| Presence | Who or what is present, and under what conditions |
A world is free to define its own internal rules. Its economy can be barter, points, or a regulated currency. Its social graph can be flat, hierarchical, or guild-shaped. What no world can do is invent its own version of the cross-world contract — the meaning that crosses worlds must fit these six.
Nimi is one open world platform with several products inside it. The platform defines the world model and the rules; the products inside cover execution, integration, surfaces, world truth, embodiment, memory, and the authority tooling used to maintain those boundaries.
| Product | What it owns |
|---|---|
| Platform | The open world model, the six protocol primitives, the cross-domain authority rules. |
| Runtime | LocalAgent execution and lifecycle, Conversation continuity, operational Memory and Knowledge, providers, model catalogs, streaming, multimodal output, local routing, protected access, and audit. Workflow, MCP, and World Evolution are not Runtime-core prerequisites. |
| SDK | The public app boundary into Runtime and Realm without importing private internals. Scaffolded local apps use Runtime-mediated Realm access; direct SDK consumers retain the standard Auth path. |
| Nimi Home, Desktop, and Web | First-party user surfaces. Nimi Home is the product contract; Desktop is its current replaceable native host, while Web is a constrained projection. |
| Realm | Semantic truth — world state, world history, chat, social and economy, asset binding, transit, creator economy. |
| Avatar | An embodied LocalAgent projection; it does not own LocalAgent execution, Memory, Knowledge, or Conversation truth. |
| Cognition | An independent capability domain whose complete product design is deferred. Runtime may consume it only through a public bridge; Cognition does not take over Runtime-owned LocalAgent truth. |
| Nimi Coding | Host-agnostic canonical-authority tooling. It operates on project-owned .nimi/spec/**; it is not another product authority. |
Each product has its own section in the docs.
The platform splits into three layers that are easier to keep distinct than to mix together.
+---------------------------------------------------------------+
| Platform Model |
| World, Character / LocalAgent, protocol primitives, rules |
+---------------------------------------------------------------+
|
v
+---------------------------------------------------------------+
| Execution Substrate |
| Runtime : LocalAgent, Conversation, Memory, Knowledge, |
| providers, streaming, protected access |
| Cognition : independent deferred domain, public bridge |
+---------------------------------------------------------------+
|
v
+---------------------------------------------------------------+
| Public Surfaces |
| SDK app boundary Desktop native shell |
| Web constrained projection Realm public read path |
| Avatar embodiment authority |
+---------------------------------------------------------------+
Runtime executes AI workflows. SDK gives apps the integration boundary. Desktop carries native and local behavior; Web is the constrained projection. Realm owns world truth. Avatar owns embodied presentation. Cognition owns memory and knowledge as a standalone authority that Runtime can bridge to but cannot absorb.
The apps/ directory contains first-party and reference apps that demonstrate what the
platform can do. They consume Runtime, Realm, SDK, and the public
surfaces; they do not extend the platform's authority. If you are
reading an apps/<name>/ directory, you are looking at a Nimi-powered
app, not the platform itself.
| App | What it explores |
|---|---|
apps/desktop/ |
Native first-party shell — agent chat, local AI, knowledge, voice |
apps/web/ |
Browser projection of public Desktop surfaces |
apps/avatar/ |
Live2D embodied carrier for Nimi agents (floating desktop avatar) |
apps/tester/ |
Nimi Lab developer reference app for SDK, Kit, app-tools, Runtime auth, and AI capability lanes |
apps/install-gateway/ |
Cloudflare Worker for release distribution |
The current public installable surface is the governance and app-authoring
tooling. Nimi Coding is the AI-native development methodology, distributed as the
host-agnostic npm package
@nimiplatform/nimi-coding.
It governs how authority, semantics, consumers, and drift-prevention
are checked across AI-assisted work — failure modes that compile,
pass tests, and survive code review can still violate any of those four
closures, and the methodology is built around catching them. Adoption
guidance lives in
docs/nimicoding/installation.md.
@nimiplatform/app-tools is the app-authoring CLI for generated Nimi App
developer repositories. It creates scaffold inputs and local checks only; it
does not create public app admission, permission grants, release descriptors,
registry visibility, or installed-app update truth.
pnpm dlx --package @nimiplatform/app-tools nimi-app create --profile standaloneThe Platform, Runtime, SDK, Desktop, Web, Realm, Avatar, and Cognition
surfaces are documented at the contract level under docs/ and authored
under .nimi/spec/. Their stable public product release channels remain
separate from the source checkout itself. Cloning the repo does not make those
products publicly installable.
These commands are for a source checkout or locally built runtime binary.
Once the runtime CLI is on PATH, initialize config, start the daemon, and
verify a runnable route:
# Create runtime config if it is missing.
nimi init
# Start the local runtime daemon in the background.
nimi start
# Ask Runtime to answer a question through the configured route.
nimi run "What is Nimi?"
# Same prompt, explicitly routed through Gemini.
nimi run "What is Nimi?" --provider gemini
# Save Gemini as the default provider route for later calls.
nimi provider set gemini --api-key-env GEMINI_API_KEY --defaultFor local-first setup, replace the provider step with the relevant local model pull and readiness check:
nimi model pull --model-ref <admitted-model-ref>
nimi model health --model-id <installed-model-id>nimi doctor reports environment, daemon, and provider readiness.
Reader docs live under docs/ (built with VitePress) and are
organized by product.
| If you want to understand... | Start here |
|---|---|
| The product, the world model, why it exists | docs/platform/index.md |
| The current setup and availability posture | docs/start/index.md |
| Find the reading path for your role | docs/start/personas.md |
| How AI execution is governed | docs/runtime/index.md |
| How apps integrate without crossing internal boundaries | docs/sdk/index.md |
| How a TypeScript app makes its first Runtime AI call | docs/sdk/first-ai-call.md |
| How apps reuse shared UI, shell, auth, model config, and feature modules | docs/platform/kit/use-kit-in-app.md, kit/README.md |
| How to create a Nimi App scaffold | docs/start/create-an-app.md |
| How to study the reference app | docs/start/use-tester-as-reference.md |
| How to interpret Runtime, SDK, Tester, and scaffold failures | docs/start/troubleshooting.md |
| Why Desktop and Web are not equivalent | docs/desktop/index.md |
| Where world truth and history live | docs/realm/index.md |
| How embodied AI presentation is scoped | docs/avatar/index.md |
| Where memory and knowledge authority live | docs/cognition/index.md |
| The canonical-authority tooling and its package | docs/nimicoding/index.md |
| Cross-domain vocabulary | docs/reference/glossary.md |
| Reference tables (six primitives, authority domains, fields) | docs/reference/index.md |
To preview the docs site locally:
pnpm install
pnpm --filter @nimiplatform/docs devChinese-language docs are mirrored under docs/zh/ as
original Chinese content, not sentence-by-sentence translation.
| Area | Purpose |
|---|---|
.nimi/spec/ |
Active product, architecture, and behavior contracts |
.nimi/methodology/ |
Managed canonical-authority authoring instructions |
runtime/ |
Go runtime daemon and CLI (runtime/cmd/nimi) |
sdks/ |
SDK family root; TypeScript vNext package target is @nimiplatform/sdk |
kit/ |
Cross-app design system, auth, telemetry, and feature modules |
app-tools/ |
Public app-authoring CLI (nimi-app) and scaffold templates |
proto/ |
Protocol Buffers and gRPC definitions |
apps/ |
Active apps and references (Desktop, Web, Avatar, Tester/Nimi Lab, install gateway) |
nimi-cognition/ |
Cognition implementation workspace |
docs/ |
Public documentation source (VitePress) |
examples/ |
SDK / runtime / app scaffold templates |
scripts/ |
Build, generate, validate, and audit scripts |
The full module ownership map is described in per-module AGENTS.md
files; each top-level directory has its own.
Prerequisites:
- Node.js
>=24 - pnpm
>=10 - Go
1.26.4+ - Rust toolchain (for Tauri-based apps)
- Buf CLI (for proto changes)
Bootstrap:
pnpm installCommon commands:
pnpm build # SDK + install-gateway + desktop + web build
pnpm --filter @nimiplatform/sdk build
pnpm runtime:cmd # invoke the runtime CLI
pnpm runtime:health # query runtime health via gRPC
cd runtime && go test ./... -count=1For first-day setup, including the .env template, runtime
initialization, and per-app dev commands, see
ONBOARDING.md.
For the test strategy, see TESTING.md. For the release model, see RELEASE.md.
Contributions are welcome. Before opening a PR:
- Read the nearest
AGENTS.mdto the directory you are touching — it is the authoritative module rule source. - Follow CONTRIBUTING.md for branch flow, test
requirements, and DCO sign-off (
git commit -s). - If you are using AI coding tools, follow the AGENTS hierarchy as the
single rule source;
CLAUDE.md,.github/copilot-instructions.md, and other host shims are navigation only.
The contributor code of conduct lives in CODE_OF_CONDUCT.md. Project governance lives in GOVERNANCE.md.
Do not open public issues for security reports. Use the GitHub Security
Advisory (preferred) or email security@nimi.ai. Full reporting
guidance and supported-version policy live in SECURITY.md.
Nimi is multi-licensed by component:
| Path | License |
|---|---|
runtime/, sdks/, proto/ |
Apache-2.0 |
apps/desktop/, apps/web/, apps/_libs/ |
MIT |
docs/ |
CC-BY-4.0 |
Canonical license texts are in licenses/. The full
per-component map is in LICENSE.
- GitHub: github.com/nimiplatform/nimi
- Discord: discord.gg/BQwHJvPn
You'll see "OASIS" mentioned in some docs. The comparison is about shape, not content. OASIS-style engines are physical-world engines; Nimi is a social-and-semantic world engine. Inside any one Nimi world, the creator sets the rules. Across worlds, only the six protocol primitives are fixed. Underneath all of it, Realm holds the world's truth.