# @x12i/memorix-hippox

> Memorix Hippox: discover, simulate, persist, and resolve contextual relationships between Memorix object types.

Latest version **1.36.0** (published 2026-07-21) · exellix-license license · 0 weekly downloads

## Install

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

## 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 | 1.36.0 |
| Published | 2026-07-21 |
| First published | 2026-06-30 |
| Weekly downloads | 0 |
| License | exellix-license |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 4 |
| Unpacked size | 322.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |
| Keywords | exellix, memorix, hippox, context-links, job-memory |

## Links

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

## Dependencies (4)

- [mongodb](https://npm.io/package/mongodb.md) ^6.21.0
- [@x12i/memorix-mongo](https://npm.io/package/@x12i/memorix-mongo.md) ^1.33.0
- [@x12i/memorix-retrieval](https://npm.io/package/@x12i/memorix-retrieval.md) ^1.32.0
- [@x12i/memorix-descriptors](https://npm.io/package/@x12i/memorix-descriptors.md) ^1.38.0

## Alternatives

- [cron](https://npm.io/package/cron.md) — 4.9M weekly downloads
- [@vercel/queue](https://npm.io/package/@vercel/queue.md) — 731.6K weekly downloads
- [create-sonicjs](https://npm.io/package/create-sonicjs.md) — 1.6K weekly downloads
- [@exellix/jobs-api](https://npm.io/package/@exellix/jobs-api.md) — 941 weekly downloads
- [@forwardimpact/libskill](https://npm.io/package/@forwardimpact/libskill.md) — 575 weekly downloads

## Recent versions

- 1.36.0 (latest) — 2026-07-21
- 1.35.0 — 2026-07-13
- 1.34.0 — 2026-07-13
- 1.33.0 — 2026-07-11
- 1.32.0 — 2026-07-11
- 1.4.0 — 2026-07-05
- 1.3.0 — 2026-06-30
- 1.2.0 — 2026-06-30
- 1.1.0 — 2026-06-30
- 1.0.1 — 2026-06-30
- 1.0.0 — 2026-06-30

## README

# @x12i/memorix-hippox

Memorix Hippox stores reusable contextual links between Memorix object types. Operators can discover join keys from sampled data, define property-based joins without pre-modeled schema relations, simulate match quality, approve links into long-term memory, and resolve bounded context into `jobMemory.context`.

See [memorix-format.md §13](../docs/memorix-format.md) and [memorix-fomat-additions.md §K](../docs/memorix-fomat-additions.md) for how Hippox fits the Memorix 2.0 record model (`data`, `associatedData`, `index.recordLinks`, `sourceFacts`).

**Full mapping landscape (consultation):** [`docs/MEMORIX-MAPPING-OVERVIEW.md`](../docs/MEMORIX-MAPPING-OVERVIEW.md)

## Not this package

| Concern | Owner |
|---------|--------|
| Durable bulk `associated*` on snapshots | [`memorix-associator`](../memorix-associator/) |
| Abstract types / propertyMap for apps | [Mappix](../mappix/) + [`memorix-abstraction`](../memorix-abstraction/) |
| Authored schema `relations[]` | object-type descriptors / Schema UI |
| Vector nearest-neighbor indexes | [`memorix-similarity`](../memorix-similarity/) |
| LLM mapping inference | Mappix FuncX adapter (not Hippox); fuzzy `infer-links` uses `@x12i/helpers` |

Hippox **resolve** returns transient `jobMemory.context`. Materializing into snapshot `associated*` is a separate associator/assembly step.

## Database

Approved and draft links persist in Mongo database **`memorix-hippox`** (collection **`context-links`** by default).

| Variable | Default | Purpose |
|----------|---------|---------|
| `MEMORIX_HIPPOX_DB` | `memorix-hippox` | Hippox Mongo database |
| `MEMORIX_HIPPOX_COLLECTION` | `context-links` | Context links collection |
| `MEMORIX_HIPPOX_SIMULATION_LIMIT` | `1000` | Max records sampled per side during simulation |
| `MEMORIX_HIPPOX_SIMULATION_EXAMPLES_LIMIT` | `25` | Max example matches/misses in simulation summary |
| `MEMORIX_CONTEXT_LIST_LIMIT` | `25` | Default list retrieval limit at resolve time |
| `MEMORIX_HIPPOX_DISCOVERY_SAMPLE_LIMIT` | `1000` | Max records sampled per side during join discovery |
| `MEMORIX_HIPPOX_DISCOVERY_DISTINCT_CAP` | `500` | Max distinct source values per value probe |
| `MEMORIX_HIPPOX_DISCOVERY_MAX_PAIRS` | `200` | Max source×target field pairs to evaluate |
| `MEMORIX_HIPPOX_DISCOVERY_MIN_COVERAGE` | `0.05` | Minimum field coverage to include in discovery |
| `MEMORIX_HIPPOX_DISCOVERY_MIN_PAIR_SCORE` | `0.15` | Minimum score for join candidates / recommended join |
| `MEMORIX_HIPPOX_DISCOVERY_CACHE_TTL_MS` | `300000` | In-memory join-discovery cache TTL per pair |
| `MEMORIX_HIPPOX_DISCOVERY_MAX_CANDIDATES` | `50` | Max entries in `joinCandidates` |

## Path conventions (Memorix 2.0)

Join paths are **dot paths from the document root**, consistent with entity descriptor relations:

```json
{ "sourcePath": "data.subnetId", "targetPath": "data.id", "operator": "eq" }
```

Discovery walks the content-type `dataRoot` (default `data`) and returns paths with the `data.` prefix.

Record identity and sorting support both Memorix 2.0 and legacy shapes:

- IDs: `identity.recordId`, `identity.targetId`, then legacy `entityId` / `recordId` / `_id`
- Latest record: `data.scopedAt`, then `lifecycle.capturedAt` / `lifecycle.modifiedAt`, then root timestamps

## Example: assets → subnets (record context)

```json
{
  "sourceObjectType": "assets",
  "targetObjectType": "subnets",
  "direction": "downstream",
  "join": [
    { "sourcePath": "data.subnetId", "targetPath": "data.id", "operator": "eq" }
  ],
  "retrieval": { "type": "record", "outputMode": "data" }
}
```

Resolved output:

```json
{
  "jobMemory": {
    "context": {
      "subnets": {
        "cidr": "10.0.0.0/24",
        "region": "eu-west-1"
      }
    }
  }
}
```

Materializing this into a snapshot's `associatedData` block is a separate assembly step; Hippox resolve returns transient job context.

## HTTP routes

When mounted through `memorix-catalox-api`:

| Method | Path | Purpose |
|--------|------|---------|
| `GET` | `/api/hippox/links?sourceObjectType=assets` | List draft + simulated + approved links |
| `POST` | `/api/hippox/links` | Create draft link |
| `GET` | `/api/hippox/join-discovery?sourceObjectType=…&targetObjectType=…` | Rank join fields and recommend default pair (`findMode=field-join` default) |
| `GET` | `/api/hippox/join-discovery?…&findMode=identifier` | Mode A: source value paths → target identity / concept candidates |
| `POST` | `/api/hippox/join-discovery` | Same as GET with body parameters (`findMode` optional) |
| `POST` | `/api/hippox/infer-links` | Fuzzy-map joins across object types (`@x12i/helpers` ≥ 2.0) |
| `POST` | `/api/hippox/links/from-relation-candidate` | Create Hippox draft from schema relation candidate |
| `POST` | `/api/hippox/links/simulate` | Simulate unsaved definition |
| `POST` | `/api/hippox/links/:id/simulate` | Simulate + persist summary |
| `POST` | `/api/hippox/links/:id/approve` | Approve simulated link |
| `POST` | `/api/hippox/context/resolve` | Resolve runtime context from approved links |

### Join discovery response (summary)

Returns ranked `sourceFields`, `targetFields`, `joinCandidates`, and `recommendedJoin` for Mode B (`findMode=field-join`, default). Each field includes a `classification` of `link-target` | `join-out` | `other`; pure link-target identity fields are demoted so Mode B dropdowns do not treat them as outward join keys.

With `findMode=identifier` (Mode A), the response also includes `sourceValuePaths`, `targetIdentityCandidates`, and `recommendedMatch` (or `null` + warnings). Mode A does not require a target `data.*` join path — the target side is identity / concept matching.

Discovery is ephemeral (optional in-memory cache); only approved links persist.

## Programmatic usage

```ts
import { createMemorixRetrievalStackFromEnv } from '@x12i/memorix-retrieval';
import { HippoxService } from '@x12i/memorix-hippox';

const { client } = await createMemorixRetrievalStackFromEnv();
const hippox = await HippoxService.create({ retrieval: client });

const discovery = await hippox.discoverJoinCandidates({
  sourceObjectType: 'assets',
  targetObjectType: 'subnets',
});

const draft = await hippox.createDraftLink({
  sourceObjectType: 'assets',
  targetObjectType: 'subnets',
  direction: 'downstream',
  join: [discovery.recommendedJoin ?? {
    sourcePath: 'data.subnetId',
    targetPath: 'data.id',
  }],
  retrieval: { type: 'record', outputMode: 'data' },
});

const { simulation } = await hippox.simulateAndPersist(draft.id);
await hippox.approveLink(draft.id);

const resolved = await hippox.resolveContextInput({
  sourceObjectType: 'assets',
  sourceRecordId: 'entity:asset:10.100.18.64',
  linkIds: [draft.id],
});
```

## Legacy relation links

Relation-based `JobContextLink` / `contextLinks` are **not** resolved into
`jobMemory`. Prefer Hippox approved links (`resolveContext` /
`resolveContextInput`). `resolveMixedContext()` remains as a deprecated alias
that only forwards Hippox resolution (no `_legacy` merge).

## Retrieval types

- **record** — single best match (default latest `data.scopedAt` or `lifecycle.capturedAt`)
- **list** — bounded array (mandatory limit)
- **aggregate** — flat per-property value counts

Output modes: `data` (default), `record`, `dataWithRecordId`.

## Relationship to other Memorix layers

| Layer | Hippox role |
|-------|-------------|
| `sourceFacts.resolver.component: "memorix-hippox"` | value resolution rules (enum/lookup) — separate from context links |
| `index.recordLinks` | schema-declared indexed relations |
| `associatedData` | readable materialized join output on snapshots |
| `jobMemory.context` | runtime output of `context/resolve` |

## Fuzzy mapping pipeline (`@x12i/helpers` ≥ 2.0)

`@x12i/helpers@2.0.0` ships **record key analysis** at `@x12i/helpers/record-key-analysis`. Hippox orchestrates it via **`POST /api/hippox/infer-links`**.

This complements **join-discovery** (named object types, schema seeds, value overlap ranking). Fuzzy mapping is the cold-start path; join-discovery refines once types and collections are registered.

### Prerequisites

- Runtime access to collection samples (Mongo via Hippox collection resolver).
- Optional peer **`@x12i/helpers@^2.0.0`** (returns HTTP 501 if missing when calling infer-links).

### API

```http
POST /api/hippox/infer-links
{ "objectTypes": ["assets", "subnets"], "sampleLimit": 10000 }
```

Returns `collectionProfiles` (PRIMARY / FOREIGN / ENUM tags) and ranked `inferredLinks` with inclusion ratios.

### Programmatic usage

```ts
const inference = await hippox.inferLinks({
  objectTypes: ['assets', 'subnets', 'vulnerabilities'],
});
for (const link of inference.inferredLinks) {
  await hippox.createDraftLink({
    sourceObjectType: link.sourceObjectType,
    targetObjectType: link.targetObjectType,
    direction: 'downstream',
    join: [{ sourcePath: link.sourcePath, targetPath: link.targetPath }],
    retrieval: { type: 'record', outputMode: 'data' },
  });
}
```

### Schema relation bridge

```http
POST /api/hippox/links/from-relation-candidate
POST /api/relationships/:sourceEntity/:relationKey/hippox-draft   # schema-api operational wrapper
```

Converts a schema `RelationCandidate` or declared relation into a Hippox draft link.

See [memorix-format.md §13.4](../docs/memorix-format.md) and [memorix-fomat-additions.md §K.4](../docs/memorix-fomat-additions.md).

Consultation maps: [MEMORIX-MAPPING-OVERVIEW](../docs/MEMORIX-MAPPING-OVERVIEW.md) · [MEMORIX-METADATA-CATALOX-OVERVIEW](../docs/MEMORIX-METADATA-CATALOX-OVERVIEW.md)

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