Pinned knowledge requires a configured knowledge storage dom

Error message

Pinned knowledge requires a configured knowledge storage domain.

What it means

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.

Source

Thrown at packages/memory/src/processors/observational-memory/subconscious/pinned.ts:167

): Promise<KnowledgeRecord> {
  const { pins } = await listPinnedKnowledge({ store, scope: options.scope });
  assertBudget(options, pins, text);
  const nodeId = await ensurePinnedNodeId(store, options.scope, options.maxScope);
  return store.appendKnowledge({
    node: nodeId,
    text,
    scope: resolveWriteScope(options, level),
    sourceThreadId: options.sourceThreadId,
    maxScope: options.maxScope,
    metadata,
    resolutionScope: options.scope,
    defaultScope: expandKnowledgeScope(options.scope, options.defaultScope),
  });
}

async function getStore(memory: PinnedMemory): Promise<KnowledgeStorage> {
  const store = await memory.storage.getStore('knowledge');
  if (!store) throw new Error('Pinned knowledge requires a configured knowledge storage domain.');
  return store;
}

async function requirePin(
  store: KnowledgeStorage,
  recordId: string,
  options: PinnedToolsOptions,
): Promise<KnowledgeRecord> {
  const record = await store.getKnowledge({ id: recordId, includeDeleted: false });
  if (!record) throw new Error(`Pin not found: ${recordId}`);
  const nodeId = await resolvePinnedNodeId(store, options.scope);
  if (!nodeId || record.node !== nodeId) throw new Error(`Record is not a pin: ${recordId}`);
  if (!isKnowledgeScopeVisible(record.scope, options.scope)) throw new Error('Pin is outside the visible scope.');
  return record;
}

/**
 * Pin lifecycle tools. Pin appends a record on the reserved node; unpin soft-deletes it

View on GitHub (pinned to 75dd419e61)

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

Example fix

// before
const pinned = createPinnedTools({ memory }); // memory.storage has no knowledge domain
// Error: Pinned knowledge requires a configured knowledge storage domain.
// after: ensure the knowledge domain is registered
const store = await memory.storage.getStore('knowledge');
if (!store) throw new Error('Enable the knowledge storage domain before using pins');

Defensive patterns

Strategy: validation

Validate before calling

const store = await memory.storage.getStore('knowledge');
if (!store) throw new Error('Pinned knowledge needs the knowledge storage domain configured on memory.storage.');

Type guard

function hasKnowledgeStore(s) {
  return typeof s === 'object' && s !== null && typeof s.getKnowledge === 'function';
}

Try / catch

try {
  const pins = await listPins(memory);
} catch (err) {
  if (err.message.includes('configured knowledge storage domain')) {
    // enable the knowledge domain, then retry
  } else throw err;
}

Prevention

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

When it happens

Trigger: Any pinned tool call or pinned read (list/get/pin/unpin) when memory.storage.getStore('knowledge') returns undefined.

Common situations: 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.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/6024642af4143bb9. Report an issue: GitHub.