API reference · USP

Ontology + backfill

Domain-specific schemas without giving up the built-in graph. Bump the ontology, run the backfill, every existing memory re-classifies against the new types.

What an ontology is

The built-in ontology covers nine memory types and a couple dozen predicates. That's usually enough for general-purpose agents but not enough for vertical-specific work — a support agent might want Ticket, Customer,ESCALATED_TO; a sales agent might want Deal, Stakeholder, BLOCKED_BY.

A project can have multiple ontology versions, one marked default. The active default applies to every new ingest. Old memories keep their original tags unless you run a backfill.

Plan availability

Custom ontology is on Scale and Enterprise plans. Backfill is metered against the ingest counter — see pricing.

POST/v1/ontologies

Create a new ontology.

Request

interface CreateOntologyRequest {
  name: string;
  description?: string;
  entityTypes: {
    name: string;            // e.g. "Ticket"
    description?: string;
    aliases?: string[];      // surface forms to detect
  }[];
  edgeTypes: {
    name: string;            // e.g. "ESCALATED_TO"
    description?: string;
    fromTypes?: string[];    // domain hints
    toTypes?: string[];
  }[];
  makeDefault?: boolean;
}

Response (201)

{
  "id": "ont_01HXY...",
  "name": "support",
  "version": 1,
  "isDefault": true,
  "entityTypes": [ { "name": "Ticket", ... } ],
  "edgeTypes": [ { "name": "ESCALATED_TO", ... } ],
  "createdAt": "..."
}

GET/v1/ontologies

List every ontology in the project.

GET/v1/ontologies/:id

Get one with full type + edge definitions.

PUT/v1/ontologies/:id

Replace the types on an existing ontology. Bumps the version field. Existing memories are not rewritten — run a backfill if you want the change to apply retroactively.

POST/v1/ontologies/:id/default

Mark this ontology as the project's default for new ingests.

DELETE/v1/ontologies/:id

Delete an ontology and its type definitions. Memories tagged with this ontology keep their tags but lose the type-definition lookup — preferable to mark it non-default first.

Backfill

The killer feature. When you change an ontology, existing memories are out of step with the new schema. Backfill rewrites them in place against the new version — no data loss, full audit trail.

POST/v1/ontologies/:id/backfill

Kick off a backfill job. Returns a jobId you can poll.

{
  "jobId": "bf_01HXY...",
  "status": "queued",
  "ontologyId": "ont_...",
  "candidateMemories": 1247
}

GET/v1/backfill/:jobId

Poll backfill status.

{
  "jobId": "bf_...",
  "status": "running",
  "processed": 412,
  "total": 1247,
  "rewritten": 88,        // memories whose type changed
  "unchanged": 324,
  "errors": 0
}

GET/v1/backfill

List recent backfill jobs in the project.

Example: adding a support vertical

# 1. Create the ontology
curl -X POST "$MEMOS_URL/v1/ontologies" \
  -H "Authorization: Bearer $MEMOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support",
    "entityTypes": [
      { "name": "Ticket", "aliases": ["case", "issue"] },
      { "name": "Customer" }
    ],
    "edgeTypes": [
      { "name": "ESCALATED_TO", "fromTypes": ["Ticket"], "toTypes": ["PERSON"] },
      { "name": "AFFECTS",      "fromTypes": ["Ticket"], "toTypes": ["Customer"] }
    ],
    "makeDefault": true
  }'

# 2. Backfill existing memories
curl -X POST "$MEMOS_URL/v1/ontologies/ont_xxx/backfill" \
  -H "Authorization: Bearer $MEMOS_KEY"

# 3. Poll until done
curl "$MEMOS_URL/v1/backfill/bf_xxx" \
  -H "Authorization: Bearer $MEMOS_KEY"

Next steps