🧠 feat: User Memories for Conversational Context (#7760)

* 🧠 feat: User Memories for Conversational Context

chore: mcp typing, use `t`

WIP: first pass, Memories UI

- Added MemoryViewer component for displaying, editing, and deleting user memories.
- Integrated data provider hooks for fetching, updating, and deleting memories.
- Implemented pagination and loading states for better user experience.
- Created unit tests for MemoryViewer to ensure functionality and interaction with data provider.
- Updated translation files to include new UI strings related to memories.

chore: move mcp-related files to own directory

chore: rename librechat-mcp to librechat-api

WIP: first pass, memory processing and data schemas

chore: linting in fileSearch.js query description

chore: rename librechat-api to @librechat/api across the project

WIP: first pass, functional memory agent

feat: add MemoryEditDialog and MemoryViewer components for managing user memories

- Introduced MemoryEditDialog for editing memory entries with validation and toast notifications.
- Updated MemoryViewer to support editing and deleting memories, including pagination and loading states.
- Enhanced data provider to handle memory updates with optional original key for better management.
- Added new localization strings for memory-related UI elements.

feat: add memory permissions management

- Implemented memory permissions in the backend, allowing roles to have specific permissions for using, creating, updating, and reading memories.
- Added new API endpoints for updating memory permissions associated with roles.
- Created a new AdminSettings component for managing memory permissions in the frontend.
- Integrated memory permissions into the existing roles and permissions schemas.
- Updated the interface to include memory settings and permissions.
- Enhanced the MemoryViewer component to conditionally render admin settings based on user roles.
- Added localization support for memory permissions in the translation files.

feat: move AdminSettings component to a new position in MemoryViewer for better visibility

refactor: clean up commented code in MemoryViewer component

feat: enhance MemoryViewer with search functionality and improve MemoryEditDialog integration

- Added a search input to filter memories in the MemoryViewer component.
- Refactored MemoryEditDialog to accept children for better customization.
- Updated MemoryViewer to utilize the new EditMemoryButton and DeleteMemoryButton components for editing and deleting memories.
- Improved localization support by adding new strings for memory filtering and deletion confirmation.

refactor: optimize memory filtering in MemoryViewer using match-sorter

- Replaced manual filtering logic with match-sorter for improved search functionality.
- Enhanced performance and readability of the filteredMemories computation.

feat: enhance MemoryEditDialog with triggerRef and improve updateMemory mutation handling

feat: implement access control for MemoryEditDialog and MemoryViewer components

refactor: remove commented out code and create runMemory method

refactor: rename role based files

feat: implement access control for memory usage in AgentClient

refactor: simplify checkVisionRequest method in AgentClient by removing commented-out code

refactor: make `agents` dir in api package

refactor: migrate Azure utilities to TypeScript and consolidate imports

refactor: move sanitizeFilename function to a new file and update imports, add related tests

refactor: update LLM configuration types and consolidate Azure options in the API package

chore: linting

chore: import order

refactor: replace getLLMConfig with getOpenAIConfig and remove unused LLM configuration file

chore: update winston-daily-rotate-file to version 5.0.0 and add object-hash dependency in package-lock.json

refactor: move primeResources and optionalChainWithEmptyCheck functions to resources.ts and update imports

refactor: move createRun function to a new run.ts file and update related imports

fix: ensure safeAttachments is correctly typed as an array of TFile

chore: add node-fetch dependency and refactor fetch-related functions into packages/api/utils, removing the old generators file

refactor: enhance TEndpointOption type by using Pick to streamline endpoint fields and add new properties for model parameters and client options

feat: implement initializeOpenAIOptions function and update OpenAI types for enhanced configuration handling

fix: update types due to new TEndpointOption typing

fix: ensure safe access to group parameters in initializeOpenAIOptions function

fix: remove redundant API key validation comment in initializeOpenAIOptions function

refactor: rename initializeOpenAIOptions to initializeOpenAI for consistency and update related documentation

refactor: decouple req.body fields and tool loading from initializeAgentOptions

chore: linting

refactor: adjust column widths in MemoryViewer for improved layout

refactor: simplify agent initialization by creating loadAgent function and removing unused code

feat: add memory configuration loading and validation functions

WIP: first pass, memory processing with config

feat: implement memory callback and artifact handling

feat: implement memory artifacts display and processing updates

feat: add memory configuration options and schema validation for validKeys

fix: update MemoryEditDialog and MemoryViewer to handle memory state and display improvements

refactor: remove padding from BookmarkTable and MemoryViewer headers for consistent styling

WIP: initial tokenLimit config and move Tokenizer to @librechat/api

refactor: update mongoMeili plugin methods to use callback for better error handling

feat: enhance memory management with token tracking and usage metrics

- Added token counting for memory entries to enforce limits and provide usage statistics.
- Updated memory retrieval and update routes to include total token usage and limit.
- Enhanced MemoryEditDialog and MemoryViewer components to display memory usage and token information.
- Refactored memory processing functions to handle token limits and provide feedback on memory capacity.

feat: implement memory artifact handling in attachment handler

- Enhanced useAttachmentHandler to process memory artifacts when receiving updates.
- Introduced handleMemoryArtifact utility to manage memory updates and deletions.
- Updated query client to reflect changes in memory state based on incoming data.

refactor: restructure web search key extraction logic

- Moved the logic for extracting API keys from the webSearchAuth configuration into a dedicated function, getWebSearchKeys.
- Updated webSearchKeys to utilize the new function for improved clarity and maintainability.
- Prevents build time errors

feat: add personalization settings and memory preferences management

- Introduced a new Personalization tab in settings to manage user memory preferences.
- Implemented API endpoints and client-side logic for updating memory preferences.
- Enhanced user interface components to reflect personalization options and memory usage.
- Updated permissions to allow users to opt out of memory features.
- Added localization support for new settings and messages related to personalization.

style: personalization switch class

feat: add PersonalizationIcon and align Side Panel UI

feat: implement memory creation functionality

- Added a new API endpoint for creating memory entries, including validation for key and value.
- Introduced MemoryCreateDialog component for user interface to facilitate memory creation.
- Integrated token limit checks to prevent exceeding user memory capacity.
- Updated MemoryViewer to include a button for opening the memory creation dialog.
- Enhanced localization support for new messages related to memory creation.

feat: enhance message processing with configurable window size

- Updated AgentClient to use a configurable message window size for processing messages.
- Introduced messageWindowSize option in memory configuration schema with a default value of 5.
- Improved logic for selecting messages to process based on the configured window size.

chore: update librechat-data-provider version to 0.7.87 in package.json and package-lock.json

chore: remove OpenAPIPlugin and its associated tests

chore: remove MIGRATION_README.md as migration tasks are completed

ci: fix backend tests

chore: remove unused translation keys from localization file

chore: remove problematic test file and unused var in AgentClient

chore: remove unused import and import directly for JSDoc

* feat: add api package build stage in Dockerfile for improved modularity

* docs: reorder build steps in contributing guide for clarity

packages/api/src/flow/manager.ts

@@ -0,0 +1,257 @@
+import { Keyv } from 'keyv';
+import type { StoredDataNoRaw } from 'keyv';
+import type { Logger } from 'winston';
+import type { FlowState, FlowMetadata, FlowManagerOptions } from './types';
+
+export class FlowStateManager<T = unknown> {
+  private keyv: Keyv;
+  private ttl: number;
+  private logger: Logger;
+  private intervals: Set<NodeJS.Timeout>;
+
+  private static getDefaultLogger(): Logger {
+    return {
+      error: console.error,
+      warn: console.warn,
+      info: console.info,
+      debug: console.debug,
+    } as Logger;
+  }
+
+  constructor(store: Keyv, options?: FlowManagerOptions) {
+    if (!options) {
+      options = { ttl: 60000 * 3 };
+    }
+    const { ci = false, ttl, logger } = options;
+
+    if (!ci && !(store instanceof Keyv)) {
+      throw new Error('Invalid store provided to FlowStateManager');
+    }
+
+    this.ttl = ttl;
+    this.keyv = store;
+    this.logger = logger || FlowStateManager.getDefaultLogger();
+    this.intervals = new Set();
+    this.setupCleanupHandlers();
+  }
+
+  private setupCleanupHandlers() {
+    const cleanup = () => {
+      this.logger.info('Cleaning up FlowStateManager intervals...');
+      this.intervals.forEach((interval) => clearInterval(interval));
+      this.intervals.clear();
+      process.exit(0);
+    };
+
+    process.on('SIGTERM', cleanup);
+    process.on('SIGINT', cleanup);
+    process.on('SIGQUIT', cleanup);
+    process.on('SIGHUP', cleanup);
+  }
+
+  private getFlowKey(flowId: string, type: string): string {
+    return `${type}:${flowId}`;
+  }
+
+  /**
+   * Creates a new flow and waits for its completion
+   */
+  async createFlow(
+    flowId: string,
+    type: string,
+    metadata: FlowMetadata = {},
+    signal?: AbortSignal,
+  ): Promise<T> {
+    const flowKey = this.getFlowKey(flowId, type);
+
+    let existingState = (await this.keyv.get(flowKey)) as FlowState<T> | undefined;
+    if (existingState) {
+      this.logger.debug(`[${flowKey}] Flow already exists`);
+      return this.monitorFlow(flowKey, type, signal);
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 250));
+
+    existingState = (await this.keyv.get(flowKey)) as FlowState<T> | undefined;
+    if (existingState) {
+      this.logger.debug(`[${flowKey}] Flow exists on 2nd check`);
+      return this.monitorFlow(flowKey, type, signal);
+    }
+
+    const initialState: FlowState = {
+      type,
+      status: 'PENDING',
+      metadata,
+      createdAt: Date.now(),
+    };
+
+    this.logger.debug('Creating initial flow state:', flowKey);
+    await this.keyv.set(flowKey, initialState, this.ttl);
+    return this.monitorFlow(flowKey, type, signal);
+  }
+
+  private monitorFlow(flowKey: string, type: string, signal?: AbortSignal): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const checkInterval = 2000;
+      let elapsedTime = 0;
+
+      const intervalId = setInterval(async () => {
+        try {
+          const flowState = (await this.keyv.get(flowKey)) as FlowState<T> | undefined;
+
+          if (!flowState) {
+            clearInterval(intervalId);
+            this.intervals.delete(intervalId);
+            this.logger.error(`[${flowKey}] Flow state not found`);
+            reject(new Error(`${type} Flow state not found`));
+            return;
+          }
+
+          if (signal?.aborted) {
+            clearInterval(intervalId);
+            this.intervals.delete(intervalId);
+            this.logger.warn(`[${flowKey}] Flow aborted`);
+            const message = `${type} flow aborted`;
+            await this.keyv.delete(flowKey);
+            reject(new Error(message));
+            return;
+          }
+
+          if (flowState.status !== 'PENDING') {
+            clearInterval(intervalId);
+            this.intervals.delete(intervalId);
+            this.logger.debug(`[${flowKey}] Flow completed`);
+
+            if (flowState.status === 'COMPLETED' && flowState.result !== undefined) {
+              resolve(flowState.result);
+            } else if (flowState.status === 'FAILED') {
+              await this.keyv.delete(flowKey);
+              reject(new Error(flowState.error ?? `${type} flow failed`));
+            }
+            return;
+          }
+
+          elapsedTime += checkInterval;
+          if (elapsedTime >= this.ttl) {
+            clearInterval(intervalId);
+            this.intervals.delete(intervalId);
+            this.logger.error(
+              `[${flowKey}] Flow timed out | Elapsed time: ${elapsedTime} | TTL: ${this.ttl}`,
+            );
+            await this.keyv.delete(flowKey);
+            reject(new Error(`${type} flow timed out`));
+          }
+          this.logger.debug(
+            `[${flowKey}] Flow state elapsed time: ${elapsedTime}, checking again...`,
+          );
+        } catch (error) {
+          this.logger.error(`[${flowKey}] Error checking flow state:`, error);
+          clearInterval(intervalId);
+          this.intervals.delete(intervalId);
+          reject(error);
+        }
+      }, checkInterval);
+
+      this.intervals.add(intervalId);
+    });
+  }
+
+  /**
+   * Completes a flow successfully
+   */
+  async completeFlow(flowId: string, type: string, result: T): Promise<boolean> {
+    const flowKey = this.getFlowKey(flowId, type);
+    const flowState = (await this.keyv.get(flowKey)) as FlowState<T> | undefined;
+
+    if (!flowState) {
+      return false;
+    }
+
+    const updatedState: FlowState<T> = {
+      ...flowState,
+      status: 'COMPLETED',
+      result,
+      completedAt: Date.now(),
+    };
+
+    await this.keyv.set(flowKey, updatedState, this.ttl);
+    return true;
+  }
+
+  /**
+   * Marks a flow as failed
+   */
+  async failFlow(flowId: string, type: string, error: Error | string): Promise<boolean> {
+    const flowKey = this.getFlowKey(flowId, type);
+    const flowState = (await this.keyv.get(flowKey)) as FlowState | undefined;
+
+    if (!flowState) {
+      return false;
+    }
+
+    const updatedState: FlowState = {
+      ...flowState,
+      status: 'FAILED',
+      error: error instanceof Error ? error.message : error,
+      failedAt: Date.now(),
+    };
+
+    await this.keyv.set(flowKey, updatedState, this.ttl);
+    return true;
+  }
+
+  /**
+   * Gets current flow state
+   */
+  async getFlowState(flowId: string, type: string): Promise<StoredDataNoRaw<FlowState<T>> | null> {
+    const flowKey = this.getFlowKey(flowId, type);
+    return this.keyv.get(flowKey);
+  }
+
+  /**
+   * Creates a new flow and waits for its completion, only executing the handler if no existing flow is found
+   * @param flowId - The ID of the flow
+   * @param type - The type of flow
+   * @param handler - Async function to execute if no existing flow is found
+   * @param signal - Optional AbortSignal to cancel the flow
+   */
+  async createFlowWithHandler(
+    flowId: string,
+    type: string,
+    handler: () => Promise<T>,
+    signal?: AbortSignal,
+  ): Promise<T> {
+    const flowKey = this.getFlowKey(flowId, type);
+    let existingState = (await this.keyv.get(flowKey)) as FlowState<T> | undefined;
+    if (existingState) {
+      this.logger.debug(`[${flowKey}] Flow already exists`);
+      return this.monitorFlow(flowKey, type, signal);
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 250));
+
+    existingState = (await this.keyv.get(flowKey)) as FlowState<T> | undefined;
+    if (existingState) {
+      this.logger.debug(`[${flowKey}] Flow exists on 2nd check`);
+      return this.monitorFlow(flowKey, type, signal);
+    }
+
+    const initialState: FlowState = {
+      type,
+      status: 'PENDING',
+      metadata: {},
+      createdAt: Date.now(),
+    };
+    this.logger.debug(`[${flowKey}] Creating initial flow state`);
+    await this.keyv.set(flowKey, initialState, this.ttl);
+
+    try {
+      const result = await handler();
+      await this.completeFlow(flowId, type, result);
+      return result;
+    } catch (error) {
+      await this.failFlow(flowId, type, error instanceof Error ? error : new Error(String(error)));
+      throw error;
+    }
+  }
+}