@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 theagentIdson that org's entry inlistOrgs(), to call Memorix for an org.listAgents()with noorgIdreturns 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
TGIandtgiare 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,listAgentsreturnsagents[]:{ agentId, inPlay, registeredAt, registeredVia, dataBasis?, lastWriteAt? }.inPlayisinstall, plusdatawhen the org holds rows written under the agent.registeredViaisinstall,register, ormigrated.dataBasisiswritewhen a write stamped the agent andinferredwhen the Memorix agents backfill named it.mapping.listAgents({ scope: "org" })carries the same fields on each agent.mapping.registerAgent(agentId)registers an installed pack, andmapping.unregisterAgent(agentId)removes that registration and keeps the rows. - A content write names exactly one agent in
agentIds. Several ids or*is400 WRITE_AGENT_REQUIRED. An agent that is not registered for the org is403 AGENT_NOT_REGISTERED. A content type may declarewriterAgents; a write from another agent is stored and the response haswarningswithcode: "WRITER_AGENT_UNEXPECTED". - A restricted caller (invocation grant, deployment identity, or an isolated sandbox service) sees only its own org.
listAgentsfor any other org is403 ACCESS_DENIED. - With
MEMORIX_DEPLOYMENT_AUTH=required,listOrgs()andlistAgents({ orgId })need a validdeploymentIdentity, or they are401. - Discovery calls never send
x-memorix-org-idorx-memorix-agent-ids, includingmx.discoveryon a client that has them. Errors areMemorixClientErrorwith 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. Standalonecheckpoints.putis administrative and is not proof of landing.
Scope headers
Every request except discovery sends:
x-memorix-org-idx-memorix-agent-idsx-memorix-caller(MX-CALLER-01)x-memorix-invocation-grant(when present fromfromInvokeContext)x-memorix-deployment-identity(whendeploymentIdentityorMEMORIX_DEPLOYMENT_IDENTITYis 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.*.