One organization-wide knowledge scope that every project under the tenant can read from. Use it for policies, shared lore, playbooks, or facts that belong to the whole organization rather than a single project.

When to use it

By default, the Knowledge Base is project-scoped. Every project has its own isolated graph. That is the right model for most tenants — a project's data should not leak into other projects' agents.

The organization scope is an opt-in second scope that sits above every project. Knowledge written here is readable by every project agent under the tenant that opts into a cross-scope reading mode. Typical uses:

Company-wide policies (HR, refund, privacy, terms).
Product documentation shared across projects.
Brand guidelines, tone standards, style rules.
Shared lore for multi-game or multi-product characters.
Reference catalogs (locations, entities, product lists).

How it fits with project KB

Tenant (organization)
|
|-- Organization-global KB   (scope_id = "")
|   - policies, shared lore, brand, reference catalogs
|   - written by tenant admins via the org endpoints
|
|-- Project A KB             (scope_id = project_a_id)
|   - A's own uploaded docs + API-pushed facts
|
|-- Project B KB             (scope_id = project_b_id)
|   - B's own uploaded docs + API-pushed facts
|
Agents under any project choose how to read across the two scopes:
- project_only   legacy: just the agent's project KB
- org_only       only the organization-global KB
- cascade        both, project wins on ID collisions (recommended)
- union          both, first occurrence wins

Scope mode on an agent

Every agent has a knowledgeBaseScopeMode capability. Leaving it unset preserves the legacy project-only behavior. To enable the cascade, set it via the capabilities endpoint or the dashboard.

Enable the knowledge base capability and set the project ID via the SDK:

// Enable the knowledge base capability for the agent
_, err := client.Agents.UpdateCapabilities(ctx, agentID, sonzai.UpdateCapabilitiesOptions{
  KnowledgeBase: func(b bool) *bool { return &b }(true),
})

Writing to the org scope

There are two ways a tenant admin can populate the org scope. Both are backend-only endpoints — end users of your products never see them.

1. Create a node directly in the org scope

Use this for hand-authored facts that should live at the organization level from the start.

node, err := client.Knowledge.CreateOrgNode(ctx, tenantID, sonzai.CreateOrgNodeOptions{
NodeType: "policy",
Label:    "Refund Policy",
Properties: map[string]any{
  "description": "Full refund available within 30 days of purchase.",
},
})

2. Promote an existing project node

If a fact already lives in a project KB and you want to share it organisation-wide, promote it. The project copy is preserved — promotion is additive. If an org node with the same (node_type, norm_label) already exists, the server returns that one instead of writing a duplicate.

orgNode, err := client.Knowledge.PromoteNodeToOrg(ctx, projectID, nodeID, tenantID)

Reading: cascade search and provenance

When an agent with a non-default scope mode calls knowledge_search during a conversation, the platform runs the search against both scopes in parallel and fuses the results using Reciprocal Rank Fusion (RRF). Each returned result carries a scope field so your prompt can show the LLM where a fact came from.

Agent's knowledge_search("refund policy")
       |
       v
+----------------------------+       +----------------------------+
| Project BM25  (scope=proj) |  +--> | Org BM25      (scope="")   |
+----------------------------+       +----------------------------+
       |                                         |
       +--------------- RRF fuse ----------------+
                       |
                       v
          Top-N results, each tagged:
            scope: "project" | "organization"

Scope modes differ in how they merge on a collision:

cascade (recommended): project wins on duplicate node IDs. Agents keep their own overrides, but inherit the org defaults when a project doesn't define something.
union: first occurrence wins; both scopes contribute equally to ranking. Useful when you want broad coverage without a strong preference.
org_only: skip project KB entirely. Useful for reference-only agents (FAQ bots on company policy, e.g.).
project_only (default): legacy behavior, org-scope facts are invisible to this agent.

Dashboard admin UI

A tenant admin can manage org-scope knowledge at /dashboard/knowledge/org:

Create a node directly in the org scope.
Promote an existing project node by pasting its project ID and node ID.

The UI is a thin wrapper over the same endpoints shown above; if you need bulk operations or automated pipelines, the SDKs are the recommended path.

Operational notes

Access control: the two org-scope write endpoints are gated by the same tenant-admin middleware used by the existing project-scoped KB endpoints. Standard project members see no new surface.
Backward compatibility: zero change for any existing agent. Agents stay on project_only mode unless you set a scope mode explicitly.
Idempotency: dedup is at (node_type, norm_label). Promotion returns the existing org node if one is already there; direct createOrgNode will create a second node with a different NodeID — check before calling if that matters.
Per-scope BM25: each scope maintains its own BM25 index and document-frequency corpus. This is why the cascade uses RRF instead of score-adding — the raw scores from two separate indexes are not directly comparable.

Organization-Global Knowledge Base