Public types · pre-release

Know what you send and receive.

The public types describe the data your application exchanges with ConceptMem. Use them to build observations and interpret the results.

@conceptmem/types accompanies the SDK. Both packages are awaiting public release. MCP clients discover their tool-specific schemas from the hosted endpoint; MCP response shapes are documented in the MCP guide.

Observation

An observation proposes a change to an entity. Keep a stable reference from your source system so later observations address the same record.

A typed observation

import type { Observation } from '@conceptmem/types';

const observation: Observation = {
  entityType: 'customer',
  entityRef: 'customer:crm_1042',
  data: { contact_channel: 'email' },
  provenance: {
    source: 'support',
    actor: 'support-agent',
    confidence: 0.97,
    extractionMethod: 'structured_import',
  },
};

Observation fields
Field	Meaning
`entityType: string`	The entity’s class. Reuse the vocabulary already used by your database.
`entityRef?: string`	An existing entity ID or stable canonical reference. Names alone can be ambiguous; prefer source-system identifiers.
`data: Record<string, unknown>`	Predicate names and proposed values. Use declared value types and domains where available.
`provenance`	Required source, actor and confidence, with an optional extractionMethod. The service timestamps the mutation.
`relations?: ObservedRelation[]`	Proposed typed relationships using relationType, targetRef and optional targetType. retract requests removal of an edge.
`validFrom?: Date`	Optional date when the proposed values became valid in the world.

confidence is between zero and one. It expresses the supplied confidence in an observation; it is not independent verification. Include an extraction method so downstream users can interpret the recorded source. The hosted service records the authenticated principal as the actor, overriding the actor supplied in the observation.

ConsolidationResult

The SDK’s default write result includes the entity reference and four lists. Process all four before treating a proposal as accepted.

ConsolidationResult fields
Field	Meaning
`entityId / canonicalId`	References to the entity addressed by the result.
`operations: AppliedOperation[]`	Changes applied by this observation. An empty list can be a no-op or a refused change; inspect the other lists.
`skipped: SkippedWrite[]`	Proposed writes deliberately not stored, with reasons.
`violations: OntologyViolation[]`	Non-conformances, including kind, message and blocking. A warning does not necessarily prevent a write.
`pendingReview: PendingReview[]`	Proposals awaiting a decision. They must not be treated as accepted current facts.

EntityView, Fact and ChangeEvent

EntityView contains entity, facts and relations. The entity includes an ID, canonical reference, type and metadata. A fact associates a predicate and value with that entity.

Fact states
Status	Meaning
current	A value in the accepted current record.
superseded	An earlier value replaced by a later accepted value.
retracted	A value withdrawn from current state.
disputed	A fact carrying a disputed lifecycle status.
pending_review	A fact awaiting review.

A ChangeEvent identifies a recorded change and its provenance, including the source, actor, confidence and timestamp. Use change history when you need to explain an update; fact history lists the values and their lifecycle states.

Schema constraints your client can inspect

Public schema types
Type or field	Client-facing meaning
`OntologyClass`	A class name, optional parent and configurable policy. strict closes the class to undeclared fields and invalid values.
`OntologyPredicate`	A named field with a valueType, cardinality and optional constraints.
`allowedValues / enforced`	A declared value domain; enforced makes the field’s type and domain binding even on an open class.
`required`	Reports missing information. Required-field findings remain advisory.
`aliases`	Accepted alternative names for a declared predicate. Use the canonical name in subsequent reads.
`cardinality`	single stores one current value; multi accepts multiple values; ordered_list treats an incoming array as the whole ordered list.
`OntologyRelationType`	A relationship name, source and target classes, and relation cardinality.

Dates and response formats

TypeScript domain types use Date. JSON response timestamps are ISO strings and the current SDK does not turn them into Date objects automatically. Convert a timestamp explicitly before calling date methods. Use a Date for SDK temporal input and an ISO timestamp for MCP temporal arguments.

Compact response profiles have their own shapes. Read the declared profile, completeness and continuation fields instead of treating every response as a full entity or history.

← SDK guide MCP response contracts →