{"record":{"id":"58acda3724898826","repo":"mastra-ai/mastra","slug":"knowledge-tools-require-a-configured-knowledge-sto","errorCode":null,"errorMessage":"Knowledge tools require a configured knowledge storage domain.","messagePattern":"Knowledge tools require a configured knowledge storage domain\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/memory/src/processors/observational-memory/subconscious/knowledge-tools.ts","lineNumber":45,"sourceCode":"  agent?: { threadId?: string; resourceId?: string };\n  requestContext?: { get(key: string): unknown };\n};\n\nfunction resolveScope(context: KnowledgeToolContext | undefined): KnowledgeScope {\n  const organizationId = context?.requestContext?.get('organizationId');\n  const resourceId = resolveKnowledgeResourceId(context?.requestContext, context?.agent?.resourceId);\n  const threadId = context?.agent?.threadId;\n  if (typeof organizationId !== 'string' || !organizationId.trim()) {\n    throw new Error('Knowledge tools require requestContext.organizationId.');\n  }\n  if (!resourceId) throw new Error('Knowledge tools require an active resourceId.');\n  if (!threadId) throw new Error('Knowledge tools require an active threadId.');\n  return [`org:${organizationId}`, `resource:${resourceId}`, `thread:${threadId}`];\n}\n\nasync function getKnowledgeStore(memory: KnowledgeToolsMemory): Promise<KnowledgeStorage> {\n  const store = await memory.storage.getStore('knowledge');\n  if (!store) throw new Error('Knowledge tools require a configured knowledge storage domain.');\n  return store;\n}\n\nfunction normalizeLimit(limit: number | undefined): number {\n  return Math.min(Math.max(limit ?? DEFAULT_LIMIT, 1), MAX_LIMIT);\n}\n\nfunction serializeRecord(record: KnowledgeRecord) {\n  return {\n    id: record.id,\n    text: record.text,\n    scope: record.scope,\n    sourceThreadId: record.sourceThreadId,\n    capturedAt: record.capturedAt.toISOString(),\n    when: record.when?.toISOString(),\n  };\n}\n","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/memory/src/processors/observational-memory/subconscious/knowledge-tools.ts#L27-L63","documentation":"Knowledge tools resolve their storage through memory.storage.getStore('knowledge'), a named storage domain that must be explicitly configured. When no 'knowledge' store is registered on the storage adapter, getKnowledgeStore throws this error because reads and writes would have nowhere to persist. It is a configuration-time problem surfaced at tool execution time.","triggerScenarios":"Executing any knowledge tool (knowledge_read, knowledge_search, knowledge_list_related) against a memory/storage instance that was created without registering the 'knowledge' storage domain.","commonSituations":"Using a storage adapter that does not implement named stores; upgrading @mastra/core without running the storage migration that provisions the knowledge domain; pointing memory at an in-memory or minimal storage configured only for messages/working memory.","solutions":["Configure the 'knowledge' storage domain on the storage adapter backing the memory instance (e.g. a Postgres/LibSQL store that supports named stores).","Run any pending storage migrations/provisioning so the knowledge store is created.","If the environment cannot host a knowledge store, disable the observational-memory knowledge tools instead of instantiating them.","Confirm memory.storage.getStore('knowledge') resolves (not undefined) before wiring createKnowledgeTools."],"exampleFix":"// before\nconst memory = new Memory({ storage: minimalStorage });\nconst tools = createKnowledgeTools(memory);\n// after\nconst memory = new Memory({ storage: storageWithKnowledgeDomain }); // getStore('knowledge') configured\nconst tools = createKnowledgeTools(memory);","handlingStrategy":"fallback","validationCode":"const store = await memory.storage.getStore('knowledge');\nif (!store) {\n  console.warn('Knowledge domain not configured; skipping knowledge tools.');\n  return;\n}","typeGuard":"async function hasKnowledgeStore(memory: { storage: { getStore(n: 'knowledge'): Promise<unknown> } }): Promise<boolean> {\n  return (await memory.storage.getStore('knowledge')) !== undefined;\n}","tryCatchPattern":"try {\n  return await tools.knowledge_search.execute(args, ctx);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('knowledge storage domain')) {\n    return { found: false, reason: 'knowledge-store-not-configured' };\n  }\n  throw e;\n}","preventionTips":["Provision the 'knowledge' storage domain during storage setup/migrations.","Gate tool registration on getStore('knowledge') resolving successfully.","Use a storage adapter that supports named stores.","Add an integration smoke test asserting the knowledge store exists in each environment."],"tags":["knowledge-tools","storage-configuration","missing-store","mastra-memory"],"backgroundTag":"missing-storage-domain","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}