MemMesh — persistent, self-improving memory for AI agents. Get started →
API ReferencePredictions

Predictions API

There are two distinct prediction routes. They are not the same endpoint with a flag — they return different shapes.

RouteWhat it doesResponse
POST /api/v1/projects/{projectId}/memory-intelligence/predictDeclared target — predict anything from the subject’s observation history when you send a target.targetPrediction
POST /api/v1/projects/{projectId}/lattice/predictPattern projection — project the subject’s mined behavior patterns forward. Ignores target.predictions[], activePatternCount

This page documents the declared-target route. For pattern projection see the shape below. See Predictions for the concept.

Declared target — memory-intelligence/predict

POST /api/v1/projects/{projectId}/memory-intelligence/predict

Predict a declared target from the subject’s history. The estimate comes back in targetPrediction.

Request

{
  "subject": { "kind": "customer", "externalId": "acct-42" },
  "horizonDays": 90,
  "target": {
    "kind": "event_occurrence",
    "eventType": "subscription_cancelled"
  }
}

target object

FieldTypeNotes
kindevent_occurrence | numeric | event_time | anomalyDrives model selection.
eventTypestringThe activity event to predict (event_occurrence / event_time).
attributeKeystringThe typed attribute to predict / monitor (numeric / anomaly).
lookbackDaysnumberHistory window to learn the base rate from. Default 365, capped at 3650.

Response — targetPrediction

Exactly one field group is meaningful per targetKind. Always check abstained first.

{
  "targetPrediction": {
    "targetKind": "event_occurrence",
    "probability": 0.71, "probabilityLower": 0.58, "probabilityUpper": 0.83,
    "value": 0, "valueLower": 0, "valueUpper": 0,
    "expectedAt": "", "expectedAtLower": "", "expectedAtUpper": "", "daysUntil": 0,
    "anomalyScore": 0, "isAnomaly": false,
    "abstained": false,
    "abstentionReason": "",
    "explanation": "12 occurrences in 365d → rate 0.033/day",
    "evidenceMemoryIds": ["mem_…", "mem_…"]
  },
  "abstained": false,
  "abstentionReason": ""
}
Target kindMeaningful fields
event_occurrenceprobability, probabilityLower/Upper
numericvalue, valueLower/Upper
event_timeexpectedAt, expectedAtLower/Upper, daysUntil
anomalyanomalyScore, isAnomaly (latest value in value)

Common to all: abstained, abstentionReason, explanation, evidenceMemoryIds (provenance).

⚠️

abstained: true means unknown — not enough signal to estimate. Never treat it as “no” or “low risk”.

Example

curl https://app.memmesh.ai/api/v1/projects/$PID/memory-intelligence/predict \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "subject": {"kind":"customer","externalId":"acct-42"},
        "horizonDays": 90,
        "target": {"kind":"event_occurrence","eventType":"subscription_cancelled"} }'

The declared-target proxy is metered as a prediction (the memory.predictions meter) and gated by the predictions entitlement, the same as pattern projection.

Pattern projection — lattice/predict

POST /api/v1/projects/{projectId}/lattice/predict

Omit target. The engine reads the subject’s active behavior_pattern memories and extends each one forward by its cadence, returning a ranked list.

Request

{
  "subject": { "kind": "customer", "externalId": "acct-42" },
  "horizonDays": 30,
  "limit": 20,
  "minConfidence": 0.5,
  "occurrencesPerPattern": 1
}

Response

{
  "subject": { "kind": "customer", "externalId": "acct-42" },
  "predictions": [
    {
      "patternId": "mem_…",
      "patternKind": "recurring_event",
      "description": "orders every ~7 days",
      "expectedAt": "2026-07-18T15:00:00Z",
      "confidence": 0.82,
      "windowMinutes": 720,
      "sourceMemoryIds": ["mem_…"]
    }
  ],
  "activePatternCount": 3,
  "eventsEmitted": 0,
  "generatedAt": "2026-07-13T00:00:00Z",
  "durationMs": 9
}

An empty predictions array with activePatternCount: 0 (or nothing over the confidence floor) is an abstention — treat it as “unknown”, not “nothing will happen”. Set emitEvents: true to fire a prediction.imminent event for each prediction due within imminentWithinHours (default 48).

GET /api/v1/projects/{projectId}/lattice/predictions/upcoming returns the project-wide list of upcoming / overdue predicted events (overdue first) with no subject input — the default Predictions view.

Typed AttributesBehavior Discovery