knowledgeMemoryScopes()

knowledgeMemoryScopes() returns scope declarations for the resource: and thread: scopes every Memory run holds, plus a tenant scope. Spread it into the Knowledge scopes option so agents with Memory can use Knowledge. See Scope declarations for how declarations work.

alpha

Knowledge is in alpha. Its API may change between releases.

Usage example

src/mastra/knowledge.ts

import { Knowledge, knowledgeMemoryScopes } from '@mastra/core/knowledge'

export const knowledge = new Knowledge({
  tools: true,
  scopes: {
    ...knowledgeMemoryScopes(),
    'team:$orgId:$teamId': { access: [{ principal: 'self', role: 'editor' }] },
  },
})

Parameters

org?:

string | false

= 'org:$orgId'

The tenant scope pattern. Rename it, for example workspace:$workspaceId, or pass false to leave the tenant out. With false, resource: has no belongsTo.

orgRole?:

'editor' | 'contributor'

= 'editor'

The role a run holding the tenant scope gets on it. contributor makes the tenant append-only: runs add pages and notes but can't edit them.

Returns

KnowledgeScopeDeclarations with three entries, or two when org is false:

Key	Access	belongsTo	pinnedContextPriority
thread:$threadId	self owner	resource:$resourceId	2
resource:$resourceId	self owner	org:$orgId	1
org:$orgId	self editor	none	0

The tenant row uses the org and orgRole options. Stored pins aimed at a scope with a higher pinnedContextPriority come first. A run gets its thread pins, then its resource pins, then tenant pins.

knowledgeMemoryScopes({ org: 'workspace:$workspaceId', orgRole: 'contributor' })
// {
//   'thread:$threadId': { access: [{ principal: 'self', role: 'owner' }], belongsTo: 'resource:$resourceId', pinnedContextPriority: 2 },
//   'resource:$resourceId': { access: [{ principal: 'self', role: 'owner' }], belongsTo: 'workspace:$workspaceId', pinnedContextPriority: 1 },
//   'workspace:$workspaceId': { access: [{ principal: 'self', role: 'contributor' }], pinnedContextPriority: 0 },
// }

knowledgeScopeAddress()

knowledgeScopeAddress(pattern: string, params: Record<string, string>): string

Builds a canonical scope address from a pattern and raw parameter values. Use it in host code for Knowledge APIs, pinnedContext entries and page references.

Inside values, %, / and # are encoded as %25, %2F and %23. : is encoded as %3A in every parameter except the last. It throws when a parameter is missing or empty.

import { knowledgeScopeAddress } from '@mastra/core/knowledge'

knowledgeScopeAddress('resource:$resourceId', { resourceId: 'acme/dana' })
// 'resource:acme%2Fdana'

knowledgeScopeAddress('team:$orgId:$teamId', { orgId: 'a:b', teamId: 'c:d' })
// 'team:a%3Ab:c:d'

note

Don't pass the result as an agent scope. Agent scopes take raw IDs (resource:acme/dana), and Knowledge encodes them at run start. See set a run's scopes.

Related

• Knowledge class
• Scope declarations
• Pinned context