Models & Types

All public types are exported from the package root:

import type {
  EventPayload,
  EventKind,
  IngestResponse,
  SearchResponse,
  SearchResult,
  SourceEvent,
  StatusResponse,
  HealthResponse,
  ClearResponse,
  UsageInfo,
  RateLimitInfo,
} from '@memsy-io/memsy';

The SDK is camelCase end-to-end. The HTTP wire format is snake_case (actor_id, session_id, event_ids); serialization happens automatically inside the client.

Request types

EventPayload

The shape you pass to client.ingest().

EventKind

type EventKind =
  | 'user_message'
  | 'assistant_message'
  | 'tool_result'
  | 'app_event';

See Events & Memories for guidance on which to use.

Response types

Every successful response carries usage and rateLimit parsed from response headers — the call returned, but you also know how much of your plan you've burned.

IngestResponse

SearchResponse

SearchResult

SourceMetadata

User-supplied event metadata propagated to memories derived from those events. Surfaced on SearchResult.sourceMetadata.

SourceEvent

A typed view of the events a memory was extracted from. Surfaced on SearchResult.sourceEvents whenever includeSourceEvents: true is passed to client.search(). The wire format embeds these as snake-cased dicts inside metadata.source_events; the SDK parses them and converts to camelCase for you.

const results = await client.search('preferences', {
  actorId: 'user_42',
  includeSourceEvents: true,
});

for (const r of results.results) {
  console.log(r.content);
  for (const src of r.sourceEvents ?? []) {
    console.log(`  ↳ from ${src.kind} at ${src.ts}: ${src.content}`);
  }
}

StatusResponse

HealthResponse

ClearResponse

Metadata types

UsageInfo

Snapshot of your plan consumption parsed from X-Usage-* and X-Plan headers.

Any field is null when the platform hasn't reported it on this response.

RateLimitInfo

Parsed from X-RateLimit-* headers.

Populated on every authenticated response — the rate-limit dimension is api_calls.

const { rateLimit } = await client.search('preferences');

if (rateLimit.remaining !== null && rateLimit.remaining < 5) {
  console.warn(`Only ${rateLimit.remaining} requests left.`);
}

Onboarding types

Org, Role, Team

All three share a common shape and differ only in the ID fields.

Console memory types

MemoryItem

MemoryScope

MemoryListResponse / MemoryStatsResponse

MemoryListResponse is { items: MemoryItem[]; total: number; limit: number; offset: number }.

MemoryStatsResponse carries aggregate counts: total, totalMemories, activeMemories, byType, byKind, byStatus, avgConfidence, avgStrength, topEntities, confidenceBuckets, dateRange.

Control-plane types

MeResponse

BillingSummary

{ tier, purchasedSeats, assignedSeats, availableSeats, stripeCustomerId, paymentMethod, upcomingInvoice, subscriptionStatus, billingContact, stripeSubscriptionId }.

PaymentMethod is { brand, last4, expMonth, expYear }. UpcomingInvoice is { amountDue, currency, periodEnd }.

Invoice

{ id, amountDue, amountPaid, currency, status, created, hostedInvoiceUrl }.

ApiKeyInfo / ApiKeyListResponse / CreateKeyResponse

ApiKeyInfo:           { keyId, prefix, name, scopes, isActive, createdAt, lastUsedAt, expiresAt }
ApiKeyListResponse:   { keys: ApiKeyInfo[], maxKeys, activeCount }
CreateKeyResponse:    { keyId, rawKey, prefix, name, scopes }

rawKey is returned only once on create — store it securely.

UsageSummaryResponse / UsageTimeseriesResponse

DimensionUsage:           { dimension, used, limit, overageRate }
UsageSummaryResponse:     { orgId, tier, periodStart, periodEnd, dimensions: DimensionUsage[] }
TimeseriesPoint:          { date, dimension, quantity }
UsageTimeseriesResponse:  { orgId, granularity, data: TimeseriesPoint[] }

EventItem / EventListResponse

EventItem:           { eventId, orgId, actorId, kind, content, ts, sessionId, metadata, ingestedAt }
EventListResponse:   { items: EventItem[], total, limit, offset }

ProInterestResponse

{ message: string }.

See also

• MemsyClient — hot-path client
• MemsyControlClient — control-plane client
• Errors — exception classes