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 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 · Services · Pipelines · Format.
Site: https://docs.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 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.

---

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)

Folder / content-source path:

managed folder source
  → knowx-reconcile-folder   (enumerate → extract Markdown → commitPage content/raw)
  → knowx-extract            (content → knowxDrafts + lineage)
  → write-record knowx
  → associate + relationship-write

Sources contain items. Extractors turn source items into canonical content. KnowX derives Knowledge from content.

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:

Layer	Name	Stored?
Content type	knowx	Yes
Discriminator	data.kind: NODE | EDGE	Inside .data
Abstract	KnowXEntity	Virtual only — NODE/EDGE + relationship navigation properties
Abstract	KnowXContent	Virtual — canonical Markdown documents (content OT)
Abstract	KnowXMaterials	Virtual — REST fixture materials
Forbidden	KnowXNode / KnowXEdge types or collections	—

A.2 Agent pack layout

Package: @x12i/memorix-knowx-pack

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, relationships
materials	Fixture Memory pull intake — abstract KnowXMaterials
content	Canonical ingested Markdown + provenance — abstract KnowXContent; landed as raw

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
knowx-derived-from-content	KnowXEntity → KnowXContent lineage

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

A.4b Content source adapter (source-neutral)

Sources are adapters — not extractors. Package path: memorix-knowx-pack/src/sources/adapter.ts.

interface ContentSourceAdapter<TConfig = unknown> {
  readonly kind: string;
  validate(config, context: SourceContext): Promise<SourceValidation>;
  enumerate(config, context: EnumerateContext): AsyncIterable<DiscoveredSourceItem>;
  open(item, config, context: OpenContext): Promise<ReadableContent>;
  describeOrigin(item, config, context): ContentOrigin;
  watch?(config, onEvent, context: WatchContext): Promise<WatchHandle>;
}

Rules:

• Adapters discover and open bytes (relativePath, extension, streams).
• They must not leak filesystem fields into Knowledge extractors — extractors see ReadableContent / canonical content only.
• Folder impl: FolderContentSourceAdapter (kind: "folder") — recursive walk, symlink-safe containment, optional fs.watch.

A.4c Content extractors (format → Markdown)

Separate from knowx-extract (Knowledge drafts). Registry: createKnowxExtractorRegistry().

Format	Id	Notes
Markdown	knowx-markdown	Front-matter title; empty → INTENTIONALLY_EMPTY
HTML	knowx-html	Strips script/style/nav; no remote fetch
PDF	knowx-pdf	Encrypted → DOCUMENT_ENCRYPTED; image-only → NO_EXTRACTABLE_TEXT (no OCR)
DOCX / PPTX / XLSX	knowx-docx / knowx-pptx / knowx-xlsx	Probe by magic + ext; XLSX truncates large sheets

Contract: probe → highest-confidence match → extract → ExtractionSuccess | ExtractionFailure. Canonical landed shape: ContentRecordData (markdown, contentHash, origins, extraction, revision, knowledgeStatus) on object type content.

A.4d Managed folder sources

Control plane (memorix-knowx-control-plane, /api/knowx/v1/folder-sources, default port KNOWX_PORT / 5110):

Method	Path
POST / GET	/api/knowx/v1/folder-sources
GET / PATCH / DELETE	/api/knowx/v1/folder-sources/:sourceId
POST	.../validate, .../pause, .../resume, .../runs, .../files/ingest
GET	.../items, .../runs (+ cancel/retry/resume proxies)

• Modes: incremental (default) vs sync (deactivate missing origins after complete reconciliation)
• Triggers: manual, schedule ({ every, unit } — KnowX ticker; not Memory pull), watch (acceleration only; reconcile is authoritative)
• Landing: Memory Model B commitPage with objectType=content, checkpoint.method=fullScanHash, workRef=incremental|sync
• On create, control plane installs a mini metadata pack (kind: "knowx-folder") so Memorix effective sources include that sourceId — Studio Memory Pulls / checkpoints then resolve the folder source like any other Memory source
• KnowX owns the folder manifest under KNOWX_DATA_DIR; Memorix owns checkpoint revision/fingerprints
• Product code uses @x12i/memorix-sdk; discovery notes in pack DISCOVERY-GATE.md

Env: KNOWX_ALLOWED_ROOTS (required allowlist), KNOWX_MOUNTS_JSON, KNOWX_DATA_DIR, KNOWX_PORT, MEMORIX_URL, MEMORIX_ORG_ID.

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

Role	Turn text + knowledge source into KnowX drafts (NODE/EDGE), not yet classified.
serviceId	knowx-extract
operation	knowx-extract
Inputs	Legacy: text + knowledgeSource. Content path: contentId / contentIds / reconcileSummary.landedContentIds — load objectType:"content" via SDK Memory, then draft from Markdown
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}
Lineage	Content path sets data.provenance.lineage.{sourceContentId,sourceContentRevision,sourceContentHash} and knowx-derived-from-content
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). Explore lists knowx on assertions, employees, contractors, and work-items (not assertions-only)
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).

---

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.

C.2 Pipeline knowx-ingest-content-source

Folder / content path (after control-plane reconcile lands content):

Step id	kind	Binding
reconcile	analyze	serviceId: knowx-reconcile-folder
extract	analyze	serviceId: knowx-extract (contentIds / landedContentIds)
write-knowx	write-record	contentType: knowx
associate-knowledge	analyze	serviceId: knowx-associate-knowledge
write-knowledge-links	relationship-write	includes knowx-derived-from-content
associate-entities	analyze	serviceId: knowx-associate-entities
write-entity-links	relationship-write	edge-from / edge-to

Control plane prefers mx.pipelines.start("knowx-ingest-content-source", { sourceId, … }); on failure may fall back to local reconcileFolderSource.

---

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

D.2 Folder source acceptance (Vitest)

src/folder-sources.test.ts patterns:

1. Path security unit tests (no FS).
2. Extractor registry: MD / HTML / unsupported / empty PDF.
3. Temp folders: mkdtemp(…/knowx-folder-) + afterEach rm; set allowedRoots: [tmp].
4. Control plane with injected fake Memorix client (pipeline start may throw → local reconcile).
5. Lineage: assert extractKnowxFromContent writes provenance.lineage.*.
6. Idempotency / rename / incremental vs sync via manifest + fullScanHash.

---

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: "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
• Folder path: adapter + extractors + knowx-ingest-content-source + control plane allowlist
• Known pack packId: "knowx" installable after opx
• No live AI required for fixture acceptance
• No associated*, no abstract collections, provenance on every draft

---

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