Building KnowX as a Memorix Agent Pack

Audience: Developers implementing the first-party KnowX agent — vocabulary, services, and pipeline.
Twin: Builders version
Scenario: Fresh sandbox* · install ops then knowx · agentIds: ["knowx"] (inherits ops).
Packages: @x12i/memorix-knowx-pack, @x12i/memorix-ops-pack, @x12i/memorix-service, @x12i/memorix-pipeline, @x12i/memorix-format, @x12i/memorix-relationships.
Prerequisites: Agent packs · Services · Pipelines · Format.
Site: https://ebooks.memorix.x12i.com · Hard rules
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.

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 ops. Scope with agentIds: ["knowx"] so inheritance collapses ops + 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.

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)

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.1 Content type (platform-native)

memorix-format registers knowx and confirmations. Payload rules:

A.2 Agent pack layout

Package: @x12i/memorix-knowx-pack

metadata/
  agents/knowx.json          # parentAgentId: ops
  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

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

A.4 Relationships

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

A.5 Provenance (mandatory)

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.

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

B.2 knowx-associate-knowledge

B.3 knowx-associate-entities

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).

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.

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

# 2) Scope — child agent collapses ops 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 ["ops"].

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

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.

• Agent knowx with parentAgentId: "ops"
• 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 ops
• No live AI required for fixture acceptance
• No associated*, no abstract collections, provenance on every draft

• Builders twin · Diagram
• Agent packs & ops
• Services · Pipelines
• Use case: knowx-claims-review