npm.io
3.22.0 • Published 4 weeks ago

@x12i/memorix-client

Licence
exellix-license
Version
3.22.0
Deps
0
Size
470 kB
Vulns
0
Weekly
0

@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.22.0
# preferred for new apps:
npm install @x12i/memorix-sdk@^1.3.0

Aligned with @x12i/memorix-service@3.23.0, @x12i/memorix-data@3.7.0, and @x12i/memorix-metadata@3.9.0. @x12i/memorix-scoper-sdk@2.2.0 and @x12i/memorix-skills@0.6.1 require this client at ^3.13.0.

Requires a running @x12i/memorix-service@^3.7.6 for metadata ensure, MCO, integrations, restricted store, continuous acquisition, incremental-state, and POST /mcp/nexum. includeDeleted, listDeletions, queued writes, content-type writer / schema checks, and expectedChecksum need 3.16.0. Raw restricted-store upload (putObjectBytes), owner read (getContentOwner), and relationship rebuild / verify need 3.17.0. mapping.listAgents({ scope: "org" }), mapping.census(), and queryRelationships with countOnly and groupBy need 3.18.0; census status per pair needs 3.19.0, conflicted object types in the census need 3.19.1, and mapping.subjects and their content-type rows need 3.20.0. Org and agent discovery (createMemorixDiscoveryClient, discovery.listOrgs, discovery.listAgents) needs 3.21.0; agents in play from the org's data (inPlay, dataBasis, lastWriteAt) need 3.22.0. Registered agents (registeredAt, registeredVia, mapping.registerAgent, mapping.unregisterAgent) and one writing agent per writeContent need 3.23.0.

Env resolution for acquisition stores: set MEMORIX_SERVICE_URL or MEMORIX_URL (optional token via MEMORIX_SERVICE_TOKEN / MEMORIX_TOKEN). When MEMORIX_DEPLOYMENT_AUTH=required, set MEMORIX_DEPLOYMENT_IDENTITY (the HMAC token from issueDeploymentIdentity, not MEMORIX_TOKEN). resolveMemorixClient and resolveRestrictedStoreClient send it as x-memorix-deployment-identity. Memory / noop modes (NEO_*_MODE=memory|off) are for tests and soft-skip only — not production acceptance.

Surfaces

Area Methods
Explore getContent, getContext (GET /api/data/content/context), listContent, queryContent, countContent (count=true from a live property index; a count with includeDeleted reads the collection), listDeletions (GET /api/data/deletions), getAbstract, runList (declared listId or abstract properties), compose, composeData / composeDataList (concrete CT .data), writeContent (queue: true accepts a row before it is stored; service 3.23.0 names exactly one agent), removeContent, queryRelationships, rebuildRelationships, verifyRelationships (POST /api/relationships/rebuild and /verify, service 3.17.0)
Analytics analytics.indexes.list, get, validate, register, remove — agent-declared stored paths. Pair with @x12i/memorix-service OpenAPI ≥ 3.11.1
Metadata ensureMetadata({ pack, expectedChecksum? }) — call once at process start before the first write; throws unless ready. expectedChecksum is 409 when the installed pack differs. listObjectTypeKinds() reads GET /api/metadata/kinds/object-types for this client's agent ids and returns the body unchanged
Discovery createMemorixDiscoveryClient / resolveMemorixDiscoveryClient, or client.discovery: listOrgs (GET /api/orgs) and listAgents({ orgId? }) (GET /api/agents). Caller header only, no org or agent ids. Service 3.21.0. See Finding org and agent ids
Mapping mapping.listAgents, registerAgent, unregisterAgent (service 3.23.0), raw, effective, kinds, census, subjects (directory pages, service 3.20.0), relationshipDefinitions, sources, sourceRuns, sourceCensus read the documents an org and agent mapping is built from and return them unchanged
Publications createDraft, list, lastGood, get, commit, getInstances
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 JSON put / break-glass content, plus putObjectBytes and getContentOwner (raw bytes, service 3.17.0)
Acquisition stores resolveStreamCheckpointStore, resolveOpStateStore / createOpStateStore, resolveInstanceRegistry — durable host façades (memory/noop = non-production)
MCP (agents) buildAgentMcpBundle, cursorMcpSnippet / claudeMcpSnippet, createNexumMcpClient — see MCP

Does not include Mongo, memorix-data, the pipeline engine, a worker server, or the Work APIs Playground UI (private monorepo tool on :5113).

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

Request timeout: when a call does not pass signal, the client aborts after requestTimeoutMs (default 30_000). Timeout errors are MemorixClientError with code REQUEST_TIMEOUT and name the operation (and recordId when applicable). Pass your own signal, or set requestTimeoutMs: 0, to opt out.

Product → Memorix

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

const mx = createMemorixClient({
  baseUrl: "http://127.0.0.1:5100",
  orgId: "sandbox1",
  agentIds: ["opx"],
  caller: "my-app",
  // optional: default 30_000; set 0 to disable. Per-call `signal` skips this.
  // requestTimeoutMs: 60_000,
});

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 person = await mx.explore.getContent({
  objectType: "people",
  contentType: "raw",
  recordId: "E-10",
});
// person is the whole record: record.data is the subject, record.context is the context payload.

const publication = await mx.explore.getContent({
  objectType: "security-map",
  contentType: "estate-analytics",
  recordId: "working/estate-analytics",
  discriminatorValue: "publication",
});
// discriminatorValue addresses one instance. The client sends it as a query parameter.

const security = await mx.explore.getContext({
  objectType: "endpoint-asset",
  contentType: "security-context",
  recordId: "object:forti-observed-1",
});
// security is the context object itself (for example { exploitability }).
// agent-context, pre-ai-context, and live-context come back as { agent }, { preAi }, or { live }.

const openPeople = await mx.explore.queryContent({
  objectType: "people",
  contentType: "raw",
  filter: { "data.status": "open" }, // or SafeFilter[]: [{ field, op: "eq", value }]
  limit: 50,
});
// openPeople.records + openPeople.pageInfo.nextCursor

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

Finding org and agent ids

Every /api/* call is scoped by x-memorix-org-id and x-memorix-agent-ids. To find those values, use the discovery client. It needs only baseUrl and caller. Requires @x12i/memorix-service@3.21.0 or later.

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

const discovery = createMemorixDiscoveryClient({
  baseUrl: process.env.MEMORIX_SERVICE_URL!,
  caller: "my-app",
  // deploymentIdentity: process.env.MEMORIX_DEPLOYMENT_IDENTITY, // when MEMORIX_DEPLOYMENT_AUTH=required
});

const { orgs } = await discovery.listOrgs();
// [{ orgId: "tgi", agentIds: ["network-synapix"] }]

const { agentIds } = await discovery.listAgents({ orgId: "tgi" });
// the agents recorded for tgi: use these in x-memorix-agent-ids for that org

const mx = createMemorixClient({ baseUrl: process.env.MEMORIX_SERVICE_URL!, orgId: "tgi", agentIds, caller: "my-app" });
const details = await mx.mapping.listAgents({ scope: "org" }); // object and content types per agent
  • Use listAgents({ orgId }), or the agentIds on that org's entry in listOrgs(), to call Memorix for an org. listAgents() with no orgId returns every installed pack (orgId: null), including ones that org does not use.
  • Org ids come back lower-case and sorted. Org matching is case-insensitive, so TGI and tgi are the same org.
  • An org is listed when it has an operational database, an in-process store, or at least one registered agent.
  • From service 3.23.0 an org's agents are the ones registered for it. With orgId, listAgents returns agents[]: { agentId, inPlay, registeredAt, registeredVia, dataBasis?, lastWriteAt? }. inPlay is install, plus data when the org holds rows written under the agent. registeredVia is install, register, or migrated. dataBasis is write when a write stamped the agent and inferred when the Memorix agents backfill named it. mapping.listAgents({ scope: "org" }) carries the same fields on each agent. mapping.registerAgent(agentId) registers an installed pack, and mapping.unregisterAgent(agentId) removes that registration and keeps the rows.
  • A content write names exactly one agent in agentIds. Several ids or * is 400 WRITE_AGENT_REQUIRED. An agent that is not registered for the org is 403 AGENT_NOT_REGISTERED. A content type may declare writerAgents; a write from another agent is stored and the response has warnings with code: "WRITER_AGENT_UNEXPECTED".
  • A restricted caller (invocation grant, deployment identity, or an isolated sandbox service) sees only its own org. listAgents for any other org is 403 ACCESS_DENIED.
  • With MEMORIX_DEPLOYMENT_AUTH=required, listOrgs() and listAgents({ orgId }) need a valid deploymentIdentity, or they are 401.
  • Discovery calls never send x-memorix-org-id or x-memorix-agent-ids, including mx.discovery on a client that has them. Errors are MemorixClientError with the status and body Memorix returned.

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: "people",
  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 except discovery sends:

  • x-memorix-org-id
  • x-memorix-agent-ids
  • x-memorix-caller (MX-CALLER-01)
  • x-memorix-invocation-grant (when present from fromInvokeContext)
  • x-memorix-deployment-identity (when deploymentIdentity or MEMORIX_DEPLOYMENT_IDENTITY is set)
import { createMemorixClient, resolveMemorixClient } from "@x12i/memorix-client";

const mx = createMemorixClient({
  baseUrl: process.env.MEMORIX_SERVICE_URL!,
  orgId: "sandbox1",
  agentIds: ["opx"],
  caller: "my-app",
  deploymentIdentity: process.env.MEMORIX_DEPLOYMENT_IDENTITY,
});

const resolved = resolveMemorixClient({
  orgId: "sandbox1",
  agentIds: ["opx"],
  caller: "my-app",
});

MCP (agents)

Product land/read/pipelines stay on createMemorixClient HTTP. Agents also get two MCP servers: MGC (:7480/mcp) and memorix-nexum (:5100/mcp/nexum). See docs/mcp-expert-brief.md in the monorepo.

import {
  buildAgentMcpBundle,
  createMgcMcpClient,
  createNexumMcpClient,
} from "@x12i/memorix-client";
// or: import { … } from "@x12i/memorix-client/mcp";

const bundle = buildAgentMcpBundle({
  memorixServiceUrl: process.env.MEMORIX_SERVICE_URL!,
  mgcSourceServiceUrl: process.env.MGC_SOURCE_SERVICE_URL,
  scope: { orgId: "tgi", agentIds: ["opx"] },
});
// paste bundle.nexum.cursorJson / bundle.mgc.cursorJson into Cursor mcp.json

const mcp = createNexumMcpClient({
  baseUrl: process.env.MEMORIX_SERVICE_URL!,
  orgId: "tgi",
  agentIds: ["opx"],
  caller: "my-agent-host",
});
await mcp.listTools();
const snapshots = await mcp.listSnapshots({ knowledgeGraphOnly: true });
await mcp.callTool("nexum_get_snapshot", { recordId: "snap-1" });

const mgc = createMgcMcpClient({
  baseUrl: process.env.MGC_SOURCE_SERVICE_URL!,
  orgId: "tgi",
  agentIds: ["opx"],
  caller: "my-agent-host",
});
await mgc.listConnectors();

Canvas HTTP (same dual store as MCP canvas tools): mx.knowledge.*.

Keywords