DocumentationAPI ReferenceKnowledge Base
Learn

Scopes & visibility

Where you write is who sees it. /private/ for the caller, /workspace/teams/<slug>/ for a team, /workspace/ for the whole workspace. No permission matrix.

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:

Path prefixVisible to
/private/only the calling key (or actor)
/workspace/teams/<slug>/members of that team within the workspace
/workspace/all workspace members

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": "…" }.

Ingest visibility

When ingesting conversations or documents, pass visibility to control where extracted knowledge lands:

await brain.ingest({
  items: [{
    type: "conversation",
    sourceRef: "session-99",
    turns: [ … ],
    visibility: "workspace",   // extracted facts visible to whole workspace
  }],
});

Default is "private".

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

Timeline

Read an entity's fact history over time. asOf queries answer what the brain believed on a given date — useful for debugging decisions made with stale information.

Workspaces & teams

A workspace is the top-level isolation boundary. Teams are named sub-groups within it with their own path namespace. Invite members with POST /v1/auth/invitations.

On this page

Writing to a shared pathPromoting a private itemIngest visibilityScoping recall and searchActor delegation (per-user private namespaces)