Reference

Data model.

The response shapes you get back from the REST API and the typed SDK. Every type below is exported from @pambase/sdk. Field names match the wire format exactly.

Memory

A single durable fact about the user, written in natural language. Returned by listMemories(), iterateMemories(), and getMemory. See Memory and the kind list in the Catalog.

Memory

interface Memory {
  id: string;
  // Advisory structural hint (a MemoryKind). The values below autocomplete,
  // but the field is free-form — any string is accepted (e.g. "task").
  type:
    | "fact"
    | "preference"
    | "event"
    | "relationship"
    | "emotion"
    | "goal"
    | "world"
    | "summary"
    | (string & {});
  scope: string;          // e.g. "fitness", "schedule.calendar"
  content: string;        // natural language
  importance: number;     // 0–100
  confidence: number;     // 0–100
  pinned: boolean;
  occurredAt: string;     // ISO 8601
  sourceApp?: string | null;
}

ContextBundle

The assembled payload from getContext() / GET /v1/context: the light identity profile, the most relevant memories (a subset of fields), related entities, and adaptation hints. See Context.

ContextBundle

interface ContextBundle {
  identity: { aiId: string; name: string; /* light profile */ };
  memories: Array<
    Pick<Memory, "id" | "type" | "scope" | "content" | "importance" | "occurredAt" | "sourceApp">
  >;
  relationships: Array<{ subject: string; relation: string; object: string }>;
  suggestions: { adaptation: string; tags?: string[] };
  generatedAt: string; // ISO 8601
}

identity here is the light profile

identity carries the display name and an optional tone note — that is it. Apps bring their own persona and model; PAMbase never exposes user-authored archetype, mood, voice, or visual fields. See Identity.

IdentityBrief

From getIdentityBrief() / GET /v1/identity/brief — a ready-to-prompt paragraph, cached for 5 minutes. See Identity brief.

IdentityBrief

interface IdentityBrief {
  brief: string;                // one paragraph, prompt-ready
  ai_name: string;              // display name
  generated_at: string;         // ISO 8601
  source_memory_count: number;  // memories that informed the brief
  cached: boolean;
}

Connection

From getConnection() / GET /v1/connection. The base record is intersected with the resolved ai and app.

Connection

interface Connection {
  id: string;
  userId: string;
  aiId: string;
  appId: string;
  scopes: string[];
  status: string;       // e.g. "active" | "revoked"
  connectedAt: string;  // ISO 8601
}

// getConnection() returns: Connection & { ai: AIIdentity; app: ConnectedApp }

GatewayChatResponse

From chat() / POST /v1/gateway/chat — the hosted-inference reply plus the memory candidates the turn produced. See Gateway.

GatewayChatResponse

interface GatewayChatResponse {
  reply: string;
  toneTags: string[];
  memoryCandidates: Array<{
    type: Memory["type"];
    scope: string;
    content: string;
    importance: number; // 0–100
  }>;
  usage: { tokensIn: number; tokensOut: number; model: string };
}

The streaming variant (chatStream()) yields a discriminated union of frames instead of one object:

ChatStreamEvent

type ChatStreamEvent =
  | { type: "delta"; text: string }
  | { type: "memory_recorded"; candidate: GatewayChatResponse["memoryCandidates"][number] }
  | { type: "done"; usage: { tokensIn: number; tokensOut: number; model: string } }
  | { type: "error"; message: string };

Webhook payloads

Outbound webhooks arrive as a tagged union. Verify the signature, then branch on type. The canonical field list for each payload is in the Catalog; delivery and verification details are in Webhooks.

PAMbaseWebhookEvent

type PAMbaseWebhookEvent =
  | { type: "memory.created";  data: { /* see Catalog */ } }
  | { type: "signal.created";  data: { /* see Catalog */ } }
  | { type: "schedule.fired";  data: { /* see Catalog */ } };

// Every delivery carries an X-PAMbase-Delivery id for idempotency
// and an X-PAMbase-Signature header for HMAC verification.

Idempotent delivery

Deduplicate on the X-PAMbase-Delivery header — retried deliveries reuse the same id. See Glossary and Webhooks.