Incognito Mode Patterns

Incognito conversations provide ephemeral, privacy-focused chat sessions with configurable tool access and optional blank slate mode (skips memories and custom instructions).

Core Behavior

Always disabled in incognito:

• Write tools: saveMemory, deleteMemory, manageTasks
• Canvas/Document mode tools

Configurable in incognito:

• Read tools: search (files, notes, tasks, history, memories, knowledge bank)
• Custom instructions application
• Memory injection

Schema Structure

Conversation Table Fields

// From conversations.ts:30-36
isIncognito: v.optional(v.boolean()),
incognitoSettings: v.optional(
  v.object({
    enableReadTools: v.optional(v.boolean()),
    applyCustomInstructions: v.optional(v.boolean()),
    inactivityTimeoutMinutes: v.optional(v.number()),
  }),
),

Creation Pattern

// From conversations.ts:57-67
...(args.isIncognito && {
  isIncognito: true,
  incognitoSettings: {
    enableReadTools: args.incognitoSettings?.enableReadTools ?? true,
    applyCustomInstructions:
      args.incognitoSettings?.applyCustomInstructions ?? true,
    inactivityTimeoutMinutes:
      args.incognitoSettings?.inactivityTimeoutMinutes,
    lastActivityAt: now,
  },
}),

Default behavior: Read tools enabled, custom instructions applied unless explicitly disabled.

Tool Filtering Logic

Write Tools: Always Disabled

// From tools.ts:167-210
// Write tools: DISABLED for incognito
if (!isIncognito) {
  // Memory write tools
  if (enableMemoryWriteTools) {
    tools.saveMemory = createMemorySaveTool(ctx, userId);
    if (memoryExtractionLevel !== "passive") {
      tools.deleteMemory = createMemoryDeleteTool(ctx, userId);
    }
  }

  // Task manager
  tools.manageTasks = createTaskManagerTool(ctx, userId, conversation?.projectId);

  // Document mode tools
  tools.enterDocumentMode = createEnterDocumentModeTool(ctx, conversationId);
  if (isDocumentMode) {
    tools.exitDocumentMode = createExitDocumentModeTool(ctx, conversationId);
    tools.createDocument = createDocumentTool(ctx, userId, conversationId);
    tools.updateDocument = createUpdateDocumentTool(ctx, userId, conversationId);
    tools.readDocument = createReadDocumentTool(ctx, userId, conversationId);
    tools.resolveConflict = createResolveConflictTool(ctx, userId, conversationId);
  }
}

Read Tools: Configurable

// From tools.ts:86-97
const isIncognito = conversation?.isIncognito ?? false;
const incognitoSettings = conversation?.incognitoSettings;
const enableReadTools = !isIncognito || incognitoSettings?.enableReadTools !== false;

// Memory tool settings based on extraction level
const enableMemoryWriteTools = !isIncognito && memoryExtractionLevel !== "none";
const enableMemoryReadTools = enableReadTools && memoryExtractionLevel !== "none";

// From tools.ts:212-238
// Read tools: Configurable for incognito (search user data)
if (enableReadTools) {
  // Memory search: respects extraction level
  if (enableMemoryReadTools) {
    tools.searchMemories = createMemorySearchTool(ctx, userId);
  }

  // Other search tools
  tools.searchFiles = createSearchFilesTool(ctx, userId);
  tools.searchNotes = createSearchNotesTool(ctx, userId);
  tools.searchTasks = createSearchTasksTool(ctx, userId);
  tools.queryHistory = createQueryHistoryTool(ctx, userId, conversationId);
  tools.searchAll = createSearchAllTool(ctx, userId, conversationId, searchCache, budgetState);
  tools.searchKnowledgeBank = createSearchKnowledgeBankTool(ctx, userId, conversation?.projectId);
}

Logic: enableReadTools defaults to true unless explicitly set to false via incognitoSettings.enableReadTools.

Capability Tools: Always Available

Stateless tools (calculator, datetime, web search, URL reader, code execution, weather, YouTube, file docs) are always enabled regardless of incognito mode.

Blank Slate Mode

Skip memories and custom instructions when applyCustomInstructions: false.

// From systemBuilder.ts:59-62
const isBlankSlate =
  conversation?.isIncognito &&
  conversation?.incognitoSettings?.applyCustomInstructions === false;

Skipped Sections

// From systemBuilder.ts:95-133
// === 2. IDENTITY MEMORIES ===
// Skip for incognito blank slate mode
if (!isBlankSlate) {
  const identityMemories = await ctx.runQuery(
    internal.memories.search.getIdentityMemories,
    { userId: args.userId, limit: 20 }
  );
  // ... format and inject
}

// From systemBuilder.ts:135-142
// === 3. CONTEXTUAL MEMORIES ===
// Skip for incognito blank slate mode
if (args.prefetchedMemories && !isBlankSlate) {
  systemMessages.push({
    role: "system",
    content: `## Contextual Memories\n\n${args.prefetchedMemories}`,
  });
}

// From systemBuilder.ts:160-186
// === 4.25. KNOWLEDGE BANK ===
// Skip for incognito blank slate mode
if (!isBlankSlate && args.hasFunctionCalling) {
  const hasKnowledge = await ctx.runQuery(
    internal.knowledgeBank.index.hasKnowledge,
    { userId: args.userId }
  );
  const kbPrompt = getKnowledgeBankSystemPrompt(hasKnowledge);
  if (kbPrompt) {
    systemMessages.push({ role: "system", content: kbPrompt });
  }
}

// From systemBuilder.ts:227-304
// === 6. USER CUSTOM INSTRUCTIONS ===
// Skip for incognito blank slate mode
if (customInstructions?.enabled && !isBlankSlate) {
  // ... build and inject user preferences
}

Effect: Blank slate mode provides completely fresh AI behavior without personalization or history context.

Inactivity Timeout

Optional auto-cleanup for incognito conversations.

Field Structure

incognitoSettings: {
  inactivityTimeoutMinutes?: number;  // Optional timeout in minutes
  lastActivityAt: number;             // Timestamp of last activity
}

Implementation: Set during creation, updated on message activity. Cleanup logic runs via scheduled job (not shown in provided files but referenced in schema).

Usage Patterns

Standard Incognito (Read Tools Enabled)

await ctx.runMutation(api.conversations.create, {
  model: "openai:gpt-5-mini",
  isIncognito: true,
  incognitoSettings: {
    enableReadTools: true,          // Can search files/notes/tasks
    applyCustomInstructions: true,  // Apply user preferences
  },
});

Tools: Web search, URL reader, code execution + file/note/task/history search. No writes.

Strict Incognito (Read Tools Disabled)

await ctx.runMutation(api.conversations.create, {
  model: "openai:gpt-5-mini",
  isIncognito: true,
  incognitoSettings: {
    enableReadTools: false,         // No data access
    applyCustomInstructions: true,  // Still apply preferences
  },
});

Tools: Only capability tools (web search, calculator, datetime, URL reader, code execution). No data access.

Blank Slate Mode

await ctx.runMutation(api.conversations.create, {
  model: "openai:gpt-5-mini",
  isIncognito: true,
  incognitoSettings: {
    enableReadTools: false,              // No data access
    applyCustomInstructions: false,      // Skip memories + custom instructions
    inactivityTimeoutMinutes: 60,        // Auto-delete after 1 hour of inactivity
  },
});

Tools: Only capability tools. System prompt: Skips identity memories, contextual memories, knowledge bank, and custom instructions. Fully anonymous.

Key Files

• packages/backend/convex/conversations.ts - Schema + creation mutation (lines 30-112)
• packages/backend/convex/generation/tools.ts - Tool filtering logic (lines 42-241)
• packages/backend/convex/lib/prompts/systemBuilder.ts - Blank slate prompt filtering (lines 59-304)

Anti-Patterns

Don't assume incognito = no read tools. Default is enableReadTools: true. Must explicitly set to false for strict privacy.

Don't confuse blank slate with incognito. Incognito only controls tool access. Blank slate (applyCustomInstructions: false) controls system prompt personalization.

Don't use incognito for temporary chats. Use inactivityTimeoutMinutes for auto-cleanup. Otherwise incognito conversations persist like normal ones.

Don't expose write tools in incognito UI. Backend enforces this but frontend must not offer task creation, memory saving, or canvas tools when isIncognito: true.