@x12i/memorix-sdk — Memorix Capability SDK

Build multi-step work on Memorix and implement the capabilities it invokes.

The SDK is the primary developer entry point. Canonical content writes go through @x12i/memorix-client explore.writeContent (re-exported here), which calls POST /api/data/content. Call ensureMetadata({ pack }) once at process start before the first write.

npm install @x12i/memorix-sdk@^1.2.3

@x12i/memorix-sdk
 ├─ /client     re-exports @x12i/memorix-client (Explore, publications, pipelines, checkpoints, commitPage, getConnection, …)
 ├─ /worker     defineCapability + createMemorixWorker (@x12i/core-service)
 ├─ /authoring  validate/compile pack + pipeline metadata
 └─ /testing    recorded adapters + envelope helpers

@x12i/memorix-client remains the canonical HTTP foundation underneath /client.

For provider connectors (source pull / push workflows), use @x12i/memorix-connector-sdk — defineConnector, workflow steps, and checkpoint-aware collectStream.

Product → pipelines

import { createMemorixClient } from "@x12i/memorix-sdk/client";

const mx = createMemorixClient({
  baseUrl: "http://127.0.0.1:5100",
  orgId: "sandbox1",
  agentIds: ["opx"],
  caller: "my-app",
});

await mx.ensureMetadata({ pack: myAgentPack }); // once per process start

await mx.explore.writeContent({
  objectType: "people",
  contentType: "raw",
  precondition: "absent",
  record: {
    recordId: "E-10",
    data: { displayName: "Ada" },
    concept: {
      title: "Ada",
      identifiers: { primary: { kind: "recordId", value: "E-10", issuer: "my-app" } },
    },
  },
});

const run = await mx.pipelines.start("knowx-associate", {
  recordId: "PB-2",
});
const completed = await mx.pipelines.wait(run.runId);
const arts = await mx.pipelines.listArtifacts(run.runId);

Called service worker

import {
  defineCapability,
  createMemorixWorker,
} from "@x12i/memorix-sdk/worker";

const capability = defineCapability({
  serviceId: "knowx-associate",
  operation: "associate",
  capabilities: ["analyze"],
  memorixAccess: ["explore"],
  handler: async (request, context) => {
    const existing = await context.memorix!.explore.listContent({
      objectType: "people",
      contentType: "knowx",
    });
    return { drafts: [{ inputs: request.inputs, existing }] };
  },
});

const worker = createMemorixWorker({ service: capability, port: 0 });
await worker.start();

Workers receive a versioned CapabilityInvocation (memorix-capability/1) with scope, execution metadata, inputs, and an optional memorix callback context (including a server-issued grant).

memorixAccess may include "explore" | "checkpoints" | "raw". Callback clients cannot call memory.pull (operator-only).

Authoring

import {
  validatePack,
  compilePipeline,
} from "@x12i/memorix-sdk/authoring";

const compiled = compilePipeline(definition);
// Installation remains an explicit memorix-service operation.

Boundaries

| In SDK | Not in SDK | |--------|------------| | Pipeline start/wait/cancel/retry | DAG execution engine | | Worker HTTP host (core-service) | Mongo / db-router | | Pack validation | Run ledger implementation | | Callback Explore / raw / checkpoints / commitPage | Canonical write ports; operator Memory pull |

memorix-service remains the orchestration and persistence plane.

Docs

• Hub: https://docs.memorix.x12i.com · npm @x12i/memorix-docs
• Books: Services, Pipelines, Runtime Data Client · use case bi-dir-callable-service