API Documentation

Real-time Events

Real-time SSE event stream for memory/profile change propagation with typed event envelopes and optional per-subject filtering.

Subscribe to real-time memory events using Server-Sent Events (SSE). Get instant notifications when memories are created, updated, superseded, or when profile fields change.

GET /api/v1/events/memories

Subscribe to real-time memory events via Server-Sent Events (SSE). The connection stays open and streams events as they occur.

Scope: memories:read or events:read

subject_id

  • Type: string
  • Optional. Filter events to a specific subject. If omitted, receives all events for the project.

Request

curl -N "https://www.mnexium.com/api/v1/events/memories?subject_id=user_123" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Accept: text/event-stream"

Event Types

  • connected - Initial connection confirmation
  • memory.created - A new memory was created
  • memory.updated - A memory was updated
  • memory.deleted - A memory was deleted
  • memory.superseded - A memory was superseded by a newer one
  • profile.updated - Profile fields were updated
  • heartbeat - Keepalive signal (every 30s)

Example Events

event: connected
data: {"project_id":"proj_abc","subject_id":"user_123","timestamp":"2024-12-15T10:30:00Z"}

event: memory.created
data: {"id":"mem_xyz","subject_id":"user_123","text":"User prefers dark mode","kind":"preference","importance":75}

event: memory.superseded
data: {"id":"mem_old123","superseded_by":"mem_xyz"}

event: profile.updated
data: {"subject_id":"user_123","fields":{"name":"John","timezone":"America/New_York"},"updated_at":"2024-12-15T10:31:00Z"}

event: heartbeat
data: {"timestamp":"2024-12-15T10:31:30Z"}

Usage Example

# SSE stream stays open — events arrive in real time
curl -N "https://www.mnexium.com/api/v1/events/memories?subject_id=user_123" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Accept: text/event-stream"

Recommendation: Use SSE instead of polling for real-time updates. Events are delivered immediately when memories change and reduce unnecessary API traffic.