mastra-ai/mastra · error · Error

Knowledge tools require a configured knowledge storage domai

Error message

Knowledge tools require a configured knowledge storage domain.

What it means

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.

Source

Thrown at packages/memory/src/processors/observational-memory/subconscious/knowledge-tools.ts:45

  agent?: { threadId?: string; resourceId?: string };
  requestContext?: { get(key: string): unknown };
};

function resolveScope(context: KnowledgeToolContext | undefined): KnowledgeScope {
  const organizationId = context?.requestContext?.get('organizationId');
  const resourceId = resolveKnowledgeResourceId(context?.requestContext, context?.agent?.resourceId);
  const threadId = context?.agent?.threadId;
  if (typeof organizationId !== 'string' || !organizationId.trim()) {
    throw new Error('Knowledge tools require requestContext.organizationId.');
  }
  if (!resourceId) throw new Error('Knowledge tools require an active resourceId.');
  if (!threadId) throw new Error('Knowledge tools require an active threadId.');
  return [`org:${organizationId}`, `resource:${resourceId}`, `thread:${threadId}`];
}

async function getKnowledgeStore(memory: KnowledgeToolsMemory): Promise<KnowledgeStorage> {
  const store = await memory.storage.getStore('knowledge');
  if (!store) throw new Error('Knowledge tools require a configured knowledge storage domain.');
  return store;
}

function normalizeLimit(limit: number | undefined): number {
  return Math.min(Math.max(limit ?? DEFAULT_LIMIT, 1), MAX_LIMIT);
}

function serializeRecord(record: KnowledgeRecord) {
  return {
    id: record.id,
    text: record.text,
    scope: record.scope,
    sourceThreadId: record.sourceThreadId,
    capturedAt: record.capturedAt.toISOString(),
    when: record.when?.toISOString(),
  };
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Configure the 'knowledge' storage domain on the storage adapter backing the memory instance (e.g. a Postgres/LibSQL store that supports named stores).
2. Run any pending storage migrations/provisioning so the knowledge store is created.
3. If the environment cannot host a knowledge store, disable the observational-memory knowledge tools instead of instantiating them.
4. Confirm memory.storage.getStore('knowledge') resolves (not undefined) before wiring createKnowledgeTools.

Example fix

// before
const memory = new Memory({ storage: minimalStorage });
const tools = createKnowledgeTools(memory);
// after
const memory = new Memory({ storage: storageWithKnowledgeDomain }); // getStore('knowledge') configured
const tools = createKnowledgeTools(memory);

const store = await memory.storage.getStore('knowledge');
if (!store) {
  console.warn('Knowledge domain not configured; skipping knowledge tools.');
  return;
}

async function hasKnowledgeStore(memory: { storage: { getStore(n: 'knowledge'): Promise<unknown> } }): Promise<boolean> {
  return (await memory.storage.getStore('knowledge')) !== undefined;
}

try {
  return await tools.knowledge_search.execute(args, ctx);
} catch (e) {
  if (e instanceof Error && e.message.includes('knowledge storage domain')) {
    return { found: false, reason: 'knowledge-store-not-configured' };
  }
  throw e;
}

When it happens

Trigger: 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.

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

Related errors

• Knowledge write tools require a configured knowledge storage
• Knowledge tools require an active threadId.
• Knowledge tools require requestContext.organizationId.
• Knowledge tools require an active resourceId.
• knowledge_read requires id or name.

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