Should I ingest conversations or write documents directly?

I have both structured facts and raw chat logs to store. Which ingest method should I use for each?

Unison has two ingest paths. They serve different purposes and have different latency characteristics.

Conversation ingest (async)

POST /v1/brain/ingest
# body: {"items":[{"type":"conversation","turns":[{"role":"...","content":"..."}],"sourceRef":"...","visibility":"private"}]}

Best for: raw agent-user exchanges, support transcripts, meeting notes — any unstructured text where you want Unison to automatically extract entities and facts.

• Returns { "items": [ { "type", "jobId" } ] }. Processing is async (seconds to a few minutes depending on length).
• Unison runs entity resolution and fact extraction on the content.
• Recall over these facts becomes available once the job completes.
• More powerful, but you don't control exactly what gets extracted.

Direct document write (synchronous)

PUT /v1/brain/doc
# body: {"path":"/private/notes/my-doc.md","bodyMd":"...","title":"..."}

Best for: structured knowledge you've already curated — decisions, policies, FAQs, reference data.

• Available for recall immediately after the PUT returns.
• You control the content exactly — no extraction, no transformation.
• Useful when you need deterministic, precise information in the brain.

Rule of thumb

If you're feeding raw conversational data and want Unison to do the work of structuring it, use conversation ingest. If you already know what the fact is and want it in the brain right now, write it as a page.

Many applications use both: ingest live agent conversations automatically, and write hand-authored knowledge pages for things like team decisions or onboarding context.