AI coding agent runtime. A library that hosts embed to get an AI coding agent — loop, tools, compaction, memory, LLM routing.
v0.1.0 — Phase 1 freeze (2026-04-21). Public contracts are additive-only from here. Breaking shape changes require MAJOR bump and 4-week advance notice (see CHANGELOG.md).
naia-agent relates to its companion repos through published interfaces, not through runtime dependencies.
- Transparent: every interface is specified in
@nextain/agent-types, documented, and versioned — open for anyone to read or implement. - Non-binding: companion repos (
naia-adk,alpha-memory, hosts) do not importnaia-agent. They implement the contracts.naia-agentdoesn't import them either — it receives concrete implementations via dependency injection. - Abstracted: the runtime knows nothing about which LLM provider, which memory backend, or which skill source is in use. Swap any of them and nothing else changes.
This is Ports & Adapters (hexagonal) architecture applied at the ecosystem scale. Each repo is independently replaceable as long as it honors the contract.
defines contracts
┌──────────────────────────────────────────┐
│ @nextain/agent-types (published, public) │
│ LLMClient · MemoryProvider · │
│ SkillLoader · ToolExecutor · ... │
└───────┬─────────────────┬────────────────┘
│ imports only │ imports only
│ types │ types
┌───────▼──────┐ ┌─────▼──────────┐
│ naia-adk │ │ alpha-memory │ implementations
│ (Skill │ │ (MemoryProvider│ (no runtime dep
│ source) │ │ impl) │ on naia-agent)
└──────────────┘ └────────────────┘
┌─────────────────────────────────────────────┐
│ Host (naia-os, CLI, server, 3rd-party app) │
│ · constructs concrete implementations │
│ · injects them into naia-agent runtime │
└─────────────────────────────────────────────┘
- What it is: Tauri-based desktop app + Bazzite Linux OS image.
- What it owns: UI, 3D VRM avatar, user-facing settings, OS-level integration (file picker, notifications, OAuth stronghold), API-key storage, device identity, approval UI.
- Relationship to naia-agent: Host — constructs
LLMClient,MemoryProvider, and other concrete implementations, injects them intonaia-agentat startup. - Independence: naia-agent can run without naia-os (e.g., inside a CLI or server host). naia-os can in theory swap to a different runtime as long as that runtime speaks the same stdio protocol.
- What it is: Agent loop, tool dispatch, context management, compaction, skill execution.
- What it owns: the
@nextain/agent-typescontracts and a reference implementation that reads them. - Relationship to others: consumer of contracts — calls out through interfaces only. Does not import
naia-adkoralpha-memoryruntime code. Does not know about providers, storage backends, or UIs directly. - Independence: naia-agent runs anywhere Node.js runs. Its dependencies are the interfaces it publishes, nothing else.
- What it is: a tool-agnostic workspace format (directory layout, context files, skill definitions). Read by any AI coding tool — Claude Code, OpenCode, Codex, naia-agent, future tools.
- What it owns:
.agents//.users/directory conventions,agents-rules.jsonschema, SKILL.md format, fork chain (naia-adk→naia-business-adk→{org}-adk→{user}-adk). - Relationship to naia-agent: format consumed. naia-agent loads skills by reading the naia-adk format. naia-adk does not depend on naia-agent.
- Independence: you can use naia-adk with Claude Code only, OpenCode only, or any mix — no runtime commitment.
- What it is: a memory system (episodic, semantic, procedural) with importance filtering, knowledge graph extraction, and time-based decay.
- What it owns: its own storage schema, 4-store architecture, pluggable vector backends.
- Relationship to naia-agent: one implementation of
MemoryProvider. naia-agent treats it as a black box behind the interface. Another memory system could replace it by implementing the same interface. - Independence: alpha-memory is published as
@nextain/alpha-memoryand can be used by anything, not just naia-agent.
Runtime concerns (loop, tools) are separated from I/O concerns (network, UI) by layer:
[L1] Host naia-os / CLI / server
Process, I/O, dependency injection ↑ embeds
─────────────────────────────────────────────────────────────────────
[L2] Agent (this repo) naia-agent
Loop · tools · compaction · hot memory ↓ calls
─────────────────────────────────────────────────────────────────────
[L3] LLM Client LLMClient interface (+ adapters)
Concrete: Gateway / Direct / Mock ↓ HTTP
─────────────────────────────────────────────────────────────────────
[L4] Routing Gateway any-llm or equivalent
Provider selection · fallback · auth ↓
─────────────────────────────────────────────────────────────────────
[L5] Providers Anthropic / OpenAI / Google / local models
The agent depends only on the injected LLMClient interface — it has no knowledge of which provider, which gateway, or which network protocol carries the call.
Every contract lives in a single zero-runtime package. Anyone can implement:
The only way naia-agent talks to language models. Implementations wrap providers directly (Anthropic/OpenAI/…), a gateway (any-llm), or a mock (tests). Streams, tool-calls, and prompt caching are all part of the contract.
Long-term memory and session logs. alpha-memory is the reference implementation. Others can implement the same interface — local JSON, SQLite, remote vector DBs, custom stores.
Reads skill definitions from a workspace (naia-adk format today, extensible to others). Produces SkillDescriptor objects the runtime can dispatch.
Runs individual tool calls (file I/O, command exec, network, MCP proxies). Implementations enforce tier policies (T0–T3) and approval flows.
Session, Conversation, Message, ToolCall, ToolResult, Event, CompactionPolicy, TokenBudget, TierLevel, ApprovalRequest. Stable across implementations.
All contracts are published open-source. No hidden extension points, no private ABIs.
- naia-os — Tauri desktop app (flagship reference host)
- CLI — peer to
claude-code,opencode,codex - HTTP server — for remote / browser / mobile clients
- Third-party apps — anyone building an AI coding product
All hosts consume the same naia-agent runtime, so behavior is consistent regardless of surface.
Published contracts (additive-only from here):
-
@nextain/agent-types0.1.0 — LLMClient / MemoryProvider / ToolExecutor / ApprovalBroker / HostContext / Event / ErrorEvent / VoiceEvent / Logger / Tracer / Meter / TierLevel / SessionLifecycle -
@nextain/agent-protocol0.1.0 — StdioFrame wire format -
@naia-adk/skill-spec0.1.0 — SkillDescriptor / SkillLoader (in naia-adk repo) -
@nextain/agent-providers0.1.0 — AnthropicClient -
@nextain/agent-observability0.1.0 — ConsoleLogger / NoopTracer / InMemoryMeter -
@nextain/agent-core0.1.0 — contracts re-export (runtime loop WIP)
Phase 2 (next):
- Core loop skeleton (Strangler Fig X3)
- Tool execution runtime (X2)
- Compaction
- Skill loader (reads naia-adk workspace) (X4)
- MCP bridge (X4, continuation of #200)
- stdio protocol flip-day (X5)
- Reference host: embedded in naia-os (X1 providers already available)
- CLI host
- Messengers (X8)
pnpm install
pnpm buildWorkspace layout:
naia-agent/
├── packages/
│ ├── types/ # @nextain/agent-types — contracts
│ ├── protocol/ # @nextain/agent-protocol — wire format
│ ├── core/ # @nextain/agent-core — runtime scaffold
│ ├── providers/ # @nextain/agent-providers — AnthropicClient
│ └── observability/ # @nextain/agent-observability — defaults
├── scripts/smoke-anthropic.ts
├── package.json # pnpm workspace root
└── tsconfig.json # TypeScript project references
See Issues for early design discussion.
- Not in
naia-os—naia-osis frontend + OS distribution. A separate runtime lets other hosts (CLI, server, 3rd-party apps) reuse the same engine. - Not in
naia-adk—naia-adkis a workspace format, analogous to a git repo or an npm package: static, portable, tool-agnostic. A runtime is the opposite: stateful, process-bound. Mixing them conflates "what the agent works on" with "what runs the agent." - Not a fork of
claude-code/opencode— those are full CLI products.naia-agentis a library designed to be embedded, not a standalone binary.
Apache License 2.0. See LICENSE.
Copyright 2026 Nextain Inc.
- Naia OS — github.com/nextain/naia-os
- Naia ADK — github.com/nextain/naia-adk
- Alpha Memory — github.com/nextain/alpha-memory
- Nextain — nextain.io