@x12i/memorix-client

@x12i/memorix-client

Canonical typed HTTP client for Memorix. This is the only implementation of scope headers, errors, Explore, raw Memory, Source checkpoints, schedules, connection probe, and pipeline run control.

New product code should prefer @x12i/memorix-sdk (re-exports this client and adds worker / authoring / testing). Existing @x12i/memorix-client installs remain compatible.

Wire contract = memorix-service OpenAPI.

Install

npm install @x12i/memorix-client@^3.5.0
# preferred for new apps:
npm install @x12i/memorix-sdk@^1.0.1

Requires a running @x12i/memorix-service@^3.6.0 for MCO, integrations, restricted store, continuous acquisition, and incremental-state.

Env resolution for acquisition stores: set MEMORIX_SERVICE_URL or MEMORIX_URL (optional token via MEMORIX_SERVICE_TOKEN / MEMORIX_TOKEN). Memory / noop modes (NEO_*_MODE=memory|off) are for tests and soft-skip only — not production acceptance.

Surfaces

Area	Methods
Explore	getContent, listContent, getAbstract, compose, queryRelationships
Memory	getRaw, getConnection, commitPage, pull, listRuns
Schedules	get, put, pause, resume, runNow, remove (Memory pull intervals)
Checkpoints	list, get, put (+ expectedRevision), reset
Pipelines	list, get, start, getRun, wait, cancel, retry, resume, listArtifacts, getArtifact
Connector ops (MCO)	createConnectorOpClient / resolveConnectorOpClient — overrides + attempt stats (soft-skip when URL unset)
Stream checkpoints (INC-01)	createStreamCheckpointClient / resolveStreamCheckpointClient — watermark/revision/hash/cursor
Continuous acquisition	createContinuousAcquisitionClient / resolveContinuousAcquisitionClient — schedule/lease/freshness/tick
Incremental state	createIncrementalStateClient / resolveIncrementalStateClient — CAS + apply-commit
Integration registry	createIntegrationRegistryClient / resolveIntegrationRegistryClient — Stage −1 instances + snapshot token
Restricted store	createRestrictedStoreClient / resolveRestrictedStoreClient — FG-A3 put metadata / break-glass content
Acquisition stores	resolveStreamCheckpointStore, resolveOpStateStore / createOpStateStore, resolveInstanceRegistry — durable host façades (memory/noop = non-production)

Does not include Mongo, memorix-data, the pipeline engine, or a worker server.

memory.pull is operator-only. Clients built with fromInvokeContext (callback grant) cannot call it — use Explore / checkpoints / raw / commitPage.

Product → Memorix

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

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

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

const conn = await mx.memory.getConnection("opx-source");
// Connected | Unreachable | Missing URL

Called service → Memorix

When a pack service declares memorixAccess, Memorix posts a versioned CapabilityInvocation envelope including memorix callback context (+ server-issued grant):

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

const mx = fromInvokeContext(request.memorix);
const existing = await mx.explore.listContent({
  objectType: "employees",
  contentType: "snapshots",
});
await mx.checkpoints.list("opx-source");

Access is enforced client-side (method gating) and server-side (HMAC grant). Mutating access[] cannot escalate privileges.

Allowed surfaces: "explore" | "checkpoints" | "raw".

Checkpoint commit

• Model A (preferred): Memory-controlled paging — worker returns { page, nextCheckpoint }; Memory lands and commits.
• Model B: mx.memory.commitPage({ …, expectedCheckpointRevision }) — land exact raw items then advance checkpoint atomically. Standalone checkpoints.put is administrative and is not proof of landing.

Scope headers

Every request sends:

• x-memorix-org-id
• x-memorix-agent-ids
• x-memorix-invocation-grant (when present from fromInvokeContext)