# @x12i/nexum

> Nexum — Memorix analyze worker + explore SDK. Deterministic knowledge-graph drafts; optional Mongo ingest via Python REST; semantic via assistant-functions.

Latest version **2.0.1** (published 2026-09-19) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @x12i/nexum
pnpm add @x12i/nexum
yarn add @x12i/nexum
bun add @x12i/nexum
```

Provides the commands `nexum-worker`, `nexum-semantic-bridge`.

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2026-09-19 |
| First published | 2026-08-16 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.0.0 |
| Dependencies | 5 |
| Unpacked size | 221.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |
| Keywords | x12i, nexum, memorix, knowledge-graph, capability-worker, sdk, rest-client, json-schema, openapi |

## Links

- npm: https://www.npmjs.com/package/@x12i/nexum
- Repository: https://github.com/x12i/nexum
- Homepage: https://github.com/x12i/nexum#readme
- Issues: https://github.com/x12i/nexum/issues
- npm.io page: https://npm.io/package/@x12i/nexum

## Dependencies (5)

- [fastify](https://npm.io/package/fastify.md) ^5.1.0
- [@x12i/ai-profiles](https://npm.io/package/@x12i/ai-profiles.md) ^4.4.0
- [@x12i/memorix-sdk](https://npm.io/package/@x12i/memorix-sdk.md) ^1.0.1
- [@x12i/ports-manager](https://npm.io/package/@x12i/ports-manager.md) ^1.0.5
- [@x12i/assistant-functions](https://npm.io/package/@x12i/assistant-functions.md) ^1.2.0

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 2.0.1 (latest) — 2026-09-19
- 1.0.0-rc.4 (rc) — 2026-08-16
- 2.0.0 — 2026-09-19
- 1.5.0 — 2026-09-19
- 1.0.0-rc.3 — 2026-08-16
- 1.0.0-rc.2 — 2026-08-16
- 1.0.0-rc.1 — 2026-08-16

## README

# Nexum

**Nexum** turns org knowledge into a **knowledge graph**.

Accepts **content**, **records**, **JSON Schema**, **OpenAPI / endpoints**, and **object properties**. Isolation is always per organization (`graphified-<orgId>` Mongo DB). Optional `agentId` is host/Memorix context only.

```bash
npm install @x12i/nexum@^2.0.1
# bins: nexum-worker, nexum-semantic-bridge
```

## Which API for which job

| Job | Use | Store |
|-----|-----|-------|
| Memorix pipeline analyze → write-record | **Capability worker** `nexum-worker` / `createNexumWorker` | Memorix subjects |
| Embed org/item graph in a host app | **Explore SDK** `createNexumClient` → Python REST | Mongo `graphified-{orgId}` |
| SPA explorer | [`ui/`](ui/) → Python REST | Mongo |
| Optional prose enrichment | `nexum-semantic-bridge` + `.funcx/` (assistant-functions) | Feeds Mongo ingest only |

Pipeline success does **not** fill SPA Mongo; SPA ingest does **not** fill Memorix subjects. See [docs/adr/0001-nexum-dual-surface.md](docs/adr/0001-nexum-dual-surface.md).

## Two surfaces

| You want | Use |
|----------|-----|
| Embed an org or item graph in a host app | **Explore SDK** — `createNexumClient` |
| Pipeline `analyze` drafts for Memorix `write-record` | **Capability worker** — `createNexumWorker` / `buildAnalyzeDraft` |

This package does **not** ship the React explorer under [`ui/`](ui/). Analyze never writes Memorix subjects or Mongo domain data; REST `POST …/ingestions` (deprecated alias `/graphify`) is the persist path for the explore API.

## Explore SDK — host views

```ts
import {
  createNexumClient,
  graphViewFrom,
  isGraphifierApiError,
} from "@x12i/nexum";

const client = createNexumClient({
  baseUrl: "http://127.0.0.1:8080",
  orgId: "authix",
  agentId: "opx", // host context only — not a DB filter
  graphId: "default",
});

try {
  // Org canvas (nodes include properties — schemas/endpoints keep their payload)
  const viz = await client.getVisualization({
    maximumNodes: 500,
    nodeTypes: ["schema", "endpoint", "property", "openapi"],
  });

  // Item ego-network
  const around = await client.getItemNeighborhood("default", "user-schema", {
    depth: 1,
  });

  const view = graphViewFrom(around); // { nodes, edges } for Cytoscape / Sigma / custom
  console.log(client.scope, view.nodes.length);

  // Preferred ingest
  await client.ingestions.submit({
    mode: "upsert",
    items: [/* … */],
  });
} catch (err) {
  if (isGraphifierApiError(err)) {
    console.error(err.code, err.status, err.message);
  } else {
    throw err;
  }
}
```

### View scopes

| View intent | SDK usage |
|-------------|-----------|
| Org graph | `getVisualization` / `searchNodes` / `getNeighbors` |
| Item + connected | `getItemNeighborhood(graphId, itemId, { depth })` |
| Schema / endpoint slice | `getVisualization({ nodeTypes: ["schema","endpoint","property"] })` or `listNodes(graphId, { type: "endpoint" })` |

`forScope({ orgId, agentId, graphId })` clones the client. REST paths are always `/v1/orgs/{orgId}/…`. See [`examples/explore-host-view.ts`](examples/explore-host-view.ts).

## Graphify schemas, endpoints, and objects

Content and record-shaped items still work. Structured JSON that **looks like** a schema or API is graphified without registering JSONPath object-types:

- **JSON Schema** — `$schema` or a `properties` map of objects → `schema` + `property` nodes, `has_property` / `refs`
- **OpenAPI** — `openapi` / `swagger` or `paths` → `openapi` + `endpoint` nodes, `exposes` / `uses_schema`
- **Endpoint object** — `method` + `path` (or `url`)
- **Nested objects** — child nodes + `has_property` (depth 2). Scalar record fields (e.g. `name`, `ownerTeamId`) stay on the entity; they are **not** exploded into property nodes

### Offline draft (no REST)

```ts
import { buildAnalyzeDraft, SERVICE_ID } from "@x12i/nexum";

const draft = buildAnalyzeDraft(
  {
    schemas: [
      {
        id: "user",
        title: "User",
        $schema: "https://json-schema.org/draft/2020-12/schema",
        properties: { email: { type: "string" } },
      },
    ],
  },
  { serviceId: SERVICE_ID },
);
// draft.proposedGraph.nodes / .edges — same envelope as analyze since 2.0.0
```

Bags: `items`, `records`, `snapshot`, **`schemas`**, **`endpoints`**, **`objects`**.

### Persist via REST

```ts
await client.graphify({
  items: [
    {
      id: "pets-api",
      inputType: "structured",
      objectType: "openapi",
      data: {
        openapi: "3.0.0",
        paths: { "/pets": { get: { operationId: "listPets" } } },
      },
    },
  ],
});
```

Optional `putObjectType` / `listObjectTypes` still apply JSONPath mappings when you want them; they are **not** required for schema/endpoint ingest. Full sample: [`examples/graphify-schema-endpoint.ts`](examples/graphify-schema-endpoint.ts).

Requires the Nexum REST API (`memorix_graphifier` Python package, typically `:8080`).

### Env (operator-side)

| Variable | Purpose |
|----------|---------|
| `NEXUM_API_URL` / `GRAPHIFIER_API_URL` | REST base for the client |
| `NEXUM_DEFAULT_ORG_ID` / `GRAPHIFIER_DEFAULT_ORG_ID` | Default orgId **or** full `graphified-<orgId>` |
| `NEXUM_DEFAULT_GRAPH_ID` / `GRAPHIFIER_DEFAULT_GRAPH_ID` | Default graph id (`default`) |
| `NEXUM_SEMANTIC_MODE` | `off` \| `enrich` \| `required` (Mongo ingest) |
| `NEXUM_SEMANTIC_PROFILE` | ai-profiles `profile/choice` (default `extraction/default`) |
| `OPENROUTER_API_KEY` | FuncX / assistant-functions (semantic enrich) |

## Capability worker (Memorix pipelines)

Analyze → persist envelope: `proposedGraph` + `sourceRefs` + `diagnostics` (since **2.0.0**). Platform sequence is **analyze → write-record**. Details: [`docs/memorix-binding.md`](docs/memorix-binding.md).

```bash
npm install
npm test
npm start   # or: nexum-worker
```

Worker listen URL is printed as JSON (`endpoint` → ServiceRef). Defaults: host `127.0.0.1`, port **7500** (ports zone `nexum`; ports-manager map key `memorix-graphier`).

- **serviceId:** `nexum`
- **operation:** `analyze`
- **Pack:** [`metadata/services.json`](metadata/services.json)
- **Sample pipeline:** [`examples/pipeline.v2.json`](examples/pipeline.v2.json)

```ts
import {
  nexumCapability,
  createNexumWorker,
  SERVICE_ID,
} from "@x12i/nexum";
```

Depends on `@x12i/memorix-sdk` only. Do not install Memorix engine packages in this app.

### Manual invoke

```bash
curl -sS -X POST "http://127.0.0.1:${NEXUM_WORKER_PORT:-7500}/" \
  -H 'content-type: application/json' \
  -d '{
    "version":"memorix-capability/1",
    "serviceId":"nexum",
    "operation":"analyze",
    "scope":{"orgId":"sandbox1","agentIds":["opx"]},
    "execution":{
      "runId":"r1","stepId":"s1","attempt":1,"correlationId":"c1"
    },
    "inputs":{
      "items":[
        {"id":"credorix","inputType":"structured","objectType":"product",
         "data":{"name":"Credorix","ownerTeamId":"identity-team"}}
      ]
    }
  }'
```

Smoke and CI fixtures: **`sandbox*`** orgs and **`agentIds: ["opx"]`** only.

## Python REST (SPA / SDK)

[`memorix_graphifier/`](memorix_graphifier/) is a FastAPI + Mongo explore/ingest API. It is **not** the Memorix called-service surface. The explore SDK uses it as the data plane.

```bash
export NEXUM_USE_MEMORY_STORE=true
# or GRAPHIFIER_USE_MEMORY_STORE=true
pip install -e ".[dev]"
```

See [ARCHITECTURE.md](ARCHITECTURE.md). Internals: [`docs/graphify-internals.md`](docs/graphify-internals.md).

## Knowledge Graph UI

Optional full SPA (not this npm package):

```bash
# API: set GRAPHIFIER_CORS_ORIGINS=http://127.0.0.1:7501
cd ui && cp .env.example .env && npm install && npm run dev
# open http://127.0.0.1:7501/organizations/<orgId>/knowledge-graph
```

Details: [`ui/README.md`](ui/README.md).

## License

Apache License 2.0. Upstream Graphify attribution is retained in [NOTICE](NOTICE) and [LICENSE-MIT](LICENSE-MIT) for applicable portions.

---
_Source: https://npm.io/package/@x12i/nexum · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._