# knowx — complete library (all audiences)

_Generated whole-library download. See `agent-manifest.json` → `library` for discovery._

## Table of contents

- **KnowX Agent Pack** (`00-knowx-agent-pack`, developers)
- **KnowX Agent Pack** (`00-knowx-agent-pack`, builders)

---

# KnowX Agent Pack — developers

# Building KnowX as a Memorix Agent Pack

**Audience:** Developers implementing the first-party KnowX agent — vocabulary, services, and pipeline.  
**Twin:** [Builders version](../builders/BOOK.md)  
**Scenario:** Fresh `sandbox*` · install `opx` then `knowx` · `agentIds: ["knowx"]` (inherits opx).  
**Packages:** `@x12i/memorix-knowx-pack`, `@x12i/memorix-opx-pack`, `@x12i/memorix-service`, `@x12i/memorix-pipeline`, `@x12i/memorix-format`, `@x12i/memorix-relationships`.  
**Prerequisites:** [Agent packs](../../11-agent-packs-and-opx/developers/BOOK.md) · [Services](../../07-services/developers/BOOK.md) · [Pipelines](../../08-pipelines/developers/BOOK.md) · [Format](../../01-format-for-dummies/developers/BOOK.md).  
**Site:** [https://ebooks.memorix.x12i.com](https://ebooks.memorix.x12i.com) · [Hard rules](../../HARD-RULES.md)  
**Status:** Present-tense tutorial for the shipped `@x12i/memorix-knowx-pack`. Deterministic fixture stubs — **no live AI required**. Replace stubs with real service bodies using the Memorix contracts in §B.

---

## How to read this tutorial

Work in authoring order: **A vocabulary → B services → C pipeline → D install & run**.

1. KnowX is a **content type** (`knowx`) plus a first-party **agent pack** — not a siloed graph engine.
2. Agent `knowx` is a **child of `opx`**. Scope with `agentIds: ["knowx"]` so inheritance collapses opx + knowx.
3. Three ordinary Memorix **services** extract and associate; they **do not persist**.
4. Pipeline `knowx-ingest-associate` persists via `write-record` and `relationship-write`.
5. When your service implementations return contract-shaped outputs, KnowX works end-to-end.
6. Provenance is mandatory; `epistemic.state` ≠ extraction confidence.
7. Four-field RelationshipLinks only — no `associated*`, no abstract collections.

Labels: **Stored** subject content · **Virtual** abstract projection · **Operational** run ledgers.

---

## The central mental model

```text
text + knowledgeSource
  → knowx-extract          (drafts only)
  → write-record knowx     (knowledge added)
  → knowx-associate-knowledge
  → relationship-write     (known / supports / contradicts / derived-from)
  → knowx-associate-entities
  → relationship-write     (edge-from / edge-to)
```

```mermaid
flowchart LR
  Text[text plus knowledge source] --> Extract[knowx-extract]
  Extract --> Write[write-record knowx]
  Write --> AssocK[knowx-associate-knowledge]
  AssocK --> RelK[relationship-write knowledge links]
  RelK --> AssocE[knowx-associate-entities]
  AssocE --> RelE[relationship-write entity links]
```

---

## A — Vocabulary

### A.1 Content type (platform-native)

`memorix-format` registers `knowx` and `confirmations`. Payload rules:

| Layer | Name | Stored? |
|---|---|---|
| Content type | `knowx` | Yes |
| Discriminator | `data.kind`: `NODE` \| `EDGE` | Inside `.data` |
| Abstract | `KnowXEntity` | Virtual only |
| Forbidden | `KnowXNode` / `KnowXEdge` types or collections | — |

### A.2 Agent pack layout

Package: `@x12i/memorix-knowx-pack`

```text
metadata/
  agents/knowx.json          # parentAgentId: opx
  abstract-types.json        # KnowXEntity (+ People/WorkItems restated for standalone validate)
  abstract-bindings.json     # knowx-entity-union
  object-types.json          # employees/contractors/work-items overlays + assertions
  relationship-definitions.json
  services.json
  pipelines-and-sources.json
fixtures/knowx-activity-log.jsonl
src/knowx-services.ts        # deterministic stubs
```

Known pack id: `knowx` → `memorix-metadata/examples/knowx/normalized/pack.json` (explicit install only).

### A.3 Object types

| OT | Role |
|---|---|
| `employees` / `contractors` / `work-items` | Host OTs — knowx pack **replaces** opx defs to add CT `knowx` + `KnowXEntity` |
| `assertions` | Claim subjects — CTs `knowx` (required), `workflow`, `confirmations` |

NODE facets share the host `recordId`. EDGE claims get their own `recordId` on `assertions`.

### A.4 Relationships

| Id | Classification / use |
|---|---|
| `knowx-same-as` | **known** — matches existing claim |
| `knowx-supports` | Reinforces existing |
| `knowx-contradicts` | **contradicts** existing |
| `knowx-derived-from` | Derived from another claim |
| `knowx-edge-from` | EDGE → domain from-endpoint |
| `knowx-edge-to` | EDGE → domain to-endpoint |

Domain assignment links may still use opx `people-assigned-to-work-items` after human accept (operator flow).

### A.5 Provenance (mandatory)

```ts
type SourceSpan =
  | { jsonPath: string }
  | { lineStart: number; lineEnd: number }
  | { byteStart: number; byteEnd: number };

type KnowxProvenance = {
  sourceClass: "measured" | "inferred" | "asserted" | "imported";
  sources: Array<{
    docId: string;
    docType: string;
    docHash: string; // sha-256 of exact source bytes
    span: SourceSpan;
    retrievedAt: string;
  }>;
  extraction: {
    method: string;
    extractorId: string;
    confidence: number; // ≠ epistemic.state
  };
};
```

Missing provenance ⇒ reject writes / fail the extract step.

---

## B — Service specs (Memorix contracts)

These are the Memorix-facing contracts. Implement real bodies against them; fixture stubs in `@x12i/memorix-knowx-pack` satisfy acceptance without live AI.

**Shared rules for all three**

- Capability class: `analyze` (pipeline `stepKind: "analyze"`).
- Invocation: `kind: "worker"` + `operation` matching the service id.
- **Must not** write Mongo, install metadata, or invent `associated*`.
- Scope headers: `orgId` + `agentIds` (use `["knowx"]`).
- Fail closed: return structured errors the pipeline can surface.

### B.1 `knowx-extract`

| | |
|---|---|
| **Role** | Turn text + knowledge source into KnowX drafts (NODE/EDGE), not yet classified. |
| **serviceId** | `knowx-extract` |
| **operation** | `knowx-extract` |
| **Inputs** | `text` — string to analyze; `knowledgeSource` — exact bytes or Memory DataRef + envelope (`docId`, `docType`, `retrievedAt`) |
| **Output** | `knowxDrafts: KnowxDraft[]` plus `docHash` of exact source bytes |
| **Draft shape** | `{ objectType, contentType: "knowx", recordId, data }` with `data.kind`, `provenance`, `epistemic`; EDGE also has `data.refs.{from,to,predicate}` |
| **Errors** | `MISSING_SOURCE`, `INVALID_SOURCE_BYTES`, `MISSING_PROVENANCE` |
| **Handoff** | Pipeline step `write-knowx` (`write-record`, `contentType: "knowx"`) consumes `knowxDrafts` |
| **Fixture stub** | `extractKnowxFromActivityLog` — parses `fixtures/knowx-activity-log.jsonl` → employee NODE, work-item NODE, `ASSERTION-99` EDGE |

### B.2 `knowx-associate-knowledge`

| | |
|---|---|
| **Role** | Classify drafts against existing KnowX scope: **known**, **novel**, **contradicts**; emit knowledge relationship plans. |
| **serviceId** | `knowx-associate-knowledge` |
| **operation** | `knowx-associate-knowledge` |
| **Inputs** | `drafts` — from extract (or already written knowx); `existingKnowx` — optional pushed catalog. Prefer Explore via injected `memorix` callback (`memorixAccess: ["explore"]`) using `@x12i/memorix-sdk/client` `fromInvokeContext` (or SDK `/worker` `context.memorix`) |
| **Output** | `classification: { known[], novel[], contradicts[] }`; `relationshipPlans[]` |
| **Plan item** | `{ definitionId, from: { objectType, recordId }, to: { objectType, recordId }, reason? }` where `definitionId` ∈ `knowx-same-as` \| `knowx-supports` \| `knowx-contradicts` \| `knowx-derived-from` |
| **Errors** | `MISSING_DRAFTS`, `INVALID_CLASSIFICATION` |
| **Handoff** | Step `write-knowledge-links` (`relationship-write`) consumes `relationshipPlans` |
| **Fixture stub** | Same `objectType+recordId` → known + `knowx-same-as`; EDGE same endpoints different predicate → contradicts + `knowx-contradicts`; else novel |

### B.3 `knowx-associate-entities`

| | |
|---|---|
| **Role** | Associate **novel** KnowX (especially EDGE) to existing domain entities. |
| **serviceId** | `knowx-associate-entities` |
| **operation** | `knowx-associate-entities` |
| **Inputs** | `novelDrafts` — from classification.novel (resolve full drafts); `entityCatalog` — available entity endpoints / abstracts |
| **Output** | `entityRelationshipPlans[]` with `definitionId` ∈ `knowx-edge-from` \| `knowx-edge-to` (optional domain defs) |
| **Errors** | `MISSING_NOVEL`, `UNRESOLVED_ENDPOINT` |
| **Handoff** | Step `write-entity-links` (`relationship-write`) consumes `entityRelationshipPlans` |
| **Fixture stub** | For each novel EDGE, emit plans from `data.refs.from` / `data.refs.to` |

### B.4 Swap stub → real implementation

1. Keep the same `serviceId` / `operation` / output field names.
2. Bind your worker in the pipeline PortHandler registry (same pattern as other `analyze` services).
3. Return contract-shaped JSON; pipeline persist steps stay unchanged.
4. Keep a deterministic path for acceptance (fixture or golden inputs).

---

## C — Pipeline `knowx-ingest-associate`

| Step id | kind | Binding |
|---|---|---|
| `extract` | `analyze` | `serviceId: knowx-extract` |
| `write-knowx` | `write-record` | `contentType: knowx` |
| `associate-knowledge` | `analyze` | `serviceId: knowx-associate-knowledge` |
| `write-knowledge-links` | `relationship-write` | plans → knowledge defs |
| `associate-entities` | `analyze` | `serviceId: knowx-associate-entities` |
| `write-entity-links` | `relationship-write` | plans → edge-from/to |

Optional later (operator-driven): `workflow` + `confirmations` before treating epistemic as `fact`; materialize domain links such as `people-assigned-to-work-items`.

Run evidence lives in the pipeline operational ledger — not in subject content.

---

## D — Install and sandbox run

```bash
# 1) Install parent opx, then knowx (never auto-install)
POST /api/metadata/install  { "packId": "opx", "confirm": true }
POST /api/metadata/install  { "packId": "knowx", "confirm": true }

# 2) Scope — child agent collapses opx inheritance
X-Memorix-Org-Id: sandbox…
X-Memorix-Agent-Ids: knowx

# 3) Start pipeline with text + knowledge source inputs
POST /api/pipelines/start
{ "pipelineId": "knowx-ingest-associate", … }
```

Isolation: fresh `sandbox*` org; `beginIsolationSession({ agentIds: ["knowx"] })` when running KnowX acceptance. Default isolation remains `["opx"]`.

Package tests: `cd memorix-knowx-pack && npm test`.

---

## Human review (siblings)

On assertion `recordId`:

- `knowx` — claim + provenance + epistemic  
- `workflow` — review assignment (`PUT /api/workflow`)  
- `confirmations` — accept/reject  

Accepted EDGE → optional domain relationship materialize (Explore / relationship APIs). Heavy JSON stays on the claim; links are navigation only.

---

## Checklist

- [ ] Agent `knowx` with `parentAgentId: "opx"`
- [ ] `KnowXEntity` union + `assertions` OT + knowx CT on host OTs
- [ ] Six KnowX relationship definitions
- [ ] Three services with Memorix contracts above
- [ ] Pipeline `knowx-ingest-associate` wired end-to-end
- [ ] Known pack `packId: "knowx"` installable after opx
- [ ] No live AI required for fixture acceptance
- [ ] No `associated*`, no abstract collections, provenance on every draft

---

## Related

- [Builders twin](../builders/BOOK.md) · [Diagram](../diagrams/knowx-flow.md)  
- [Agent packs & OpX](../../11-agent-packs-and-opx/developers/BOOK.md)  
- [Services](../../07-services/developers/BOOK.md) · [Pipelines](../../08-pipelines/developers/BOOK.md)  
- Use case: `knowx-claims-review`

---

# KnowX Agent Pack — builders

# Building KnowX — Builders

**Audience:** Studio builders reviewing knowledge claims and running the KnowX ingest pipeline.  
**Twin:** [Developers version](../developers/BOOK.md)  
**Scenario:** Fresh `sandbox*` · install opx then knowx · `agentIds: ["knowx"]`.  
**Site:** [https://ebooks.memorix.x12i.com](https://ebooks.memorix.x12i.com) · [Hard rules](../../HARD-RULES.md)  
**Status:** Operator guide for the first-party `@x12i/memorix-knowx-pack`. Live AI not required. Studio NODE/EDGE screenshots may still be placeholders.

---

## How to read this guide

1. KnowX is ordinary Memorix content plus a **knowx** agent pack — not a separate graph product.
2. Pipeline adds knowledge, associates it to other knowledge, then links novel claims to entities.
3. You review claims via workflow/confirmations; Explore shows four-field links.
4. Implementation contracts → [developers twin](../developers/BOOK.md).

---

## The central idea

> **KnowX is `contentType: "knowx"` with mandatory provenance. Services draft; the pipeline persists. Navigation is four-field relationships — never copied claim JSON.**

| You see | Meaning |
|---|---|
| NODE knowx on an employee / work item | Subject is graph-visible with provenance |
| EDGE knowx on an assertion | A claim linking subjects |
| known / novel / contradicts | Associate-knowledge classification |
| Knowledge relationship links | same-as / supports / contradicts / derived-from |
| Entity edge-from / edge-to links | Assertion attached to domain endpoints |
| Workflow + confirmations | Human review siblings |

One abstract name: **KnowXEntity**. Scope with agent **`knowx`** (inherits **ops**). Always use a fresh **`sandbox*`** org.

---

## 1. Five questions every claim should answer

1. What is asserted? (label / refs)  
2. Where did it come from? (`docHash` + span)  
3. How sure is the extractor? (extraction confidence)  
4. What is the epistemic state? (hypothesis / fact / disputed / …)  
5. Who must confirm? (workflow sibling)

Extraction confidence and epistemic state are **different** fields.

---

## 2. Operator journey

1. **Install** known packs `opx` then `knowx` (explicit confirm).  
2. **Run** pipeline `knowx-ingest-associate` with text + knowledge source.  
3. **Inspect** written knowx content (NODE/EDGE).  
4. **Inspect** knowledge association links and entity edge links.  
5. **Review** assertions via workflow / confirmations when required.  
6. **Explore** four-field links — do not expect claim JSON on the link.

---

## 3. Review rules before accept

- Provenance present (`docHash` + span).  
- `data.kind` is NODE or EDGE.  
- Contradictions are visible as `knowx-contradicts` (do not silently overwrite).  
- Accept writes `confirmations`; update epistemic deliberately.  
- Never store `associated*` on content roots.

---

## 4. What builders do not do

- Do not call Mongo.  
- Do not invent a separate KnowX database.  
- Do not expect auto-install of the knowx pack.  
- Live AI extractors are optional behind your service implementation — fixtures prove the Memorix path.

---

## Related

- [Developers twin](../developers/BOOK.md) — full service contracts and pipeline map  
- [Agent packs](../../11-agent-packs-and-opx/builders/BOOK.md) · [Studio / workflow](../../09-workflow-and-studio/builders/BOOK.md)