Import

Five importers, one job lifecycle. All accept a scope template (placeholders filled per row) and return 202 Accepted with a lifecycle_stream URL. Track progress via GET /v1/import/ or subscribe to import_progress / import_complete / import_error lifecycle events.

Stability: beta — mapping tables track source-system version drift.

---

POST /v1/import/jsonl — Generic

{
  "scope_template": "org:acme/user:{user_id}",
  "lines": [
    "{\"user_id\":\"alice\",\"modality\":\"conversation\",\"content\":{\"kind\":\"message\",\"role\":\"user\",\"text\":\"...\"},\"context\":{\"observed_at\":\"...\"},\"idempotency_key\":\"k1\"}",
    "..."
  ]
}

Each line must be a valid experience envelope minus scope (which the server fills from the template using fields in each line).

Response — 202

{
  "import_id": "imp_01HX...",
  "status": "running",
  "estimated_items": 1284,
  "lifecycle_stream": "/v1/lifecycle/stream?import_id=imp_01HX..."
}

---

POST /v1/import/mem0 — Mem0 exports

{
  "scope_template": "org:acme/user:{user_id}",
  "rows": [
    { "user_id": "alice", "memory": "...", "timestamp": "...", "metadata": {...} }
  ]
}

Map: memory → content.text, timestamp → context.observed_at, metadata → context.labels + context.intent.

---

POST /v1/import/zep — Zep exports

{
  "scope_template": "org:acme/user:{user_id}",
  "rows": [
    { "user_id": "alice", "fact": "...", "valid_from": "...", "valid_to": "..." }
  ]
}

Zep facts land as triples via content.kind = "triple". Bi-temporal fields preserved.

---

POST /v1/import/letta — Letta exports

{
  "scope": "org:acme/user:alice",
  "rows": [
    { "block_label": "...", "value": "...", "limit": 2000 }
  ]
}

Letta blocks land as modality: "document" with the block label as context.intent.

---

POST /v1/import/openai — OpenAI memory exports

{
  "scope": "org:acme/user:alice",
  "rows": [
    { "id": "...", "content": "...", "created_at": "..." }
  ]
}

---

GET /v1/import/

{
  "import_id": "imp_01HX...",
  "status":    "completed",
  "imported":  1284,
  "failed":    0,
  "elapsed_ms": 84000,
  "lifecycle_stream": "/v1/lifecycle/stream?import_id=imp_01HX..."
}

status ∈ { running, completed, failed, cancelled }.