# @x12i/memorix-metadata

> Canonical Memorix metadata contracts, effective multi-agent resolution, and metadata-only abstract unions (Phase 3).

Latest version **3.2.1** (published 2026-08-17) · exellix-license license · 0 weekly downloads

## Install

```sh
npm install @x12i/memorix-metadata
pnpm add @x12i/memorix-metadata
yarn add @x12i/memorix-metadata
bun add @x12i/memorix-metadata
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.2.1 |
| Published | 2026-08-17 |
| First published | 2026-07-23 |
| Weekly downloads | 0 |
| License | exellix-license |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 1 |
| Unpacked size | 578.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |

## Links

- npm: https://www.npmjs.com/package/@x12i/memorix-metadata
- Repository: https://github.com/x12i/memorix-mono-repo
- Homepage: https://github.com/x12i/memorix-mono-repo#readme
- Issues: https://github.com/x12i/memorix-mono-repo/issues
- npm.io page: https://npm.io/package/@x12i/memorix-metadata

## Dependencies (1)

- [@x12i/memorix-mapping](https://npm.io/package/@x12i/memorix-mapping.md) ^3.0.2

## Recent versions

- 3.2.1 (latest) — 2026-08-17
- 3.0.0 (next) — 2026-07-23
- 0.0.0-bootstrap.0 (bootstrap) — 2026-07-23
- 3.2.0 — 2026-08-05
- 3.1.0 — 2026-08-02
- 3.0.3 — 2026-07-30
- 3.0.2 — 2026-07-23
- 3.0.1 — 2026-07-23
- 0.2.0 — 2026-07-23
- 0.1.0 — 2026-07-23

## README

# `@x12i/memorix-metadata`

Declarative **metadata contracts**, **multi-agent effective resolution**, and **metadata-only abstract unions** for Memorix.

This package is the **law** layer (what agents, types, views, mappings, and pipelines *are*). It does not install packs into Mongo, read subject records, or serve HTTP.

## Install

```bash
npm install @x12i/memorix-metadata@3.0.2
```

| Audience | Use this package? |
|----------|-------------------|
| Remote app | Usually **no** — call `memorix-service` `/api/metadata` |
| Pack authors / platform engineers | **Yes** — validate packs, resolve effective metadata in-process |
| “Install a pack into an org” | Use `@x12i/memorix-metadata-runtime` (or HTTP install routes) |

## What it covers

Built-in kinds (via `METADATA_KIND_IDS` / Catalox catalogs):

`agents` · `object-types` · `abstract-types` · `abstract-bindings` · `relationship-definitions` · `mappings` · `views` · `writes` · `sources` · `services` · `pipelines` · `schedules` · `kind-declarations`

Plus **namespaced custom kinds** (`kindDeclarations` + `extensions`) — store/resolve only; engines do not execute them.

## Core API

```ts
import {
  validateMetadataPack,
  assertValidMetadataPack,
  resolveEffectiveMetadata,
  resolveMultiAgentMetadata,
  resolveAbstractBindingsFromPack,
  buildEffectiveMetadataTopology,
  normalizeOpxPackBundle,
  METADATA_KIND_IDS,
  isValidCustomKindId,
} from "@x12i/memorix-metadata";
```

| Function | Role |
|----------|------|
| `validateMetadataPack` / `assertValidMetadataPack` | Structural + cross-ref validation of a pack |
| `resolveEffectiveMetadata` / `resolveMultiAgentMetadata` | Merge `agentIds[]` inheritance into effective definitions |
| `resolveAbstractBindings*` | Plan abstract → concrete property paths (virtual only) |
| `buildEffectiveMetadataTopology` | Project concrete OT↔OT / feed / pipeline-derived graph (no new authoring kinds) |
| `normalizeOpxPackBundle` | Normalize opx-pack style JSON into a pack |
| `fingerprintDefinition` | Stable fingerprints for install/diff |

## Quick example

```ts
import { validateMetadataPack, resolveEffectiveMetadata } from "@x12i/memorix-metadata";

const pack = /* MetadataPack */;
const { ok, issues } = validateMetadataPack(pack);
if (!ok) throw new Error(issues.map((i) => i.message).join("; "));

const effective = resolveEffectiveMetadata({
  packsByAgentId: { opx: pack },
  agentIds: ["opx"],
});
// effective.effective → definitions with provenance; conflicts reported, not silent
```

Custom-kind example pack: [`examples/custom-kinds/acme-ui-tabs.pack.json`](./examples/custom-kinds/acme-ui-tabs.pack.json)

## Boundaries

| Need | Use instead |
|------|-------------|
| Install / publish into Catalox + effective client | `@x12i/memorix-metadata-runtime` |
| HTTP for operators / remote apps | `@x12i/memorix-service` `/api/metadata` |
| Subject record I/O | `@x12i/memorix-data` / `/api/data` |

Abstracts stay **virtual** — no abstract collections and no abstract `recordId`.

**Relationships** are authored on abstracts; concrete OT↔OT edges come from `buildEffectiveMetadataTopology` (HTTP: `GET /api/metadata/topology`). Sources/streams **feed** object types; services appear on an OT neighborhood only when a pipeline invokes them and a mapping on that pipeline lands on an OT.

## Docs

- Practical: [`documentation/metadata.md`](../documentation/metadata.md) · [`documentation/packages/memorix-metadata.md`](../documentation/packages/memorix-metadata.md)
- Ebook: [Metadata, Agents, Abstracts](../memorix-docs/05-metadata-agents-abstracts/)
- Hub: [https://docs.memorix.x12i.com](https://docs.memorix.x12i.com)

---
_Source: https://npm.io/package/@x12i/memorix-metadata · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._