@x12i/memorix-mongo

Mongo data tier for Memorix: namespaced collection discovery, entity binding, live collection reads, and job memory context resolution.

Exports

| API | Purpose | |-----|---------| | listLiveEntityCollections, snapshotEntitySources | Discover collections for an entity | | readEntityCollectionDocuments, buildRecordLookupQuery | Read/filter documents | | ContextQuery, JobMemoryContextEntry | Declarative queries + optional preview entry type | | buildContextQueryMongoFilter | Turn filters + input into a Mongo query | | resolveJobMemoryContext | Fetch related records → jobMemory.context object keyed by alias | | createJobMemoryContextResolver | Factory for worker resolveContext hooks |

Job memory context

Jobs (and graph runs) can attach 0..n context queries against Memorix source collections. Authoring (graph model / job def) keeps those as a list (jobMemory.context[] / contextQueries). At run time the host resolves them into the shared object bucket:

"jobMemory": {
  "context": {
    "peer-subnets": [ /* matching documents */ ]
    // plus Hippox keys, contextSources, promoted discovery / associated*, …
  }
}

Do not write host-filled leaves at jobMemory root (discovery, associated*, _legacy).

Graph-engine forwards runtime.jobMemory on every RunTaskRequest.jobMemory. No ai-tasks changes are required — tasks already read jobMemory.

Declarative query shape (ContextQuery)

type ContextQuery = {
  alias: string;
  entityName?: string;       // defaults to input._memorixRef.entityName
  contentType: string;       // source collection postfix
  target?: 'entity' | 'event';
  filter: Array<{
    key: string;
    source: 'input' | 'literal';
    inputField?: string;     // when source === 'input', dot-path on job input
    value?: unknown;         // when source === 'literal'
  }>;
  limit?: number;            // default 50
};

Resolve at run time

import { createMemorixRetrievalStackFromEnv } from '@x12i/memorix-retrieval';
import { resolveJobMemoryContext } from '@x12i/memorix-mongo';

const { client } = await createMemorixRetrievalStackFromEnv(/* … */);
const jobMemory = await resolveJobMemoryContext(client, {
  input: jobRun.input,
  contextQueries: jobRun.contextQueries,
});
// pass to executeGraph: runtime: { input, jobMemory, … }

Preview (same resolver jobs-ui uses):

const jobMemory = await resolveJobMemoryContext(retrieval, {
  input: { region: 'eu', _memorixRef: { … } },
  contextQueries: [{ alias: 'peers', contentType: 'snapshots', filter: [...] }],
});

graphs-studio integration

See docs/STUDIO_INTEGRATION.md.

Summary for studio:

1. Author default queries on the graph model as jobMemory.context[] once CRS-FRS-003 ships in graphenix-format. Until then, store under metadata.extensions['exellix.jobMemory/v1'].context.
2. Preview with resolveJobMemoryContext(retrieval, { input, contextQueries }) using a sample input record.
3. Persist per-job overrides via @exellix/jobs-db (JobDef.contextQueries / JobRun.contextQueries) when enqueueing from studio or jobs-ui.
4. Pair with @exellix/catalox-graphs for graph catalog load/save (see catalox-graphs docs/STUDIO_INTEGRATION.md).

Env

Same as other Memorix packages: MONGO_URI, Catalox/Firebase vars via @x12i/memorix-retrieval.

Related packages

| Package | Role | |---------|------| | @exellix/jobs-db | Stores contextQueries on JobDef / JobRun (types re-exported from here) | | @exellix/jobs | Worker wires createJobMemoryContextResolver → runtime.jobMemory | | @exellix/jobs-ui | Wizard + POST /api/context/preview (reference host) | | @exellix/catalox-graphs | Graph catalog for studio |