Operational Ontology (Layer 7)

Define the domain objects, relations, and agent instructions that matter to your workspace. MindGraph extracts instances from your documents under that schema, review-and-approves them, and exposes them to your agents as typed business memory — Clients, Suppliers, Contracts, Patients, Cases, Tickets, whatever your work centers on.

When to use it

Add an Operational Ontology when your workspace has recurring business objects that don't fit the cognitive primitives. Some examples by use case:

• Client services: Client, Project, Contract, Stakeholder, Deliverable, Meeting
• Healthcare: Patient, Condition, Medication, LabResult, Guideline, CarePathway, VisitNote
• Supply chain: Supplier, Shipment, Facility, PurchaseOrder, Part, InventoryItem, Incident
• Research / intel: Actor, Source, Event, Location, Timeline, Hypothesis-of-interest

Don't recreate cognitive types (Claim, Evidence, Decision, Risk, Task, Goal, …) — those already exist as built-ins and the ontology layer composes with them.

Setting up an ontology

1. Open /dashboard/ontology in the dashboard.
2. Click Create with AI, describe your workspace, and (optionally) upload sample documents.
3. Review the proposed object types + relation types. Add, remove, or edit.
4. Activate the schema.
5. Ingest documents with layers: ["reality", "epistemic", "ontology"] — extracted domain objects land in the Proposals queue for review.
6. Approve proposals. Approved objects become queryable by your agents.

SDK usage

import { MindGraph } from "mindgraph";

const mg = new MindGraph({ baseUrl: "https://api.mindgraph.cloud", apiKey: "mg_..." });

// 1. Propose a schema from a description
const { schema_id, job_id } = await mg.proposeOntologySchema({
  description: "We're a client-services agency: clients, projects, contracts, risks.",
  template_hint: "client_services",
});

// 2. Activate the schema after reviewing
await mg.activateOntologySchema(schema_id);

// 3. Ingest with ontology extraction enabled
await mg.ingestDocument({
  content: "Acme Corp signed a new contract on Mar 14 ...",
  layers: ["reality", "epistemic", "ontology"],
  ontology_schema_id: schema_id,
});

// 4. Review + approve proposals
const { items: proposals } = await mg.listOntologyProposals({ status: "pending" });
for (const p of proposals) {
  await mg.approveOntologyProposal(p.id);
}

// 5. Query the ontology
const result = await mg.queryOntology({
  query: "Which clients have unresolved delivery risks?",
  schema_id,
  include_cognitive_context: true,
});

Object type fields

Each object type defines a list of fields. Allowed field types:

• string, number, integer, boolean, date, datetime, object, json
• enum — requires enum: ["a", "b"]
• reference — requires reference_object_type: "OtherType" (must exist in the same schema)
• array — requires array_item_type: "string" (scalar item types only)

Each object type also declares identity_fields — the subset of fields whose values together uniquely identify an instance. The apply-worker uses identity fields to deduplicate: if a new proposal matches an existing object by identity, it's applied as an update instead of a create.

Reserved type names

Domain object type names cannot collide with MindGraph built-in NodeType variants (case-insensitive). Person, Organization, Document, Claim, Decision, etc. are reserved — use workspace-specific names like Client, Supplier, Patient instead. The cloud API rejects collisions with 409 reserved_type_name.

Provenance & review

Every proposed domain object carries a source_uids array referencing the chunks it was extracted from. Approved objects keep that provenance and add an ExtractedFrom edge to each source chunk, so queryOntology can return source excerpts alongside the object. Object types with review_policy: "never" auto-approve above their default_confidence; "low_confidence" auto-approves high-confidence proposals and queues low-confidence ones for review; "always" queues every proposal.