Ingest

POST /v1/brain/ingest is the document write. Send up to 100 items per call, each type: "document". Documents land as extractable notes at a brain path. The response returns job ids — extraction is never synchronous.

Conversations and session dumps don't go through ingest — they go through POST /v1/brain/remember, which runs the save-or-skip curation pipeline (dedupe, curated /private/notes notes, entity facts) before filing anything.

Save a conversation

import { BrainClient } from "@unisonlabs/sdk";

const brain = new BrainClient({ token: process.env.UNISON_TOKEN });

await brain.remember({
  dump: {
    turns: [
      { role: "user",      content: "switch the queue to pgmq" },
      { role: "assistant", content: "Done — migrated worker, dropped redis." },
    ],
  },
  sourceRef: "session-42",            // your stable session/thread id
});

curl -X POST https://brain.unisonlabs.ai/v1/brain/remember \
  -H "Authorization: Bearer $UNISON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dump": {
      "turns": [
        { "role": "user",      "content": "switch the queue to pgmq" },
        { "role": "assistant", "content": "Done — migrated worker, dropped redis." }
      ]
    },
    "sourceRef": "session-42"
  }'

Both calls return { "jobId": "job_..." } — remember runs as a background job; poll GET /v1/brain/jobs/{jobId} for status.

Ingest a document

await brain.ingest({
  items: [{
    type: "document",
    content: "# ADR-007\n\nWe moved the job queue from Redis to pgmq on 2026-05-10…",
    title: "ADR-007: pgmq migration",
    path: "/workspace/decisions/adr-007-pgmq.md",
    visibility: "workspace",
  }],
});

Item shape (ingest)

// Document — the only item type ingest accepts
{
  type: "document",
  content: string,
  title?: string,
  path?: string,               // brain path; auto-routed to /private/ if omitted
  tags?: string[],
  visibility?: "private" | "workspace",
  sourceRef?: string
}

remember's body is a separate shape — see POST /v1/brain/remember for dump (string, { turns }, or { sessionJsonl }), source, sourceRef, and hints.

What gets extracted

Documents sent to ingest land at a stable brain path as extractable notes — no curation judgment, no entity extraction. Dumps sent to remember run the save-or-skip curation pipeline: it decides whether the dump is worth keeping, dedupes against existing notes, and files curated /private/notes notes plus entity facts. Neither is instant — check job state with GET /v1/brain/jobs/{id}, GET /v1/brain/status (pendingJobs, lastIngestAt), or unison jobs ls.

sourceRef and idempotency

sourceRef is your stable caller-side id (a session id, thread id, webhook message id) on both endpoints. Re-sending the same sourceRef is safe — ingest treats it as a dedup anchor for the document, and remember treats it as a no-op re-run of the same dump.

Visibility

ingest documents take an explicit visibility:

remember has no visibility field — curated notes are filed under /private/notes by the pipeline itself.

For direct document writes with explicit path control, use PUT /v1/brain/doc — see Documents.

See also: API reference, API reference