# @x12i/memorix-pipeline

> Memorix unified durable pipeline runtime (memorix-pipeline/v2)

Latest version **3.2.6** (published 2026-09-23) · exellix-license license · 0 weekly downloads

## Install

```sh
npm install @x12i/memorix-pipeline
pnpm add @x12i/memorix-pipeline
yarn add @x12i/memorix-pipeline
bun add @x12i/memorix-pipeline
```

## 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 | 3.2.6 |
| Published | 2026-09-23 |
| First published | 2026-07-07 |
| Weekly downloads | 0 |
| License | exellix-license |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 8 |
| Unpacked size | 436.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |
| Keywords | memorix, pipeline, v2 |

## Links

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

## Dependencies (8)

- [mongodb](https://npm.io/package/mongodb.md) ^6.21.0
- [@x12i/nexum](https://npm.io/package/@x12i/nexum.md) ^2.0.1
- [@x12i/memorix-data](https://npm.io/package/@x12i/memorix-data.md) ^3.0.2
- [@x12i/memorix-format](https://npm.io/package/@x12i/memorix-format.md) ^3.0.3
- [@x12i/memorix-memory](https://npm.io/package/@x12i/memorix-memory.md) ^3.2.1
- [@x12i/memorix-mapping](https://npm.io/package/@x12i/memorix-mapping.md) ^3.0.2
- [@x12i/memorix-relationships](https://npm.io/package/@x12i/memorix-relationships.md) ^3.1.0
- [@x12i/memorix-pipeline-runtime](https://npm.io/package/@x12i/memorix-pipeline-runtime.md) ^3.1.1

## Alternatives

- [byte-size](https://npm.io/package/byte-size.md) — 2.1M weekly downloads
- [speed-limiter](https://npm.io/package/speed-limiter.md) — 16.0K weekly downloads
- [@powersync/node](https://npm.io/package/@powersync/node.md) — 10.9K weekly downloads
- [@ledgerhq/coin-cardano](https://npm.io/package/@ledgerhq/coin-cardano.md) — 1.0K weekly downloads
- [@jayesol/jayeson.lib.streamfinder](https://npm.io/package/@jayesol/jayeson.lib.streamfinder.md) — 1.0K weekly downloads

## Recent versions

- 3.2.6 (latest) — 2026-09-23
- 3.0.0 (next) — 2026-07-23
- 3.2.3 — 2026-08-17
- 3.2.2 — 2026-08-16
- 3.2.1 — 2026-08-05
- 3.2.0 — 2026-08-05
- 3.1.0 — 2026-08-02
- 3.0.2 — 2026-07-23
- 3.0.1 — 2026-07-23
- 2.0.0 — 2026-07-23
- 1.35.0 — 2026-07-21
- 1.33.0 — 2026-07-11
- 1.32.0 — 2026-07-11
- 1.1.1 — 2026-07-07
- 1.1.0 — 2026-07-07

## README

# `@x12i/memorix-pipeline`

Durable **pipeline DAG engine** (`memorix-pipeline/v2`): captured plans, ordered step attempts, port registry (Memory, map, write, relationships, compose, enrich, …), retries, and run context.

## Install

```bash
npm install @x12i/memorix-pipeline@3.0.2
```

| Audience | Use this package? |
|----------|-------------------|
| Remote app | **No** — `/api/pipelines` |
| Platform / service | **Yes** |

## Exports

```ts
import {
  createPipelineRuntime,
  createLivePortRegistry,
  validatePipelineDefinition,
  createMongoRunLedger,
} from "@x12i/memorix-pipeline/v2";
```

Main entry also re-exports v2 surfaces from `.` where applicable; prefer **`./v2`** for new code.

## Lifecycle

```text
pipeline definition (metadata)
  → start run (capture plan + fingerprint)           # immediate execute
  → enqueue / lease / executeLeased                 # repeated-work queue
  → Work evaluate (selector → frozen batch → runs)   # continuous work
  → execute steps (attempts with input/output / DataRef)
  → mutating steps emit mutationRefs (persisted on attempt)
  → retry / resume
```

### Repeated work (Jobs Manager foundation)

Studio authors pipelines. Runtime Work definitions (operational, not Magit metadata) evaluate selectors again and again and create ordinary `PipelineRun` rows with `workId` / `batchId` / `itemRef` / `admission`.

| Concern | Mechanism |
|---------|-----------|
| Continuous Work | `PipelineWorkDefinition` in pipeline-runtime stores |
| Admission | `PipelineRun.admission` (`held` \| `ready` \| `leased`) on the run ledger |
| Step leases | Existing step `LeaseStore` |
| HTTP product API | `/api/jobs/v1` contract frozen (P1); handlers in P3 |

Do **not** introduce a parallel `job_runs` collection. One execution = one extended `PipelineRun`.

Pack schedules (design) ≠ Memory pull schedules ≠ Work cadence (runtime factory).

Step kinds include: `memory-pull`, `map-normalize`, `validate`, `identity-dedupe`, `write-record`, `relationship-discover`, `relationship-write`, `compose`, `enrich`, `analyze`, `decide`, `workflow`, `run-pipeline` (nested child run), `runx`, …

### Step targets (composition)

Authoring steps may carry a unified `target`:

| `target.kind` | Compiles to | Role |
|---------------|-------------|------|
| `service` | `analyze` / `enrich` / … + remote `portConfig` | Pack worker service |
| `ai-service` | `analyze` + `ai-services/1` | AI companion item |
| `connector` | `memory-pull` | Connector + source pull |
| `pipeline` | `run-pipeline` | Nested pipeline (child `PipelineRun`) |
| `runx` | `runx` | Runx capability (`runx.run`) |

Nested pipelines use **child runs** with lineage (`parentRunId`, `pipelineCallStack`) and cycle/depth guards (default max depth 8).

### Pipeline as a service

| Route | Role |
|-------|------|
| `POST /api/pipelines/:pipelineId/invoke` | Capability-shaped invoke |
| `POST /api/capability/invoke` | `serviceId: "pipeline:{id}"` (or bare installed id) |
| `GET /api/pipelines/services` | Virtual service catalog entries |

## Quick example

```ts
import { createPipelineRuntime, validatePipelineDefinition } from "@x12i/memorix-pipeline/v2";

validatePipelineDefinition(definition);
const rt = createPipelineRuntime({
  orgId,
  ledger,
  ports: createLivePortRegistry({ /* data, memory, relationships, mappings */ }),
});
const run = await rt.start({ agentIds, pipelineId, definition, input });
const attempts = await rt.getStepAttempts(run.runId);
```

## HTTP

| Route | Role |
|-------|------|
| `GET /api/pipelines/definitions` | From effective metadata |
| `GET /api/pipelines/services` | Pipelines as virtual services |
| `POST /api/pipelines/start` | Start a run |
| `POST /api/pipelines/:pipelineId/invoke` | Capability-shaped invoke |
| `POST /api/capability/invoke` | `pipeline:*` service invoke |
| `GET /api/pipelines/runs/:runId` | Run + attempts |
| `POST .../retry-step` · `.../resume` | Recovery |

## Related

| Package | Role |
|---------|------|
| `@x12i/memorix-pipeline-runtime` | Artifacts / leases / DLQ helpers |
| `@x12i/memorix-data-journey` | Reconstructs the data cone from attempts + mutationRefs |
| `@x12i/memorix-mapping` | `map-normalize` execution |

## Docs

- Package docs under [`docs/`](./docs/)
- [`docs/mutation-refs-capture.md`](./docs/mutation-refs-capture.md)
- Ebook: [Building Pipelines](../memorix-docs/08-pipelines/)
- Hub: [https://docs.memorix.x12i.com](https://docs.memorix.x12i.com)

```bash
npm test
```

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