diff --git a/packages/mnemopi/src/core/runtime-options.ts b/packages/mnemopi/src/core/runtime-options.ts
index 3e940c57f..56f002272 100644
--- a/packages/mnemopi/src/core/runtime-options.ts
+++ b/packages/mnemopi/src/core/runtime-options.ts
@@ -51,6 +51,8 @@ export interface MnemopiLlmRuntimeOptions {
 export interface MnemopiRuntimeOptions {
 	embeddings?: false | MnemopiEmbeddingRuntimeOptions;
 	llm?: false | MnemopiLlmRuntimeOptions | Model<Api> | MnemopiLlmCompletion;
+	/** Verbose diagnostics: escalates best-effort failure logs from debug to warn. */
+	debug?: boolean;
 }
 
 export interface ResolvedMnemopiEmbeddingRuntimeOptions {
@@ -75,6 +77,7 @@ export interface ResolvedMnemopiLlmRuntimeOptions {
 export interface ResolvedMnemopiRuntimeOptions {
 	embeddings?: ResolvedMnemopiEmbeddingRuntimeOptions;
 	llm?: ResolvedMnemopiLlmRuntimeOptions;
+	debug?: boolean;
 }
 
 const runtimeOptionsStorage = new AsyncLocalStorage<ResolvedMnemopiRuntimeOptions>();
@@ -90,6 +93,11 @@ export function getMnemopiRuntimeOptions(): ResolvedMnemopiRuntimeOptions | unde
 	return runtimeOptionsStorage.getStore();
 }
 
+/** Whether the active runtime scope requested verbose diagnostics (`mnemopi.debug`). */
+export function mnemopiDebugEnabled(): boolean {
+	return runtimeOptionsStorage.getStore()?.debug === true;
+}
+
 export function resolveEmbeddingProvider(
 	provider:
 		| MnemopiEmbeddingProvider