@x12i/memorix-service

Sole production HTTP composition root over accepted Memorix packages.

Remote apps should call this service over HTTP — not reinvent wiring by installing every engine. Running the process (or a hosted deployment) is the product surface.

Install / run

npm install @x12i/[email protected]   # composition library / CLI

Prefer the monorepo stack (service + Studio + opx-source):

# from repo root
node scripts/dev-stack.mjs

Or this package alone:

MEMORIX_SERVICE_MODE=prod MONGO_URI=mongodb://127.0.0.1:27017 npm run serve
MEMORIX_SERVICE_MODE=dev npm run dev   # metadata in-memory; durable routes 503 without Mongo

| | | |--|--| | Default port | 5100 (MEMORIX_SERVICE_PORT, zone memorix) | | OpenAPI | GET /api/openapi.json | | Live view | GET /_live (@x12i/core-service → @x12i/api-live-view) | | Health | GET /health |

Compliance: this process uses @x12i/core-service (zone port, health, live view, correlation-id).

Dual-mode org blob plane (cloud / on-prem)

Not Magit. When storing org/connector object payloads that would use cloud buckets, on-prem must use local disk.

| Env | Effect | |-----|--------| | MEMORIX_BLOB_BACKEND | disk / onprem (default) or s3 / cloud | | MEMORIX_BLOB_ROOT | Disk root for on-prem (default .memorix-blobs) | | MEMORIX_S3_BUCKET | Required when backend=s3 | | MEMORIX_RESTRICTED_KEK | Optional AES-GCM KEK for disk-encrypted restricted bodies |

Used by /api/restricted-store/v1 (FG-A3). See restricted-store.md and integration-registry.md.

Magit package catalog

Default-on when durable Mongo is configured (METADATA_MAGIT=0 disables).

| Mode | Config | |------|--------| | A typed store | MAGIT_PACKAGE_STORE_SELECTOR + MAGIT_PACKAGE_TYPE_ID | | B flat catalog | both unset |

Requires @x12i/[email protected]. Defaults: MAGIT_CATALOG_TENANT=x12i, MAGIT_CATALOG_REPO=memorix.

Ops (provision / verify / recover / channels / smoke): see documentation/magit-typed-store-runbook.md.

npm run catalog:provision -- --out /secure/magit-store.env --confirm-allowed-kinds
npm run catalog:verify
npm run catalog:recover -- --store-id st_… --out /secure/magit-store.env
npm run catalog:list
npm run magit:cross-env-smoke
npm run magit:cross-env-smoke -- --publish

Owner mint: repo memorix, Package stores empty until the store exists.
Consumer: store grant + repoIds: [] (Repositories unchecked).
Channels and release sets need Mode A + publisher token to promote; consumers only resolve.

Env examples: memorix-service/.env.example. Selector never appears in Studio or GET /api/diagnostics/scope.

Library exports

When embedding the composition root in-process:

import {
  createMemorixPlatform,
  createMemorixServiceApp,
  startMemorixServiceHttp,
} from "@x12i/memorix-service";

Scope headers

Every /api/* request requires:

x-memorix-org-id: sandboxdemo
x-memorix-agent-ids: opx

Singular agentId headers are rejected. agentIds[] selects effective metadata; orgId selects the data universe.

Minimal curl

curl -s http://127.0.0.1:5100/health
curl -s http://127.0.0.1:5100/api/diagnostics/scope \
  -H 'x-memorix-org-id: sandboxdemo' \
  -H 'x-memorix-agent-ids: opx'

Route families

| Family | Role | |--------|------| | /api/metadata | Kinds, definitions, install/publish, pack versions (Magit default-on; METADATA_MAGIT=0 disables) | | /api/data | Content get/list/write, compose, abstract | | /api/relationships | Query / discover / verify / rebuild (no ad-hoc link PUT) | | /api/memory | Pull, raw, sources, checkpoints, schedules, runs, commit-page, connection probe | | /api/pipelines | Definitions, start, runs, retry/resume | | /api/operations | Operational helpers | | /api/workflow | Workflow sibling content | | /api/intelligence | Profiles / proposals (never auto-install) | | /api/data-journey | Evidence cone + expected-vs-filled coverage | | /api/ai-services | Companion AI-services (function / skill / task / graph) — list, items, invoke proxy |

AI-services companions

Point memorix-service at FR-compliant processes via env (FUNCX_URL, AI_SKILLS_URL, AI_TASKS_URL, GRAPH_ENGINE_URL).
Stack: AI companions are on by default; skip with --no-ai-services or AI_SERVICES=0.

Vendor pipeline workers (opt-in)

Archetype-A HTTP companions invoke via POST {origin}/pipeline. Inject base origin only (no /pipeline path). Soft-skip when URL unset; fail-closed when set (src/optional-companion-url.ts).

| Suite | Stack flag | Client env | |-------|------------|------------| | Exellix Apollo + M365 | --exellix-connectors / EXELLIX_CONNECTORS=1 | EXELLIX_APOLLO_READ_URL, EXELLIX_APOLLO_ACTIONS_URL, EXELLIX_M365_USER_READ_URL, EXELLIX_M365_USER_ACTION_URL (ports 9711–9722, zone exellix-connectors) | | Neo security workers | --neo-connectors / NEO_CONNECTORS=1 | NEO_FIREWALL_URL, NEO_XDR_URL, NEO_NESSUS_URL, NEO_ENTRA_URL, NEO_SPLUNK_URL, NEO_CROWDSTRIKE_URL (frozen ports; no zone remap) | | Neo status UI | --neo-status-ui / NEO_STATUS_UI=1 | NEO_STATUS_UI_URL (:9001) |

Optional hard gates: EXELLIX_CONNECTORS_REQUIRED=1, NEO_CONNECTORS_REQUIRED=1.

Neo packages ship on GitHub Packages. Local install needs .npmrc scope + NODE_AUTH_TOKEN (see .npmrc.example).

Memory (operator + called-service)

| Method | Path | Notes | |--------|------|-------| | GET | /api/memory/sources/{sourceId}/connection | Probe configured URL | | GET/PUT/POST | …/checkpoints (+ /reset) | Source position per OT × route | | POST | …/commit-page | Model B atomic land + checkpoint | | POST | /api/memory/pull | Operator-only — rejected when x-memorix-invocation-grant is present |

Called services with memorixAccess receive an HMAC grant scoped to explore · checkpoints · raw. Prefer @x12i/memorix-sdk (/client / /worker) over raw fetch.

Data journey (read-only)

| Method | Path | |--------|------| | GET | /api/data-journey/object-types | | GET | /api/data-journey/journeys | | POST | /api/data-journey/matrix/query | | POST | /api/data-journey/matrix/columns/query | | POST | /api/data-journey/matrix/cells/query | | GET | /api/data-journey/evidence/:evidenceRef | | GET | /api/data-journey/expected-slots | | POST | /api/data-journey/coverage |

Hard rules

• Prod rejects missing Mongo and in-memory durable fallbacks
• /api/relationships/links → 405 (no ad-hoc link mutation)
• Intelligence never auto-installs/publishes
• Only credentialRef may cross Memory APIs

Docs

• documentation/http-api.md · OpenAPI in-repo openapi/openapi.json
• Capability SDK: @x12i/memorix-sdk · HTTP client: @x12i/memorix-client
• Ebooks: Platform Overview · Services · Runtime Data Client
• Hub: https://docs.memorix.x12i.com · npm @x12i/memorix-docs