# @x12i/memorix-relationships

> Memorix relationship engine: compile, discover, materialize, verify/rebuild (Phase 7 / G7). The only trusted production relationship-link writer.

Latest version **3.1.1** (published 2026-09-23) · exellix-license license · 0 weekly downloads

## Install

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

## 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.1.1 |
| Published | 2026-09-23 |
| First published | 2026-07-23 |
| Weekly downloads | 0 |
| License | exellix-license |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 5 |
| Unpacked size | 168.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |

## Links

- npm: https://www.npmjs.com/package/@x12i/memorix-relationships
- 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-relationships

## Dependencies (5)

- [mongodb](https://npm.io/package/mongodb.md) ^6.21.0
- [@x12i/memorix-data](https://npm.io/package/@x12i/memorix-data.md) ^3.0.2
- [@x12i/memorix-mapping](https://npm.io/package/@x12i/memorix-mapping.md) ^3.0.2
- [@x12i/memorix-metadata](https://npm.io/package/@x12i/memorix-metadata.md) ^3.1.0
- [@x12i/memorix-relationship-store](https://npm.io/package/@x12i/memorix-relationship-store.md) ^3.0.2

## Recent versions

- 3.1.1 (latest) — 2026-09-23
- 3.0.0 (next) — 2026-07-23
- 0.0.0-bootstrap.0 (bootstrap) — 2026-07-23
- 3.1.0 — 2026-08-02
- 3.0.2 — 2026-07-23
- 3.0.1 — 2026-07-23
- 0.1.0 — 2026-07-23

## README

# `@x12i/memorix-relationships`

Trusted **relationship engine**: compile definitions, **discover**, **materialize**, **verify**, and **rebuild** four-field links.

This is the only production path that writes relationship links. Remote clients use HTTP; ad-hoc `/links` mutation is rejected (405).

## Install

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

| Audience | Use this package? |
|----------|-------------------|
| Remote app | **No** — `/api/relationships` |
| Platform / pipelines | **Yes** |

## Core API

```ts
import { createRelationshipEngine } from "@x12i/memorix-relationships";

const engine = createRelationshipEngine({ /* store, metadata resolver, data reader */ });

// Dry-run candidates
await engine.discoverAndMaterialize(scope, definitionId, { dryRun: true });

// Persist links
await engine.discoverAndMaterialize(scope, definitionId, { dryRun: false });

await engine.verify(scope, definitionId);
await engine.rebuild(scope, definitionId);
```

Lifecycle:

```text
relationship definition (metadata)
  → discover (candidates, service-held)
  → materialize (four-field links in store)
  → verify / rebuild
```

## Hard rules

- Links are exactly four fields (`relationshipId`, `relationshipDefinitionId`, `fromRecordId`, `toRecordId`).
- Never copy related payloads into the source record (`associated*` as storage is forbidden).
- Neighbor content is read at expand time, not embedded.

## Related

| Need | Package |
|------|---------|
| Persistence adapter | `@x12i/memorix-relationship-store` |
| Compose / expand reads | `@x12i/memorix-data` |
| Pipeline steps | `relationship-discover` / `relationship-write` in `@x12i/memorix-pipeline` |

## Docs

- [`documentation/hard-rules.md`](../documentation/hard-rules.md)
- Ebook: [Relationships & Memory](../memorix-docs/06-relationships-and-memory/)
- Hub: [https://docs.memorix.x12i.com](https://docs.memorix.x12i.com)

```bash
npm test
```

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