Event Ingestion

Use event ingestion when a system action should become future memory.

Examples:

deployments
incidents
CI runs
pull requests
code review findings
support tickets
user preferences
operational decisions

Route

HTTP

POST /v1/memory/events

Requires memory:write.

When environments are enabled, the credential determines whether the event enters Test, Staging, or Production. Do not put an Achiral environment ID in the request payload or use the payload's domain-specific metadata.environment value for routing. See Memory API environments.

Payload

JSON

{
  "type": "deployment.completed",
  "source": "github-actions",
  "subject": "api-service",
  "text": "api-service commit abc123 deployed to production.",
  "metadata": {
    "repo": "acme/api-service",
    "sha": "abc123",
    "environment": "production"
  }
}

Required fields:

Field	Purpose
`type`	Stable event type such as `deployment.completed` or `incident.resolved`.
`text`	Human-readable event summary that can be triaged into memory.

Recommended fields:

Field	Purpose
`source`	System that emitted the event.
`subject`	Service, customer, repo, workflow, or entity the event is about.
`metadata`	Structured source details such as repo, SHA, environment, ticket id, or URL.

Send Idempotency-Key when retrying event submissions. If no explicit key is provided, Achiral derives a deterministic key from the developer event source, event type, and normalized payload hash.

Idempotency is scoped to the selected environment. The same source event can be ingested once in Test, once in Staging, and once in Production without a collision. Retries within one environment continue to resolve to the same event.

Test and Staging suppress production automation, customer-facing notifications, and irreversible external writes by default. Event ingestion can still create environment-scoped records and memory candidates for validation.

SDK

TypeScript

await chiro.events.ingest({
  type: "incident.resolved",
  source: "pagerduty",
  subject: "auth-service",
  text: "Resolved elevated 401s after rotating the stale JWKS cache.",
  metadata: {
    incidentId: "INC-123",
    severity: "sev2",
  },
});

Events flow through Achiral's generic ingestion pipeline as developer_event sources and can create BusinessEvent records, workflow state, and memory candidates.