@x12i/web-scoper-memorix

@x12i/web-scoper-memorix

Memorix knowledge-backed persistence for @x12i/web-queries.

This package is fully automatic and Catalox-free: no descriptors, schema bootstrap, catalog, or write descriptors are required. It writes web-scoping artifacts directly to the Memorix knowledge database using one hardcoded collection, web-scoping-artifacts.

Install

npm install @x12i/web-scoper-memorix @x12i/web-queries @x12i/search-adapter

Quick Start

import { createSearchAdapter } from "@x12i/search-adapter";
import { createMemorixWebScoperFromEnv } from "@x12i/web-scoper-memorix";

// Reads MONGO_URI, EXELLIX_NAME, MEMORIX_KNOWLEDGE_DB, and TTL env vars automatically.
const scoper = await createMemorixWebScoperFromEnv();

const result = await scoper.search({
  requestId: "req-123",
  question: "{{cveId}} patch status",
  record: { cveId: "CVE-2021-44228" },
});

await scoper.close();

Explicit config is also supported:

import { createMemorixWebScoper } from "@x12i/web-scoper-memorix";

const scoper = await createMemorixWebScoper({
  searchAdapter: createSearchAdapter(),
  mongoUri: process.env.MONGO_URI,
});

Environment

MONGO_URI=mongodb+srv://...
EXELLIX_NAME=my-exellix
MEMORIX_KNOWLEDGE_DB=my-explicit-knowledge-db

WEB_SCOPER_MEMORIX_SCOPE_TTL=7d
WEB_SCOPER_MEMORIX_SEARCH_TTL=7d
WEB_SCOPER_MEMORIX_FETCH_TTL=30d
WEB_SCOPER_MEMORIX_SYNTHESIS_TTL=30d

Database resolution follows the Memorix knowledge convention:

1. MEMORIX_KNOWLEDGE_DB when set.
2. <EXELLIX_NAME>-memorix-knowledge when EXELLIX_NAME is set.
3. memorix-knowledge when neither is set.

Storage

All artifacts are stored in:

<knowledge-db>.web-scoping-artifacts

Documents use a Memorix-style knowledge envelope:

{
  "knowledgeId": "web-scoping:scope:<searchTypeKey>:<searchKey>",
  "recordId": "web-scoping:scope:<searchTypeKey>:<searchKey>",
  "capturedAt": "2026-06-28T00:00:00.000Z",
  "modifiedAt": "2026-06-28T00:00:00.000Z",
  "data": {
    "artifactKind": "scope",
    "searchTypeKey": "hash-of-template-before-rendrix",
    "searchTypeTemplate": "{{cveId}} patch status",
    "searchKey": "hash-of-rendered-search",
    "renderedSearch": "{\"question\":\"CVE-2021-44228 patch status\"}",
    "cacheKey": "stable-cache-key",
    "expiresAt": "2026-07-05T00:00:00.000Z",
    "payload": {}
  },
  "_memorix": {
    "package": "@x12i/web-scoper-memorix",
    "writeKind": "automatic-cache"
  }
}

Concrete readable content, raw provider/fetch payloads, and returned scoper results live under data. _memorix is reserved for internal write metadata.

requestId can be provided on search() and searchMany() inputs. When omitted, @x12i/web-queries generates one. @x12i/web-scoper-memorix returns that id with the result and persists it in write metadata for scope, search, fetch, and cache artifacts.

TTLs

Defaults:

• Scope results: 7d
• Search/discovery results: 7d
• URL fetch results: 30d
• Synthesized answers: 30d

Resolution order:

1. Request memorix.ttl.
2. Environment variables.
3. Code defaults.

Use memorix.forceRefresh: true to bypass cache for a single request while still saving the fresh result.

Synthesized Answers

Use saveSynthesized() to persist downstream synthesized output for a request. The caller supplies taskVariables, jobVariables, and jobTopic; the package stores all three under data.requestMetadata and does not store a question property for synthesized records.

await scoper.saveSynthesized({
  requestId: "req-123",
  taskVariables: { cveId: "CVE-2021-44228", field: "patchStatus" },
  jobVariables: { tenantId: "tenant-1", workflowId: "wf-1" },
  jobTopic: "security",
  synthesized: "Patched in Log4j 2.17.1.",
});

const allForRequest = await scoper.getSynthesized({ requestId: "req-123" });

const partialMatch = await scoper.getSynthesized({
  requestId: "req-123",
  taskVariables: { cveId: "CVE-2021-44228", field: "patchStatus" },
});

const exactMatch = await scoper.getSynthesized({
  requestId: "req-123",
  taskVariables: { cveId: "CVE-2021-44228", field: "patchStatus" },
  jobVariables: { tenantId: "tenant-1", workflowId: "wf-1" },
  jobTopic: "security",
});

getSynthesized() can filter by any subset of taskVariables, jobVariables, and jobTopic. Returned rows include match.partial, which is true when fewer than all three filters were supplied and false when all three filters were supplied.

Development

npm run build --workspace=@x12i/web-scoper-memorix
npm run test --workspace=@x12i/web-scoper-memorix
npm run test:integration --workspace=@x12i/web-scoper-memorix

Integration tests require MONGO_URI and use a test collection name.

Core Package Wiring

@x12i/web-scoper-memorix keeps its package name, but it wraps and depends on @x12i/web-queries. Use @x12i/web-queries directly for stateless search, and use this package when the same search flow should persist scope, search, and fetch artifacts to Memorix.