@x12i/memorix-writer

Descriptor-driven write layer for Memorix. Turns Catalox write descriptors, entity descriptors, validated input, and optional Markdown/text content into Memorix records and external content object pointers.

Shared MongoDB naming rules: docs/MEMORIX-DATABASE-CONVENTIONS.md.

Architecture

• Catalox — memorix-write-descriptors, memorix-object-type-descriptors. Catalog metadata lives in MongoDB (memorix-catalox via @x12i/catalox/mongo). Firestore is not used for Memorix Catalox.
• MongoDB — built-in MemorixDataTier + collection-name CRUD (no separate @x12i/memorix package)
• @x12i/memorix-descriptors — shared catalog ids and descriptor validation (aligned with retrieval)
• @x12i/helpers — GCS/S3 content uploads (contentWriters.gcs / contentWriters.s3)
• @x12i/memorix-retrieval (optional) — returnMode: "retrievalItem"

Quick start

Set MONGO_URI and provide a Catalox client. Database names, entity vs event routing, and collection resolution are handled internally.

MONGO_URI=mongodb://localhost:27017

import {
  createMemorixWriterFromEnv,
  writeMemorixRecord,
} from "@x12i/memorix-writer";

const writer = await createMemorixWriterFromEnv({
  catalox: boundCatalox, // must implement getCatalogItem(appId, catalogId, itemId)
  contentWriters: {
    gcs: myGcsUploader, // uploadObject({ key, body, contentType })
  },
});

const result = await writeMemorixRecord(writer, {
  writeDescriptorId: "asset-analysis-write",
  entityId: "10.150.68.31",
  input: { riskLevel: "HIGH", summary: "..." },
  metadata: { source: { uri: "file://scan.json" } },
  tags: ["risk", "source-scan"],
  narratives: {
    "high-risk": { detectedBy: "risk-worker" },
  },
  content: {
    fields: {
      investigationReport: { body: "# Report\n...", format: "markdown" },
    },
  },
});

await writer.close?.();

Lazy connect (same env, no upfront await):

import { createMemorixWriter, writeMemorixRecord } from "@x12i/memorix-writer";

const writer = createMemorixWriter({ catalox: boundCatalox });
// connects to Mongo on first write using MONGO_URI

Advanced (optional)

Override defaults only when you need to:

| Option | Purpose | |--------|---------| | MEMORIX_ENTITIES_DB / MEMORIX_EVENTS_DB | Non-default database names | | MEMORIX_ENTITIES_COLLECTION_* / MEMORIX_EVENTS_COLLECTION_* | Per-type collection overrides | | memorix | Inject a pre-configured MemorixDataTier instead of built-in Mongo connect | | mongo | Reuse an existing MongoClient | | processEnv | Custom env object (default: process.env) |

Collection resolution

Writes target memorix-entities, memorix-events, or memorix-knowledge based on the write descriptor (target.kind, defaulting from the descriptor's identity.idField config). Database names follow Memorix Database Conventions (MEMORIX_ENTITIES_DB, MEMORIX_EVENTS_DB, MEMORIX_KNOWLEDGE_DB, …).

Identity model

Every record this package writes uses the memorix-record.2.0 envelope — a nested identity object, not flat top-level id fields:

{
  "identity": {
    "recordId": "rec_...",
    "target": "entity",
    "targetId": "10.150.68.31",
    "objectType": "assets",
    "contentType": "analysis",
    "version": "memorix-record.2.0"
  },
  "lifecycle": { "createdAt": "...", "modifiedAt": "...", "status": "active" },
  "concept": { "kind": "assets", "name": "10.150.68.31" },
  "data": { "...": "..." }
}

entityId / eventId / knowledgeId are request-time parameter names on writeMemorixRecord — pass exactly one to say which target and which id value you're writing:

| Target | Request field | Written to | |--------|----------------|------------| | entity | entityId | identity.target: "entity", identity.targetId | | event | eventId | identity.target: "event", identity.targetId | | knowledge | knowledgeId | identity.target: "knowledge", identity.targetId |

They are never stored as flat root fields, and there is no client-facing idField concept — clients read/write identity via the identity object (and, for narrative/search context, the concept object). This package will not add a flat-id or idField public API even on request, since it would break the memorix-record.2.0 contract for every downstream consumer. See MEMORIX-DATABASE-CONVENTIONS.md for the full shape and rationale.

Internally, @x12i/memorix-writer tolerates reading older, pre-2.0 records that only have a flat entityId/eventId (see docs/GRAPH-RUNS.md § Identity resolution) so graph-run tracking keeps working during a tenant's migration window. That fallback is read-only, internal, and not exported — it does not change what gets written, and it is not something applications should rely on or target.

Collection name resolution order:

1. Explicit override (API/code parameter)
2. Write descriptor target.targetCollection
3. Entity descriptor content type collection
4. MEMORIX_ENTITIES_COLLECTION_* / MEMORIX_EVENTS_COLLECTION_* env vars
5. Write descriptor target.targetCollectionCandidates
6. Content-type slice {collectionPrefix}-{postfix} (e.g. assets-analysis)
7. Built-in defaults for known entityType values
8. Heuristic (<entityType> or <entityType>-events)
9. Verify the collection exists in the target database (skipped for dryRun / validateOnly)

For content-type slices, step 6 runs before canonical entity defaults so assets + analysis still resolves to assets-analysis unless overridden explicitly.

Generic Annotations

writeMemorixRecord and writeMemorixRecords expose generic annotation hooks that work across entity, event, and knowledge targets:

| Request field | Written shape | |---------------|---------------| | metadata | _memorix.metadata | | tags | _memorix.tags | | narratives | narratives.{key} |

Narrative keys use the same top-level narratives.{key} shape consumed by @x12i/memorix-retrieval helpers such as fetchMemorixNarrativeRecords. This is only a generic tag/write primitive; applications still own narrative detection, descriptor design, and domain-specific relation names.

Operations

| Operation | Default | Notes | |-----------|---------|--------| | add | yes | Always inserts a new record | | upsert | descriptor-gated | Requires conflict.matchBy | | patch | descriptor-gated | Updates writable fields on existing row | | replace | descriptor-gated | Full replace |

Catalox seeds

Catalog metadata for this package (write descriptors, entity descriptors) is managed in MongoDB — the memorix-catalox database. The manifest below is the source of truth for what gets applied there.

Validate the write descriptor seed:

npm run catalox:seed:write-descriptors:validate

Apply the manifest to Mongo memorix-catalox (uses MONGO_URI + MEMORIX_CATALOX_DB) — this is the normal way to publish or update descriptors:

npm run catalox:seed:write-descriptors:apply

Seed file: catalox-seeds/memorix-write-descriptors.manifest.json

Shipped write descriptors include asset-analysis-write (entity) and corpus helpers content-documents-snapshot-write / content-documents-chunk-write (knowledge target). Record builders: @x12i/memorix-corpus.

Acceptance criteria

| ID | Status | |----|--------| | AC-1 | Generic descriptor-driven write | | AC-2 | Prefix/postfix collection resolution | | AC-3 | Identity: exactly one of entityId / eventId / knowledgeId, written to identity.targetId | | AC-4 | Default operation add | | AC-5 | Upsert only when allowed | | AC-6 | Patch only when allowed | | AC-7 | Writable field allowlist / unknown fields | | AC-8 | Required fields | | AC-9 | Content body → object storage + pointer | | AC-10 | Existing content pointer | | AC-11 | Content maxBytes | | AC-12 | No secrets in descriptors | | AC-13 | Idempotency | | AC-14 | dryRun | | AC-15 | validateOnly | | AC-16 | Retrieval delegated when configured | | AC-17 | Generic metadata, tags, narrative tags, and knowledge writes |

Graph-run tracking (_graphRuns) — MRX-FRS-001

System-only APIs for Exellix jobs graph execution tracking. Domain writeMemorixRecord rejects _graphRuns in input.

import {
  markGraphRunStarted,
  markGraphRunFailed,
  writeGraphRunResult,
  clearGraphRun,
  ensureGraphRunIndexes,
} from "@x12i/memorix-writer";

| API | Purpose | |-----|---------| | markGraphRunStarted | Stamp in_progress (idempotent per jobRunId) | | markGraphRunFailed | Terminal failure stamp | | writeGraphRunResult | Upsert result doc + stamp source done (best-effort compensation) | | clearGraphRun | Force re-run via $unset | | ensureGraphRunIndexes | Opt-in planning-query indexes |

Full contract: docs/GRAPH-RUNS.md.

Job-type run tracking (_jobTypeRuns) — MRX-CR-003

Parallel stamp APIs keyed by jobTypeId (shared GraphRunEntry shape). Domain writes reject _jobTypeRuns in input.

import {
  markJobTypeRunStarted,
  markJobTypeRunCompleted,
  markJobTypeRunFailed,
  ensureJobTypeRunIndexes,
} from "@x12i/memorix-writer";

Full contract: docs/JOB-TYPE-RUNS.md.

Entity collection bootstrap — MRX-CR-005

import { initializeEntityCollections } from "@x12i/memorix-writer";

await initializeEntityCollections(client, "assets", {
  contentTypes: ["core", "inferences"],
  graphRunIndexes: true,
  jobTypeRunIndexes: true,
});

Idempotent: creates missing collections and ensures standard indexes (idx_updatedAt, idx_graphRuns, optional idx_jobTypeRuns, etc.).

Development

npm run build
npm test

Mongo collection I/O is built in (insertMemorixCollectionDocument, etc. under src/mongo/).

Publish

npm run build
npm publish --access public

Or from the x12i workspace root: ./scripts/publish-memorix-packages.sh