@x12i/memorix

Memorix Mongo I/O for entity collections ({entityName}-{suffix}), registry (_memorix-entities), discovery, Catalox catalog helpers, reports, and CLI.

Documentation

| Doc | Purpose | |-----|---------| | docs/host-integration.md | Env vars, discovery order, Catalox wiring, scoped namespace APIs, record IDs, JSON serialization, health | | docs/specs.md | Package design specification (metadata vs data, content types, testing matrix) |

Public surfaces (quick map)

| Area | Main exports | |------|----------------| | Tier lifecycle | createMemorixDataTier, resolveMemorixTierEnv, DEFAULT_MEMORIX_DATABASE_NAME | | Entity CRUD / list | countMemorixEntityDocuments, listMemorixEntityDocuments, getMemorixEntityDocument, getMemorixEntityDocumentByRecordId, bindMemorixRecords | | Scoped namespace (Explorer-style) | listMemorixScopedEntityTypes, listMemorixScopedDocuments, countMemorixScopedDocuments, assertMemorixScopedNamespace | | Namespace match helpers | memorixScopedNamespaceMatchFilter, mergeMemorixMongoFilters, resolveMemorixScopedNamespaceFromEnv | | Record IDs | resolveMemorixRecordIdFilter, resolveMemorixRecordIdForFilter, normalizeMemorixFilter | | JSON for HTTP | serializeMemorixDocumentForJson | | Health | getMemorixTierHealth | | Discovery | discoverMemorixEntityNames, discoverMemorixEntityNamesWithCatalox |

Database name (do not infer from MONGO_URI)

The Memorix database is memorix_db / MEMORIX_DB, or the package default DEFAULT_MEMORIX_DATABASE_NAME ("memorix"). Never parse the path segment of MONGO_URI (e.g. …/kiDB?…) to choose that database — it is unrelated to where {entity}-{suffix} collections live and has caused repeated production bugs.

Quick start

import {
  createMemorixDataTier,
  listMemorixScopedEntityTypes,
  listMemorixScopedDocuments,
  countMemorixScopedDocuments,
  getMemorixEntityDocumentByRecordId,
  resolveMemorixRecordIdFilter,
  serializeMemorixDocumentForJson,
  getMemorixTierHealth,
  discoverMemorixEntityNamesWithCatalox,
} from "@x12i/memorix";

const tier = createMemorixDataTier();
await tier.init();
try {
  const types = await listMemorixScopedEntityTypes(tier);
  const page = await listMemorixScopedDocuments(tier, {
    includeTotal: true,
    limit: 25,
  });
  const doc = await getMemorixEntityDocumentByRecordId(tier, {
    entityName: "assets",
    contentType: "scoped",
    recordId: "507f1f77bcf86cd799439011",
  });
  const health = await getMemorixTierHealth(tier);
} finally {
  await tier.close();
}

Scoped surface helpers require a resolved namespace (MEMORIX_SCOPED_NAMESPACE, TARGET_NAMESPACE, or XMEMORY_NAMESPACE). See docs/host-integration.md.

Testing

npm test

Vitest picks up src/**/*.test.ts. Each host-facing addition has a dedicated test file:

| Test file | What it covers | |-----------|----------------| | src/scoped-namespace.test.ts | Namespace env precedence, memorixScopedNamespaceMatchFilter, mergeMemorixMongoFilters | | src/scoped-surface.test.ts | listMemorixScopedEntityTypes, listMemorixScopedDocuments, countMemorixScopedDocuments, assertMemorixScopedNamespace | | src/id-normalize.test.ts | resolveMemorixRecordIdFilter / resolveMemorixRecordIdForFilter | | src/entity-documents-record.test.ts | getMemorixEntityDocumentByRecordId | | src/env.test.ts | resolveMemorixTierEnv scoped fields (memorixScopedNamespace, memorixScopedNamespaceFieldPaths) | | src/discovery.test.ts | discoverMemorixEntityNamesWithCatalox, env-based discoverMemorixEntityNames | | src/tier-health.test.ts | getMemorixTierHealth | | src/json-serialize.test.ts | serializeMemorixDocumentForJson |

Integration tests against a real cluster live under tests/live. Run:

npm run test:live

Loads .env via scripts/check-live-env.mjs and tests/live imports. Uses an ephemeral database name (memorix_live_<pid>_<time>) unless you set MEMORIX_LIVE_TEST_DB to reuse a dedicated DB (tests call dropDatabase() in afterAll).

License

MIT (align with sibling @x12i/* packages).