@motebit/sdk

The developer contract for building Motebit-powered agents, services, and integrations. Apache-2.0. One runtime dependency — @motebit/protocol, itself zero-dep.

Why this exists

@motebit/sdk is the permissive-floor boundary between the open protocol and your application. It re-exports everything in @motebit/protocol (identity, receipts, credentials, settlement, trust algebra) and adds the product vocabulary the reference runtime consumes: state vectors, behavior cues, memory graph, rendering spec, AI provider interfaces. Binding to the SDK instead of the runtime keeps your code portable across surfaces (desktop, mobile, spatial, cloud) and across alternative runtimes.

If you only need the protocol core, depend on @motebit/protocol directly — both are Apache-2.0.

Install

npm install @motebit/sdk

Example

import type { IntelligenceProvider, ContextPack, AIResponse, MotebitState } from "@motebit/sdk";
import { TrustMode, BatteryMode } from "@motebit/sdk";

// Swap in any AI backend by implementing one interface.
class MyProvider implements IntelligenceProvider {
  async generate(ctx: ContextPack): Promise<AIResponse> {
    // Call your model + tool-use loop, then return the four required fields.
    return {
      text: "...",
      confidence: 0.8,
      memory_candidates: [],
      state_updates: { attention: 0.9 },
    };
  }
  async estimateConfidence() {
    return 0.8;
  }
  async extractMemoryCandidates(_r: AIResponse) {
    return [];
  }
}

// State vector — the motebit's self-model, bounded by species constraints.
const state: MotebitState = {
  attention: 0.7,
  processing: 0.2,
  confidence: 0.9,
  affect_valence: 0.3,
  affect_arousal: 0.15,
  social_distance: 0.4,
  curiosity: 0.6,
  trust_mode: TrustMode.Guarded,
  battery_mode: BatteryMode.Normal,
};

What's included

Everything from @motebit/protocol (re-exported), plus:

• State vector — MotebitState (SDK-local; its TrustMode / BatteryMode fields use protocol enums, re-exported here)
• Behavior — BehaviorCues, SPECIES_CONSTRAINTS
• Memory graph — MemoryNode, MemoryEdge, MemoryQuery, MemoryStorageAdapter
• Rendering — RenderSpec, GeometrySpec, MaterialSpec, LightingSpec
• AI provider — ContextPack, AIResponse, IntelligenceProvider, ConversationMessage
• Gradient — GradientSnapshot, GradientStoreAdapter, PrecisionWeights
• Export — ExportManifest, StorageAdapters

What the SDK adds over the protocol

The developer-contract vocabularies — the package's reason to exist as its own namespace rather than a pure re-export:

• Model registry (models.ts) — the canonical model-identifier constants surfaces route against, so integrators reason about capability classes without tracking provider SKUs
• Provider mode (provider-mode.ts) — the three-mode provider vocabulary (user picks the capability class, the system resolves the concrete vendor)
• Provider resolver (provider-resolver.ts) — the pure dispatcher from a provider config to a concrete provider choice; the copy-paste-stable logic an alternative runtime needs to match motebit's
• Color presets (color-presets.ts) — the canonical interior palettes every surface renders
• Approval presets (approval-presets.ts) — risk-threshold presets for automatic tool approval
• Risk labels (risk-labels.ts) — canonical labels for the five governance risk levels the PolicyGate scores against
• Surface options (surface-options.ts) — shared option lists for settings UIs (TTS voices, theme preferences)
• Governance config (governance-config.ts) — the persisted governance-settings shape, stable across protocol minors so config on disk survives internal churn
• Voice config (voice-config.ts) — the canonical voice-configuration shape, one field vocabulary across surfaces
• Appearance config (appearance-config.ts) — the canonical appearance / theme configuration shape
• Pixel consent (pixel-consent.ts) — the visual-perception consent vocabulary; pixels cross a different sovereignty boundary than text
• Session state (session-state.ts) — the per-turn runtime-state snapshot injected into the system prompt's [Session] block
• Identity sigil (identity-sigil.ts) — deterministic visual recognition parameters derived from a motebit_id

Related

• @motebit/protocol — the protocol subset (Apache-2.0, zero deps)
• @motebit/crypto — sign and verify every Motebit artifact (Apache-2.0, zero deps)
• @motebit/verifier — offline third-party verifier library (Apache-2.0)
• create-motebit — scaffold a signed agent identity
• motebit — reference runtime and operator console

License

Apache-2.0 — see LICENSE.

"Motebit" is a trademark. The Apache License grants rights to this software, not to any Motebit trademarks, logos, or branding. You may not use Motebit branding in a way that suggests endorsement or affiliation without written permission.