npm package: @mubit-ai/sdk
Description: Public unified Mubit SDK with one Client facade
Latest version: 0.5.3

# @mubit-ai/sdk

Canonical JavaScript SDK for MuBit.

## Install

```bash
npm install @mubit-ai/sdk
```

## Quickstart

```js
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

```js
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

```js
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:

```bash
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:

```bash
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
```