@mubit-ai/sdk

Canonical JavaScript SDK for MuBit.

Install

npm install @mubit-ai/sdk

Quickstart

import { Client } from "@mubit-ai/sdk";

const client = new Client({
  transport: process.env.MUBIT_TRANSPORT ?? "auto",
  run_id: "sdk-js-demo",
  api_key: process.env.MUBIT_API_KEY,
});

await client.remember({
  session_id: "sdk-js-demo",
  agent_id: "sdk-quickstart",
  content: "Cache invalidation failures usually show up after stale token reuse.",
  intent: "lesson",
  lesson_type: "failure",
  lesson_scope: "session",
  metadata: { source: "readme" },
});

const answer = await client.recall({
  session_id: "sdk-js-demo",
  query: "What should I watch for before retrying auth?",
  entry_types: ["lesson", "rule"],
});
console.log(answer.final_answer, answer.evidence?.length ?? 0);

Surface Model

• Low-level raw APIs remain available on client.auth.*, client.core.*, and client.control.*.
• High-level helper APIs live on Client:
  • remember
  • recall
  • getContext
  • archive
  • archiveBlock
  • dereference
  • memoryHealth
  • diagnose
  • reflect
  • forget
  • checkpoint
  • registerAgent
  • listAgents
  • recordOutcome
  • surfaceStrategies
  • handoff
  • feedback
• Helper APIs use session_id as the ergonomic alias for run_id.

MAS / Learning Loop Example

await client.registerAgent({
  session_id: "sdk-js-demo",
  agent_id: "planner",
  role: "planner",
  read_scopes: ["rule", "lesson", "fact"],
  write_scopes: ["lesson", "trace"],
  shared_memory_lanes: ["knowledge", "history"],
});

const checkpoint = await client.checkpoint({
  session_id: "sdk-js-demo",
  label: "pre-compaction-1",
  context_snapshot: "Planner has narrowed the failure to token refresh ordering.",
  metadata: { window: 1 },
});

const strategies = await client.surfaceStrategies({
  session_id: "sdk-js-demo",
  lesson_types: ["success", "failure"],
  max_strategies: 3,
});

console.log(checkpoint.checkpoint_id, strategies.strategies?.length ?? 0);

Exact References

const archived = await client.archive({
  session_id: "sdk-js-demo",
  artifact_kind: "patch_fragment",
  content: "--- a/query.py\n+++ b/query.py\n@@ ...",
  labels: ["django", "retry"],
  family: "patch-repair",
});

const exact = await client.dereference({
  session_id: "sdk-js-demo",
  reference_id: archived.reference_id,
});

console.log(exact.evidence?.content);

Endpoint Resolution

transport defaults to auto (gRPC primary, HTTP fallback).

Endpoint resolution order:

• explicit endpoint / http_endpoint / grpc_endpoint config fields
• env vars MUBIT_ENDPOINT, MUBIT_HTTP_ENDPOINT, MUBIT_GRPC_ENDPOINT
• shared defaults https://api.mubit.ai and grpc.api.mubit.ai:443

Package Example Lanes

Public adoption scenarios are the primary learning path:

node sdk/javascript/mubit-sdk/examples/public/run_public_examples.mjs --list
node sdk/javascript/mubit-sdk/examples/public/run_public_examples.mjs --scenario 01_remember_recall
node sdk/javascript/mubit-sdk/examples/public/run_public_examples.mjs --scenario 10_full_learning_loop_smoke

Internal raw-smoke scenarios remain available for compatibility and wire-level verification:

node sdk/javascript/mubit-sdk/examples/internal/run_internal_examples.mjs --list
node sdk/javascript/mubit-sdk/examples/internal/run_internal_examples.mjs --scenario auth_lifecycle