{"record":{"id":"6024642af4143bb9","repo":"mastra-ai/mastra","slug":"pinned-knowledge-requires-a-configured-knowledge-s","errorCode":null,"errorMessage":"Pinned knowledge requires a configured knowledge storage domain.","messagePattern":"Pinned knowledge requires a configured knowledge storage domain\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/memory/src/processors/observational-memory/subconscious/pinned.ts","lineNumber":167,"sourceCode":"): Promise<KnowledgeRecord> {\n  const { pins } = await listPinnedKnowledge({ store, scope: options.scope });\n  assertBudget(options, pins, text);\n  const nodeId = await ensurePinnedNodeId(store, options.scope, options.maxScope);\n  return store.appendKnowledge({\n    node: nodeId,\n    text,\n    scope: resolveWriteScope(options, level),\n    sourceThreadId: options.sourceThreadId,\n    maxScope: options.maxScope,\n    metadata,\n    resolutionScope: options.scope,\n    defaultScope: expandKnowledgeScope(options.scope, options.defaultScope),\n  });\n}\n\nasync function getStore(memory: PinnedMemory): Promise<KnowledgeStorage> {\n  const store = await memory.storage.getStore('knowledge');\n  if (!store) throw new Error('Pinned knowledge requires a configured knowledge storage domain.');\n  return store;\n}\n\nasync function requirePin(\n  store: KnowledgeStorage,\n  recordId: string,\n  options: PinnedToolsOptions,\n): Promise<KnowledgeRecord> {\n  const record = await store.getKnowledge({ id: recordId, includeDeleted: false });\n  if (!record) throw new Error(`Pin not found: ${recordId}`);\n  const nodeId = await resolvePinnedNodeId(store, options.scope);\n  if (!nodeId || record.node !== nodeId) throw new Error(`Record is not a pin: ${recordId}`);\n  if (!isKnowledgeScopeVisible(record.scope, options.scope)) throw new Error('Pin is outside the visible scope.');\n  return record;\n}\n\n/**\n * Pin lifecycle tools. Pin appends a record on the reserved node; unpin soft-deletes it","sourceCodeStart":149,"sourceCodeEnd":185,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/memory/src/processors/observational-memory/subconscious/pinned.ts#L149-L185","documentation":"All pinned-knowledge operations funnel through getStore(), which resolves the 'knowledge' storage domain from memory.storage and throws if it is not configured. Pins live in the knowledge store, so without the domain there is nowhere to read or write them and the library fails fast with a configuration error.","triggerScenarios":"Any pinned tool call or pinned read (list/get/pin/unpin) when memory.storage.getStore('knowledge') returns undefined.","commonSituations":"Enabling pinned knowledge on a Memory whose storage lacks the knowledge domain; storage adapters that predate knowledge-domain support; test/ephemeral storage setups that skip domain registration.","solutions":["Configure the 'knowledge' storage domain on the memory instance's storage","Verify with `await memory.storage.getStore('knowledge')` before enabling pinned tools","Use a storage adapter that supports the knowledge domain","Disable pinned-knowledge tooling if the domain is intentionally absent"],"exampleFix":"// before\nconst pinned = createPinnedTools({ memory }); // memory.storage has no knowledge domain\n// Error: Pinned knowledge requires a configured knowledge storage domain.\n// after: ensure the knowledge domain is registered\nconst store = await memory.storage.getStore('knowledge');\nif (!store) throw new Error('Enable the knowledge storage domain before using pins');","handlingStrategy":"validation","validationCode":"const store = await memory.storage.getStore('knowledge');\nif (!store) throw new Error('Pinned knowledge needs the knowledge storage domain configured on memory.storage.');","typeGuard":"function hasKnowledgeStore(s) {\n  return typeof s === 'object' && s !== null && typeof s.getKnowledge === 'function';\n}","tryCatchPattern":"try {\n  const pins = await listPins(memory);\n} catch (err) {\n  if (err.message.includes('configured knowledge storage domain')) {\n    // enable the knowledge domain, then retry\n  } else throw err;\n}","preventionTips":["Configure the knowledge domain before wiring pinned tools","Verify getStore('knowledge') in a smoke test","Avoid adapters without knowledge-domain support for pin workloads","Disable pinned tools explicitly where knowledge storage is not used"],"tags":["configuration","storage","observational-memory"],"backgroundTag":"missing-storage-domain","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}