Scopes & visibility

Unison has no permission matrix. Visibility is decided by path prefix at write time — and can be promoted later with a share call. Three writable roots:

Read-only roots: /system/ (synthesized views), /private/sources/ (connector ingest). Writes to these return 403.

Writing to a shared path

await brain.write({
  path: "/workspace/runbooks/deploy.md",
  bodyMd: "# Deploy runbook\n\n`bun run deploy`",
  title: "Deploy runbook",
});

// Team-scoped
await brain.write({
  path: "/workspace/teams/platform/decisions/adr-007.md",
  bodyMd: "# ADR-007…",
  title: "ADR-007: pgmq migration",
});

Promoting a private item

An item written to /private/ can be promoted to workspace visibility without rewriting:

curl -X POST https://brain.unisonlabs.ai/v1/brain/share \
  -H "Authorization: Bearer $UNISON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "doc", "id": "doc_…" }'

unison share doc <id>

Facts and entities can be shared the same way: { "kind": "fact" | "entity", "id": "…" }.

Document ingest visibility

When ingesting documents, pass visibility to control where the content lands:

await brain.ingest({
  items: [{
    type: "document",
    content: "…",
    title: "Q3 pricing decision",
    sourceRef: "doc-99",
    visibility: "workspace",   // visible to whole workspace
  }],
});

Default is "private".

Conversation capture (POST /v1/brain/remember) doesn't take a visibility field — it's an async curation call (dump, source, sourceRef, hints), and the curation step files the resulting notes and facts. Use document ingest or write when you need explicit placement.

Scoping recall and search

Both recall and search respect path prefix. Confine a session to its lane:

const ctx = await brain.context({
  q: "deploy process",
  pathPrefix: "/workspace/teams/platform/",
});

unison context "deploy process" --path-prefix /workspace/teams/platform/

Actor delegation (per-user private namespaces)

With brain:act-as, one service key serves many end users. Each actor id automatically gets an isolated /private/ namespace — the actor cannot read another actor's private documents, but all actors share /workspace/:

const u1 = brain.withActor("user-001");
await u1.write({ path: "/private/notes/chat.md", bodyMd: "…" });   // user-001 only

const u2 = brain.withActor("user-002");
await u2.search("notes");   // no cross-actor leakage

See also: Shared vs private memory concept · Auth & API keys · API reference