@x12i/memorix-explorer-api

@x12i/memorix-explorer-api

HTTP API for Memorix Explorer — a Fastify server that exposes read and write endpoints over MongoDB and Catalox descriptors.

This package is a thin HTTP layer on top of:

Package	Role in this API
@x12i/memorix-retrieval	All reads — inventory, lists, items, narratives, agents, health
@x12i/memorix-associator	Associated snapshot property metadata and storage-to-client associated aliases
@x12i/memorix-descriptors	List descriptor mutations; entity descriptor narratives catalog + root property catalog compute
@x12i/memorix-writer	Record writes via write descriptors

The React UI lives in @x12i/memorix-explorer (sibling package). You can run this API standalone, embed it in another host, or serve the built Explorer UI from the same process.

Documentation

Guide	Topic
docs/README.md	Documentation index
Consuming Memorix data	Read-only API — snapshots, records, lists, narratives, inventory, Skills cards
Advanced APIs	Writes, enrichment, associations, metadata, pipeline registry

---

Architecture

Client (browser, curl, automation)
  ↓ HTTP /api/explorer/*
memorix-explorer-api (Fastify)
  ↓ getRetrievalStack()     → @x12i/memorix-retrieval + Catalox + Mongo (Xronox)
  ↓ getDescriptorAdmin()    → @x12i/memorix-descriptors (list writes, narratives catalog, rootPropertyCatalog compute)
  ↓ getWriterClient()       → @x12i/memorix-writer (POST /records/write)
MongoDB cluster (payload + metadata)
  memorix-entities / memorix-events / memorix-knowledge  — record payloads (Xronox)
  memorix-catalox — Catalox descriptor metadata (lists, object types, items)

Descriptor boundary: list descriptors and authored narrative catalog entries on entity descriptors are writable through this API (when MEMORIX_EXPLORER_ENABLE_METADATA_WRITES=true). Full Catalox catalog manage + execute lives in @x12i/memorix-catalox-api (:5180). GET /catalogs* on Explorer returns 410 Gone — use /api/catalox/catalogs instead.

---

Requirements

• Node.js ≥ 20
• MongoDB reachable via MONGO_URI (payload databases + memorix-catalox metadata database)
• Catalox metadata stored in Mongo (MEMORIX_CATALOX_DB, default memorix-catalox) — same cluster as MONGO_URI
• Optional: OpenRouter or Gemini API key for AI-assisted list suggestions

---

Quick start

From this package directory:

npm install

# Create .env with at least MONGO_URI (and optional MEMORIX_CATALOX_DB; see Environment below).
# In the monorepo you can copy from ../memorix-explorer/.env as a starting point.

# Apply Catalox seeds for entity/list/item descriptors (once per app/environment)
npm run catalox:seed:memorix-retrieval:apply

# Start the API server (default port 5181)
npm run dev

Verify:

curl -s http://127.0.0.1:5181/health                                     # open — no token
curl -s http://127.0.0.1:5181/api/explorer/health \
  -H "Authorization: Bearer $EXPLORER_API_TOKEN" | jq '.ok, .memorixDb'   # token needed if EXPLORER_API_TOKEN is set

API base URL (local): http://localhost:5181/api/explorer API base URL (deployed): https://explorer.neociso.com/api/explorer

All routes documented below are relative to that base unless noted. See Authentication for the bearer token.

---

Authentication

Two modes — Authix (browser + bearer sessions) and static M2M bearer — are mutually exclusive guards on /api/explorer/*.

Authix (recommended for deployed UI)

When AUTHIX_API_URL and AUTHIX_API_KEY are set (or AUTHIX_AUTH_MODE=app / sso), Authix protects all /api/* routes except the public auth allowlist (/api/auth/login, /api/auth/sso/*, etc.). Browser users log in via POST /api/auth/login (password) or SSO; the session is an httpOnly cookie. Machine callers can send Authorization: Bearer <authix-token>.

EXPLORER_API_TOKEN is ignored when Authix is enabled — do not set both unless you intend Authix only.

Variable	Description
AUTHIX_API_URL	Authix service base URL (e.g. https://authix.x12i.com)
AUTHIX_API_KEY	Service API key (x-authix-api-key)
AUTHIX_AUTH_MODE	app (password login), sso, or disabled
AUTHIX_ADMIN_USERNAME / AUTHIX_ADMIN_PASSWORD	Operator credentials for app mode
AUTHIX_APP_ID	App id registered in Authix (default memorix-explorer)

Static M2M bearer (Authix disabled only)

When Authix is disabled (AUTHIX_AUTH_MODE=disabled and no AUTHIX_API_URL), you may set EXPLORER_API_TOKEN to require a static bearer on /api/explorer/* only:

curl -s https://explorer.neociso.com/api/explorer/inventory/summary \
  -H "Authorization: Bearer $EXPLORER_API_TOKEN"

• Exempt (no token): GET /health, /api/auth/*, and OPTIONS preflight.
• Missing/incorrect token → 401 { "error": "unauthorized" }.
• Constant-time compared shared secret — not a JWT. Store in deployment secrets (not in this repo).
• When EXPLORER_API_TOKEN is unset, /api/explorer/* is open.

Deployed note: explorer.neociso.com sets EXPLORER_API_TOKEN in server environment (outside this repo). If Authix is also configured there, redeploy with this fix so /api/auth/login is reachable again.

---

Running the server

Development

npm run dev          # tsx src/cli.ts serve — loads .env from cwd or ../memorix-explorer/.env

Production

npm run build
npm run serve        # node dist/cli.js serve

CLI (after build or via npx)

npx memorix-explorer-api serve

Programmatic embedding

import {
  createMemorixExplorerApp,
  startMemorixExplorerHttp,
  EXPLORER_API_PREFIX,
} from "@x12i/memorix-explorer-api";

// Start listening
const { url, close } = await startMemorixExplorerHttp({
  port: 5181,
  publicDir: "/path/to/built/explorer-ui", // optional — serves static SPA + fallback
});
console.log(`Listening on ${url}${EXPLORER_API_PREFIX}`);

// Or integrate into an existing Fastify/host setup
const { app } = await createMemorixExplorerApp({ logger: true });
await app.listen({ port: 5181, host: "0.0.0.0" });

When EXPLORER_PUBLIC_DIR (or publicDir option) points at a built Explorer UI (index.html present), non-API routes serve the SPA; API routes remain under /api/explorer.

---

Environment variables

Required

Variable	Description
MONGO_URI	MongoDB connection string for the cluster (alias: MONGO_CONNECTION_STRING)

Mongo target databases

Override only when your deployment uses non-default database names. See Memorix Database Conventions.

Variable	Default	Target
MEMORIX_ENTITIES_DB	memorix-entities	Entity records (target=entity)
MEMORIX_EVENTS_DB	memorix-events	Event records (target=event)
MEMORIX_KNOWLEDGE_DB	memorix-knowledge	Knowledge records (target=knowledge, optional)
MEMORIX_OPERATIONAL_DB	memorix-operational	Platform ops (*-failed, schema observation, pipeline-registry-parts)
MEMORIX_PIPELINE_REGISTRY_DB	(falls back to operational)	Optional override for remote pipeline plugin registry only
MEMORIX_CATALOX_DB	memorix-catalox	Catalox descriptor metadata (lists, object types, items)

Catalox

Variable	Default	Description
CATALOX_APP_ID	memorix	Catalox app id (alias: MEMORIX_APP_ID)

Catalox metadata uses the same MONGO_URI cluster; database name defaults to memorix-catalox.

Server

Variable	Default	Description
EXPLORER_API_PORT	5181	HTTP port (fallback: PORT)
EXPLORER_API_TOKEN	(unset)	Static M2M bearer on /api/explorer/* when Authix is disabled only. See Authentication
EXPLORER_PUBLIC_DIR	./public if present	Path to built Explorer static files

Optional — AI list suggestions

Variable	Description
OPENROUTER_API_KEY	Enables richer confidence on GET /lists/suggest?mode=ai
GEMINI_API_KEY	Alternative AI provider for the same route

Smoke / test helpers

Variable	Default	Description
SMOKE_BASE	http://127.0.0.1:5181/api/explorer	Base URL for smoke scripts
SMOKE_STRICT_INVENTORY	off	Fail inventory smoke if no rows
SMOKE_STRICT_ENTITIES	off	Fail entity smoke if graph/records empty

---

HTTP conventions

Base path and methods

• Explorer API routes: /api/explorer + path (e.g. /api/explorer/health).
• Process liveness: GET /health → { "ok": true } (does not check Mongo/Catalox).
• Supported methods on /api/explorer/*: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS.
• OPTIONS returns 204 with no body.
• Responses include Cache-Control: no-store.
• Request body limit: 1 MB (JSON bodies for POST/PATCH/PUT).

Content type

Send JSON bodies with Content-Type: application/json. Responses are JSON unless serving static UI.

Errors

Status	Meaning
400	Missing/invalid query params or JSON body
401	Missing/incorrect bearer token (when EXPLORER_API_TOKEN is set) — body { "error": "unauthorized" }
404	Unknown route or missing list/narrative
422	Write validation failed (POST /records/write)
500	Unexpected server error — body { "error": "..." }

Pagination

Shared query parameters for list-style endpoints:

Param	Alias	Default	Description
limit	—	50	Page size (clamped 1–500)
offset	skip	0	Rows to skip
includeTotal	—	false	Include total count in page.total when supported

Search

Param	Alias	Description
searchText	q	Full-text search when supported by the underlying list

Sorting

Repeated sort params (preferred for compound sort):

GET /records/collection?entityName=assets&sort=severity:desc&sort=entityId:asc

Legacy single sort:

Param	Alias
sortProperty	sortPath
sortDirection	asc or desc

Filtering

Repeat filter as property:operator:value:

GET /records/collection?entityName=assets&filter=severity:gte:7&filter=status:eq:open

Operator	Value notes
eq, ne, gt, gte, lt, lte	Scalar comparison
in, nin	Comma-separated list
exists	true/false (default true if value omitted)
regex	String pattern

Targets

Many routes accept target: entity, event, or knowledge. Omit or use all where documented to include all configured targets.

---

API reference

Health

GET /health

Memorix-aware health check — Mongo bindings, Catalox discovery, warnings, and optional inventory summary.

Query	Description
includeInventory	1 / true — attach inventory summary counts

Example:

curl -s "$BASE/health?includeInventory=1"

Response highlights:

{
  "ok": true,
  "generatedAt": "2026-07-01T12:00:00.000Z",
  "mongoUriConfigured": true,
  "memorixDb": "memorix-entities + memorix-events",
  "discoverySample": ["assets", "vulnerabilities"],
  "sourceAware": { "...": "full retrieval health object" },
  "retrieval": {
    "appId": "memorix",
    "entitiesCatalogId": "memorix-object-type-descriptors",
    "discoverySource": "catalox",
    "catalogFallback": false
  },
  "inventorySummary": {
    "orphans": 0,
    "declaredEmpty": 1,
    "matchedPopulated": 12,
    "missingCollections": 0
  },
  "warnings": [],
  "errors": []
}

Use this endpoint before debugging empty lists or inventory issues.

---

Inventory

Unified inventory and entity graph for Explorer navigation.

GET /inventory/collections · GET /inventory/summary

Same handler — returns MemorixUnifiedInventory rows, issues, and per-target summaries.

Query	Description
sourceLens	catalox-first (descriptor-first) or db-first (Mongo-first). Default: db-first
target	entity, event, knowledge, or all
includeExactCounts	1 / true — run exact countDocuments (slower)
includeIgnored	Include collections marked ignored in inventory policy

Example:

curl -s "$BASE/inventory/collections?sourceLens=db-first&includeExactCounts=1"

Each row includes provenance (source, sources), suggested UI actions (actions), and navigation hints (navigation.primaryNarrative when mapped).

GET /inventory/issues

Subset of unified inventory — { issues, summary } only.

GET /inventory/graph

Entity relationship graph for the Entities view.

Query	Default	Description
includeOrphans	true	Include orphan Mongo collections in orphanEntities

Example:

curl -s "$BASE/inventory/graph"

Returns entities, orphanEntities, memorixDb, discovery, and catalogRelations.

---

Records (read)

GET /records/collection

Entity collection — descriptor-backed rows, raw Mongo, or auto-detected mode.

Query	Required	Description
entityName	Yes	Object type name (e.g. assets)
target	No	entity / event / knowledge
listId	No	List descriptor id (alias: listDescriptorId)
contentType	No	Restrict to one content type
collectionName	No	Explicit collection override
mode	No	descriptor | raw | auto (default auto)
+ pagination, sort, filter, search		See HTTP conventions

Example:

curl -s "$BASE/records/collection?entityName=assets&mode=auto&limit=10&includeTotal=1"

GET /records/raw-collection

Read Mongo documents directly without list descriptor projection.

Query	Required
target	Yes
collectionName	Yes
+ pagination, sort, search

GET /records/full

Full record across content types (multi-collection compose).

Query	Required
entityName	Yes
One of recordId, entityId, eventId, knowledgeId	Yes — prefer recordId when the object type uses it
contentTypes	No — comma-separated; default all declared types

GET /records/item

Item descriptor view — sections and fields for a single record.

Query	Required
entityName	Yes
One of recordId, entityId, eventId, knowledgeId	Yes — prefer recordId when the object type uses it
itemDescriptorId	No — default item for entity

Skills cards (analysis / decisions) — two generic calls

List ids are Catalox metadata, not routes baked into this API. Discover them, then page + open:

# 0) Discover lists for the entity (ids come from Catalox)
curl -sS "$BASE/lists?entityName=assets" | jq '.[] | {id, title, leadingContentType}'

# 1) Page of cards — use the list id returned above
curl -sS "$BASE/lists/$LIST_ID/records?limit=50&includeTotal=1"

# 2) Open card / Explain Decision
curl -sS "$BASE/records/item?entityName=assets&recordId=$ID"

Platform (stable)	Instance (Catalox lists catalog)
GET /lists?entityName=	Which lists exist, their id / title / leadingContentType
GET /lists/{listId}/records	Card fields authored on that list descriptor
GET /records/item	Item sections/fields from memorix-item-descriptors

Pick Skills lists by leadingContentType of decisions or analysis (and UI title). Do not hardcode list ids in client code unless you intentionally pin to a known Catalox item for one deployment.

Notes for clients

• Nested decision blobs (e.g. assets data.exploitability → OT decisionExploitability) are usually item fields, not list fields — use /records/item (or /records/full?...&contentTypes=decisions).
• Prefer /records/item for Skills open; use /records/full only when you need raw multi-CT documents.
• A given deployment may seed example list ids (e.g. neo); treat those as catalog data. Field maps for the neo instance: .operational/web-client-intergration/02-skills-card-lists.md.

See also docs/consuming-memorix-data.md.

Ad-hoc Assets Exploitability (no Catalox list / item ids)

Same use case without passing Catalox descriptor ids from client code:

# 1) Page decisions
curl -sS "$BASE/records/collection?entityName=assets&contentType=decisions&limit=50&includeTotal=1"

# 2) Open — exploitability = data.exploitability (default item; or use /records/full)
curl -sS "$BASE/records/item?entityName=assets&recordId=$ID"
# curl -sS "$BASE/records/full?entityName=assets&recordId=$ID&contentTypes=snapshots,decisions"

Full field map and paths: docs/consuming-memorix-data.md § Ad-hoc Assets Exploitability.

GET /records/content

Fetch content for a specific item field (e.g. markdown body, external pointer).

Query	Required
entityName	Yes
fieldPath	Yes (alias: contentKey)
One of entityId, eventId, knowledgeId	Yes
itemDescriptorId	No

GET /records/raw-item

Single Mongo document by id from a named collection.

Query	Required
target	Yes
collectionName	Yes
recordId	Yes
idField	No — override identity field

GET /records/workspace

Cross-entity workspace list (pinned / multi-entity views).

Query	Description
workspaceListId	Workspace list descriptor id
entityName	Filter to one entity
+ pagination, sort, search

---

Snapshots And Associated Data

Normalized snapshot reads expose the client consumption contract from the operational guide. These routes keep storage-compatible names available while presenting associatedInferred as client-facing discovery.

GET /snapshots/{objectType}/{recordId}

Returns a normalized snapshot view:

{
  "objectType": "assets",
  "contentType": "snapshots",
  "recordId": "asset-1",
  "concept": { "...": "..." },
  "data": { "...": "native snapshot data" },
  "analytics": { "...": "optional rollups" },
  "enrichment": { "...": "optional sourced values" },
  "insights": { "...": "optional judgments" },
  "system": { "...": "from _system" },
  "associated": {
    "data": [{ "...": "associatedData[]" }],
    "discovery": [{ "...": "associatedInferred[]" }],
    "analysis": [{ "...": "associatedAnalysis[]" }],
    "custom": {
      "associatedAssets": [{ "...": "custom associated copy" }]
    },
    "properties": []
  },
  "storage": {
    "associatedAliases": {
      "associated.data": "associatedData",
      "associated.discovery": "associatedInferred",
      "associated.analysis": "associatedAnalysis"
    }
  }
}

Query	Description
include	Comma-separated buckets: data, analytics, enrichment, insights, system, associated
idField	Override lookup field. Defaults to recordId

GET /snapshots/{objectType}/{recordId}/associated

Returns only the normalized associated view plus associated-property metadata.

GET /snapshots/{objectType}/{recordId}/associated/{propertyName}

Returns one associated property. propertyName may be a storage name or client alias:

Client/API name	Storage property
data	associatedData
discovery	associatedInferred
inferred	associatedInferred
analysis	associatedAnalysis
associatedAssets or any associated*	same storage property

GET /snapshots/{objectType}/associated-properties

Returns managed plus discovered associated-property metadata for snapshot records. Discovery samples the snapshot collection and treats any root-level associated* property as a valid associated property.

Query	Description
limit / offset	Sample page for discovery
includeTotal	Include total count from the raw collection read

Important semantics:

• Associated arrays are copied read models from linked record data.
• Legacy properties (associatedData, associatedDiscovery, …) may include inline recordId / contentType.
• v2 properties (associated<ObjectType><ContentType>) use flat copied data; optional traceability lives in item-level _system.association when enabled. See memorix-pipeline/docs/association-format.md.
• Refresh resolves snapshot → snapshot first, then fetches non-snapshot content by matched snapshot recordId when applicable.
• Refresh is one-way: linked content data → source snapshot associated*[].
• Associated arrays do not include linked record _system, analytics, enrichment, or insights; query the linked collection directly when those buckets are needed.
• Item-level _system inside associated arrays is stripped from the default snapshot API view; pass include=system to retain it.
• Root buckets that do not start with associated are still consumable (analytics, enrichment, insights, _system) and can be resolver inputs when configured.

Association refresh (operations)

Method	Route	Description
POST	/associations/plan	Dry-run association plan with fingerprint
POST	/associations/apply	Apply plan (requires expectedPlanFingerprint when configured)
POST	/associations/verify	Verify associated array shapes on source collection

---

Lists (read)

GET /lists?entityName={name}

Discover list descriptors registered for an entity.

Response:

{
  "entityName": "assets",
  "lists": [
    {
      "id": "assets-default",
      "title": "Assets",
      "entity": "assets",
      "leadingContentType": "snapshots",
      "fieldCount": 8
    }
  ]
}

GET /lists/{listId}

Full list descriptor document from Catalox.

GET /lists/{listId}/records

Execute the list — same pagination, sort, filter, and search conventions as /records/collection.

GET /lists/suggest?entityName={name}

Suggest extensions and analytics fields for list authoring.

Query	Description
entityName	Required
listId	Optional — exclude already-configured extensions/analytics
mode	automation (default) or ai (requires API key)

Response shape:

{
  "entityName": "assets",
  "listId": null,
  "mode": "automation",
  "extensions": [
    {
      "kind": "extension",
      "contentType": "analysis",
      "mode": "extendFields",
      "confidence": "high",
      "reason": "Content type \"analysis\" is declared on entity but not joined in this list"
    }
  ],
  "analytics": [
    {
      "kind": "analytics",
      "field": "countAnalysis",
      "collection": "assets-analysis",
      "joinBy": "entityId",
      "metric": { "op": "count" },
      "confidence": "medium",
      "reason": "Count documents in analysis per record"
    }
  ]
}

---

Lists (write)

All list mutations go through @x12i/memorix-descriptors executeDescriptorMutation. Bodies must match MemorixListDescriptor validation.

Method	Path	Operation
POST	/lists	Create list descriptor → 201
PATCH	/lists/{listId}	Update list descriptor
DELETE	/lists/{listId}	Remove list descriptor
POST	/lists/{listId}/extensions	Add extension join
DELETE	/lists/{listId}/extensions/{contentType}	Remove extension
POST	/lists/{listId}/analytics	Add analytics field
DELETE	/lists/{listId}/analytics/{field}	Remove analytics field
PUT	/lists/{listId}/sort	Set compound default sort

Create list (POST /lists): pass a full list descriptor object (must include id, entity, leadingContentType, fields, etc.). See seed examples under memorix-descriptors/catalox-seeds/inputs/list-descriptors/.

Set sort (PUT /lists/{listId}/sort):

{
  "sort": [
    { "property": "severity", "direction": "desc" },
    { "property": "entityId", "direction": "asc" }
  ]
}

Mutation failures return 400 with { "error": "...", "result": { ... } }.

---

Record writes

POST /records/write

Write Memorix payload documents via a Catalox write descriptor.

Single record:

{
  "writeDescriptorId": "asset-analysis-write",
  "entityId": "10.150.68.31",
  "operation": "upsert",
  "input": { "riskLevel": "HIGH", "summary": "..." },
  "metadata": { "source": { "uri": "file://scan.json" } },
  "dryRun": false,
  "validateOnly": false
}

Batch:

{
  "writeDescriptorId": "asset-analysis-write",
  "operation": "upsert",
  "records": [
    { "entityId": "a", "input": { "...": "..." } },
    { "entityId": "b", "input": { "...": "..." } }
  ],
  "continueOnError": true,
  "dryRun": false
}

Field	Description
writeDescriptorId	Required — Catalox write descriptor id
operation	add, upsert, patch, or replace
entityId / eventId / knowledgeId	Exactly one identity for single writes
input	Payload object (single write)
records	Array of record inputs (batch)
dryRun	Plan without writing
validateOnly	Validate input only
continueOnError	Batch — continue after per-record failure

Returns 200 on success, 422 when validation/write fails. See @x12i/memorix-writer for descriptor shapes and content uploads.

---

Narratives

The authored catalog lives on entity descriptors at descriptor.narratives (validated MemorixNarrativeDefinition entries). Per-record tags live at doc.narratives.{key} (written by pipeline narrative-sync or Explorer assignment).

Merged list/detail endpoints combine authored catalog + platform-generated signals + optional live Mongo counts. Use the raw endpoint when you need only the stored descriptor map (e.g. Exellix catalog consumption).

GET /narratives

Global narrative catalog (merged).

Query	Description
entity	Filter to one entity
target	Filter by target
agentId	Filter by agent scope
includeLiveCounts	Attach live record counts

GET /narratives/{entity}

Narratives for one entity (merged).

GET /narratives/{entity}/raw

Authored descriptor map only — Record<slug, MemorixNarrativeDefinition> as stored on the entity descriptor (no signal discovery merge).

GET /narratives/{entity}/{key}

Single narrative (merged enriched summary).

POST /narratives

Create an authored narrative entry on a descriptor. Requires metadata writes.

Catalog shape (kind required):

{
  "entity": "assets",
  "key": "has-vulnerabilities",
  "label": "Has vulnerabilities",
  "kind": "having-signal",
  "sourceRef": "assetVulnerabilities",
  "targetEntity": "vulnerabilities"
}

Implementation shape (legacy condition-based narratives): label, detectionMethod, condition.

PATCH /narratives/{entity}/{key}

Update an authored entry. Platform-generated keys return 409.

DELETE /narratives/{entity}/{key}

Remove from descriptor. Optional ?removeTags=1 clears record tags.

GET /narratives/{entity}/{key}/records

Paginated records tagged with the narrative.

curl -s "$BASE/narratives/assets/high-risk/records?limit=20&includeTotal=1"

Filter any list by narrativeId

Narrative tags sit on snapshots (doc.narratives.{key}), but the same key filters lists and other content types via the virtual filter property narrativeId (alias narrativeKey):

# Default list / snapshots
curl -s "$BASE/lists/vulnerabilities-main-list/records?filter=narrativeId:eq:is-vulnerability"

# Analysis (or discovery/decisions) linked to tagged snapshots
curl -s "$BASE/records/collection?entityName=vulnerabilities&contentType=analysis&filter=narrativeId:eq:is-vulnerability&mode=raw"

# User-facing filter dropdown options
curl -s "$BASE/narratives/vulnerabilities/filter-options"

# Execute a dashboard listQuery object
curl -s -X POST "$BASE/records/query" -H 'Content-Type: application/json' \
  -d '{"entityName":"vulnerabilities","listDescriptorId":"vulnerabilities-main-list","filters":[{"property":"narrativeId","operator":"eq","value":"is-vulnerability"}]}'

eq / in = has tag; ne / nin = missing tag. See Consuming Memorix data — Narrative filter.

---

Object types & root property catalog

Read-only object-type summaries from Catalox descriptors, plus computed root-envelope property stats.

GET /object-types

All object-type summaries (properties, declarative rootProperties, authored narratives, rootPropertyCatalog when present).

GET /object-types/{name}

Single object-type summary.

GET /object-types/{name}/root-property-catalog

Computed rootPropertyCatalog array. Optional ?contentType=snapshots filters to one content type.

POST /object-types/{name}/root-property-catalog/compute

Full-scan Mongo collections and persist rootPropertyCatalog on the descriptor. Requires metadata writes.

{ "ttlMs": 86400000, "contentTypes": ["snapshots"], "force": false }

Response includes skipped / reason: "fresh" when TTL not expired and force is false.

---

Agents

GET /agents

Returns the agent registry from inventory policy (array of agent objects). Used by Explorer for agent-scoped narrative filtering.

curl -s "$BASE/agents"

---

Route summary

Method	Path	Description
GET	/health	Memorix + Mongo + Catalox health
GET	/inventory/collections, /inventory/summary	Unified inventory
GET	/inventory/issues	Inventory issues only
GET	/inventory/graph	Entity graph
GET	/records/collection	Entity collection (descriptor/raw/auto)
GET	/records/raw-collection	Raw Mongo collection page
GET	/records/full	Multi-content-type full record
GET	/records/item	Item descriptor view
GET	/records/content	Single field content
GET	/records/raw-item	Raw Mongo document by id
GET	/records/workspace	Workspace list
GET	/snapshots/{objectType}/{recordId}	Normalized snapshot view
GET	/snapshots/{objectType}/{recordId}/associated	Normalized associated arrays
GET	/snapshots/{objectType}/{recordId}/associated/{propertyName}	One associated property by alias or storage name
GET	/snapshots/{objectType}/associated-properties	Managed/discovered associated-property metadata
POST	/records/write	Write record(s)
GET	/lists?entityName=	List discovery
GET	/lists/suggest?entityName=	Extension/analytics suggestions
GET	/lists/{listId}	List descriptor
GET	/lists/{listId}/records	List rows
POST	/lists	Create list
PATCH	/lists/{listId}	Update list
DELETE	/lists/{listId}	Delete list
POST	/lists/{listId}/extensions	Add extension
DELETE	/lists/{listId}/extensions/{contentType}	Remove extension
POST	/lists/{listId}/analytics	Add analytics
DELETE	/lists/{listId}/analytics/{field}	Remove analytics
PUT	/lists/{listId}/sort	Set default sort
GET	/object-types	Object-type descriptor summaries
GET	/object-types/{name}	One object-type summary
GET	/object-types/{name}/root-property-catalog	Computed root envelope property catalog
POST	/object-types/{name}/root-property-catalog/compute	Recompute and persist root property catalog
GET	/narratives	Narrative catalog (merged)
GET	/narratives/{entity}	Entity narratives (merged)
GET	/narratives/{entity}/raw	Authored narratives map from descriptor
GET	/narratives/{entity}/{key}	One narrative
POST	/narratives	Create authored narrative
PATCH	/narratives/{entity}/{key}	Update authored narrative
DELETE	/narratives/{entity}/{key}	Delete authored narrative
GET	/narratives/{entity}/{key}/records	Tagged records
GET	/agents	Agent registry

Also: GET /health at server root (process liveness only).

---

Commands

Script	Purpose
npm run dev	Start API server (port 5181) with tsx
npm run build	Compile TypeScript to dist/
npm run serve	Production server (node dist/cli.js serve)
npm test	Live API smoke tests (server must be running)
npm run test:live	Same as npm test — runs all smoke scripts
npm run smoke:api	Core health + inventory + narratives smoke
npm run smoke:inventory	Inventory lenses + raw/descriptor record drill
npm run smoke:records	Workspace + item fetch
npm run smoke:snapshots	Normalized snapshot + associated data reads
npm run smoke:narratives	Narrative catalog + records
npm run smoke:entities	Graph → collection navigation spine
npm run mongo:inventory	CLI inventory report (no HTTP server)
npm run catalox:seed:memorix-retrieval:apply	Apply Catalox retrieval seeds
npm run catalox:seed:memorix-retrieval:validate	Validate seeds without applying

Live test workflow:

# Terminal 1
npm run dev

# Terminal 2
npm test

---

Catalox seeds

Before first use in a new environment, apply retrieval seeds so entity/list/item descriptors exist:

npm run catalox:seed:memorix-retrieval:apply

Requires MONGO_URI and CATALOX_APP_ID (default memorix). Validates with:

npm run catalox:seed:memorix-retrieval:validate

---

Migration: lists catalog rename

If upgrading from a deployment that used the legacy lists catalog id, run once per Catalox app:

cd ../memorix-descriptors
CATALOX_APP_ID=memorix node scripts/migrate-list-descriptors-catalog.mjs [--dry-run]

---

Related documentation

Document	Topic
docs/consuming-memorix-data.md	Read-only consumption guide
docs/advanced-apis.md	Writes, pipeline, associations, metadata
memorix-pipeline docs	Enrichment CLI and association format
memorix-retrieval README	Underlying read APIs, graph runs, inventory lenses
memorix-descriptors README	List descriptor shapes and mutations
memorix-writer README	Write descriptors and record operations
memorix-explorer integration	How the UI consumes these routes
MEMORIX-CATALOX-CONTRACTS	Catalog ids and descriptor JSON formats
MEMORIX-DATABASE-CONVENTIONS	Mongo layout and env resolution

---

Package exports

import {
  createMemorixExplorerApp,
  startMemorixExplorerHttp,
  EXPLORER_API_PREFIX,
} from "@x12i/memorix-explorer-api";

Use these to embed the Explorer API in another Node host or serve the UI from the same process. For custom gateways, proxy HTTP to /api/explorer/* rather than importing internal handlers.