@x12i/memorix-retrieval

@x12i/memorix-retrieval is the read-side runtime data tier for Memorix.

It loads Catalox descriptors, inventories Mongo databases, resolves collection bindings, reads mapped and unmapped records, executes list/slice descriptors, composes item views, builds graph/inventory views, and returns Explorer/API-ready JSON.

Positioning

| Package | Role | |---------|------| | @x12i/memorix-retrieval | Runtime reads/views — Catalox descriptors + Mongo reads → lists, items, inventory, slices, graph, health | | @x12i/memorix-descriptors | Descriptor writes, slice schema, inventory ignore policy | | @x12i/memorix-completion | Payload writes |

Retrieval does not write descriptors and does not write Memorix payload documents.

Quick start

Set MONGO_URI. Database names, entity/event/knowledge routing, and collection resolution are handled internally.

MONGO_URI=mongodb://localhost:27017

Host apps (Catalox + Mongo)

import {
  createMemorixRetrievalStackFromEnv,
  fetchMemorixListForEntity,
  fetchMemorixItemForEntity,
} from "@x12i/memorix-retrieval";

const { client, appId } = await createMemorixRetrievalStackFromEnv({
  cataloxContext: { superAdmin: true, actor: { type: "service", id: "my-api" } },
});

const list = await fetchMemorixListForEntity(client, {
  entityName: "assets",
  page: { limit: 50, offset: 0 },
});

const item = await fetchMemorixItemForEntity(client, {
  entityName: "assets",
  entityId: "10.150.68.31",
});

await client.close?.();

Targets: entity, event, knowledge

| Target | Default DB | Identity field | Env override | |--------|------------|----------------|--------------| | entity | memorix-entities | entityId | MEMORIX_ENTITIES_DB | | event | memorix-events | eventId | MEMORIX_EVENTS_DB | | knowledge | memorix-knowledge | knowledgeId | MEMORIX_KNOWLEDGE_DB |

import {
  resolveMemorixDatabaseName,
  resolveMemorixIdentityField,
  resolveMemorixTargetFromDescriptor,
} from "@x12i/memorix-retrieval";

Unified inventory

One API powers Catalox-first and DB-first Explorer inventory modes:

import { buildMemorixUnifiedInventory } from "@x12i/memorix-retrieval";

const inventory = await buildMemorixUnifiedInventory(client, {
  sourceLens: "catalox-first", // or "db-first"
  targets: ["entity", "event", "knowledge"],
  includeExactCounts: false,
  includeSamples: true,
});

Returns normalized rows, issues, per-target summaries, and suggested actions.

Every inventory result includes source (MemorixRuntimeSourceRef), targetBindings, and per-row sources explaining descriptor and Mongo provenance.

Source-aware runtime provenance

Retrieval never returns anonymous data. Every Explorer-facing result can explain where it came from:

import {
  getSourceAwareMemorixRetrievalHealth,
  type MemorixRuntimeSourceRef,
  type RuntimeSourceAware,
} from "@x12i/memorix-retrieval";

const health = await getSourceAwareMemorixRetrievalHealth(client, {
  includeInventory: true,
});

// health.source.sourceClass === "runtime-projection"
// health.mongo.targets.knowledge.status may be "not-configured" or "empty" (non-fatal)

Key types: MemorixRuntimeSourceRef, RuntimeSourceAware<T>, MemorixTargetDbBinding, MemorixRequiredUserInput.

Legacy Catalox catalogs (memorix-entities, memorix_entity_content_types, knowledge) are not used for descriptor-driven reads.

Catalox-first vs DB-first

• Catalox-first — start from entity descriptors and declared content types; append orphan Mongo collections.
• DB-first — start from Mongo collections (parsed with last-dash rule); append missing Catalox-declared collections.

Both lenses use the same MemorixUnifiedInventory shape.

Last-dash collection parsing

Collection names follow <objectName>-<contentType> where the last dash is the separator (object names may contain dashes):

import { parseMemorixCollectionName } from "@x12i/memorix-retrieval";

parseMemorixCollectionName("topology-cidr-graphs-scoped");
// objectName = "topology-cidr-graphs", contentType = "scoped"

Raw collection records

Read Mongo directly without a Catalox descriptor:

import { fetchMemorixRawCollectionRecords } from "@x12i/memorix-retrieval";

const raw = await fetchMemorixRawCollectionRecords(client, {
  target: "entity",
  collectionName: "assets-snapshots",
  page: { limit: 50, offset: 0 },
});

Open records from inventory rows with descriptor or raw fallback:

import { fetchMemorixCollectionRecords } from "@x12i/memorix-retrieval";

const records = await fetchMemorixCollectionRecords(client, {
  entityName: "assets",
  contentType: "snapshots",
  mode: "auto",
});

Slice execution

List descriptors with kind: "slice" are executable saved views:

Slice descriptors use the canonical shape from @x12i/memorix-descriptors (entityName, target, contentType, filter, ui.group). Create slices with createSliceDescriptor in descriptors; execute them here with fetchMemorixSliceRecords.

import {
  fetchMemorixSlices,
  fetchMemorixSliceRecords,
  fetchMemorixSliceItem,
  loadMemorixSliceDescriptor,
} from "@x12i/memorix-retrieval";

const slices = await fetchMemorixSlices(client, { includeHealth: true });
const page = await fetchMemorixSliceRecords(client, {
  sliceId: "critical-vulnerabilities",
  page: { limit: 50, offset: 0 },
});

Record identity

import { resolveMemorixRecordIdentity } from "@x12i/memorix-retrieval";

const { id, identityField, source } = resolveMemorixRecordIdentity("knowledge", record);

Resolution order: descriptor identity field → target default (entityId / eventId / knowledgeId) → id → Mongo _id.

Health model

import { getMemorixRetrievalHealth } from "@x12i/memorix-retrieval";

const health = await getMemorixRetrievalHealth(client, { includeInventory: true });
// health.catalox, health.mongo.targets, health.descriptors, health.inventory

Documentation

| Doc | Purpose | |-----|---------| | DATA-TIER-CONTRACT.md | Public API surface (what hosts may call) | | XRONOX-DATA-TIER-REQUIREMENTS.md | Xronox API/env requirements for Memorix data tier | | MEMORIX-CATALOX-CONTRACTS.md | Descriptor catalogs, JSON formats, cross-component sync | | MEMORIX-DATABASE-CONVENTIONS.md | Mongo DB names, collections, env vars | | EXPLORER-HOST-APIS.md | Graph, raw reads, inventory, slices (Explorer hosts) |

Advanced (optional)

| Option / env | Purpose | |--------------|---------| | MEMORIX_ENTITIES_DB / MEMORIX_EVENTS_DB / MEMORIX_KNOWLEDGE_DB | Non-default database names | | MEMORIX_ENTITIES_COLLECTION_* / MEMORIX_EVENTS_COLLECTION_* / MEMORIX_KNOWLEDGE_COLLECTION_* | Per-type collection overrides | | CATALOX_APP_ID / MEMORIX_APP_ID | Catalox app namespace (default: memorix) | | memorixDb | Code overrides for entity/event/knowledge DB names | | xronox | Inject a pre-configured Xronox client instead of built-in Mongo reads |

Entity descriptors declare target: "entity" | "event" | "knowledge" (default entity).

Catalox seeds

Source of truth: catalox-seeds/inputs/

npm run catalox:seed:build
npm run catalox:seed:memorix-retrieval:validate
npm run catalox:seed:memorix-retrieval:apply
npm run catalox:seed:ensure

Build, test, and live smoke

npm run build
npm test

Live checks (require .env with MONGO_URI and Catalox/Firestore credentials):

npm run mongo:check-collections
npm run mongo:inventory -- --sourceLens db-first --targets entity,event,knowledge
npm run mongo:inventory -- --sourceLens catalox-first --targets all
npm run mongo:inventory -- --includeExactCounts
npm run smoke:retrieval -- --health --source-aware
npm run smoke:retrieval -- --inventory --sourceLens db-first
npm run smoke:retrieval -- --raw-records --target entity --collection assets-snapshots --limit 5
npm run smoke:retrieval -- --collection-records --entity assets --contentType snapshots --mode auto
npm run smoke:retrieval -- --slice critical-vulnerabilities-list --limit 5
npm run smoke:retrieval -- --graph --sourceLens db-first --includeInventory

Publish

npm run build && npm test && npm publish