Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🫗 perf: Release Message Histories of Conversations the User Has Left (#16747)
Danny Avila3e4b01834f97
diff --git a/client/src/data-provider/Messages/__tests__/retention.spec.ts b/client/src/data-provider/Messages/__tests__/retention.spec.tsnew file mode 100644index 0000000000..4f6e1f800c--- /dev/null+++ b/client/src/data-provider/Messages/__tests__/retention.spec.ts@@ -0,0 +1,263 @@+import { QueryClient, QueryObserver } from '@tanstack/react-query';+import { Constants, QueryKeys, DEFAULT_HISTORY_CACHE_TTL_MS } from 'librechat-data-provider';+import type { TMessage } from 'librechat-data-provider';+import { retainMessages, PIN_RECHECK_MS, RELEASE_SETTLE_MS } from '../retention';++const TTL = DEFAULT_HISTORY_CACHE_TTL_MS;+/** React Query's own default `cacheTime`, which a retained history must outlive. */+const NATIVE_CACHE_TIME = 5 * 60_000;++const history = (conversationId: string): TMessage[] => [+ { messageId: `${conversationId}-1`, conversationId, text: conversationId } as TMessage,+];++const seed = (queryClient: QueryClient, conversationId: string) =>+ queryClient.setQueryData([QueryKeys.messages, conversationId], history(conversationId));++const isCached = (queryClient: QueryClient, conversationId: string) =>+ queryClient.getQueryCache().find([QueryKeys.messages, conversationId]) != null;++/** Mounts a reader the way an on-screen view does; the returned function unmounts it. */+const observe = (queryClient: QueryClient, conversationId: string): (() => void) => {+ const observer = new QueryObserver(queryClient, {+ queryKey: [QueryKeys.messages, conversationId],+ enabled: false,+ });+ return observer.subscribe(() => undefined);+};++/** Opens a conversation and leaves it, which is when its retention clock starts. */+const visit = (queryClient: QueryClient, conversationId: string) => {+ seed(queryClient, conversationId);+ observe(queryClient, conversationId)();+};++describe('retainMessages', () => {+ let queryClient: QueryClient;+ let pinned: Set<string>;+ let stop: () => void;++ beforeEach(() => {+ jest.useFakeTimers();+ queryClient = new QueryClient();+ pinned = new Set();+ stop = retainMessages(queryClient, { isPinned: (id) => pinned.has(id) });+ });++ afterEach(() => {+ stop();+ queryClient.clear();+ jest.useRealTimers();+ });++ it('releases the last conversation left once its history outlives the TTL', () => {+ visit(queryClient, 'a');++ jest.advanceTimersByTime(TTL - 1);+ expect(isCached(queryClient, 'a')).toBe(true);++ jest.advanceTimersByTime(1);+ expect(isCached(queryClient, 'a')).toBe(false);+ });++ it('keeps only the most recently left conversation across a burst of switches', () => {+ visit(queryClient, 'a');+ jest.advanceTimersByTime(10);+ visit(queryClient, 'b');+ jest.advanceTimersByTime(10);+ visit(queryClient, 'c');++ jest.advanceTimersByTime(RELEASE_SETTLE_MS);++ expect(isCached(queryClient, 'a')).toBe(false);+ expect(isCached(queryClient, 'b')).toBe(false);+ expect(isCached(queryClient, 'c')).toBe(true);+ });++ it('keeps observed, pinned and fetching histories, and placeholder or list queries', () => {+ seed(queryClient, 'on-screen');+ const unmount = observe(queryClient, 'on-screen');+ visit(queryClient, 'running');+ pinned.add('running');+ visit(queryClient, 'loading');+ queryClient.getQueryCache().find([QueryKeys.messages, 'loading'])?.setState({+ fetchStatus: 'fetching',+ });+ queryClient.setQueryData([QueryKeys.messages, Constants.NEW_CONVO], history('new'));+ queryClient.setQueryData([QueryKeys.messages, { conversationId: 'listed' }], {+ pages: [],+ pageParams: [],+ });+ visit(queryClient, 'idle');++ jest.advanceTimersByTime(TTL * 2);++ expect(isCached(queryClient, 'idle')).toBe(false);+ expect(isCached(queryClient, 'on-screen')).toBe(true);+ expect(isCached(queryClient, 'running')).toBe(true);+ expect(isCached(queryClient, 'loading')).toBe(true);+ expect(isCached(queryClient, Constants.NEW_CONVO)).toBe(true);+ expect(+ queryClient.getQueryData([QueryKeys.messages, { conversationId: 'listed' }]),+ ).toBeDefined();++ unmount();+ pinned.delete('running');+ jest.advanceTimersByTime(TTL);++ expect(isCached(queryClient, 'running')).toBe(false);+ expect(isCached(queryClient, 'on-screen')).toBe(false);+ });++ it('restarts the clock when a left conversation is opened again', () => {+ visit(queryClient, 'a');+ jest.advanceTimersByTime(TTL / 2);+ const unmount = observe(queryClient, 'a');++ jest.advanceTimersByTime(TTL);+ expect(isCached(queryClient, 'a')).toBe(true);++ unmount();+ jest.advanceTimersByTime(TTL - 1);+ expect(isCached(queryClient, 'a')).toBe(true);+ jest.advanceTimersByTime(1);+ expect(isCached(queryClient, 'a')).toBe(false);+ });++ it('waits for pending mutations, whose callbacks write into these caches', async () => {+ let settle: () => void = () => undefined;+ const gate = new Promise<void>((resolve) => {+ settle = resolve;+ });+ const mutation = queryClient.getMutationCache().build(queryClient, {+ mutationFn: () => gate,+ });+ const pending = mutation.execute();+ visit(queryClient, 'a');+ visit(queryClient, 'b');++ jest.advanceTimersByTime(TTL * 2);+ expect(isCached(queryClient, 'a')).toBe(true);+ expect(isCached(queryClient, 'b')).toBe(true);++ settle();+ await pending;+ jest.advanceTimersByTime(RELEASE_SETTLE_MS);++ expect(isCached(queryClient, 'a')).toBe(false);+ expect(isCached(queryClient, 'b')).toBe(false);+ });++ it('owns collection, so a pinned history outlives the native cacheTime', () => {+ stop();+ queryClient.clear();+ seed(queryClient, 'mounted-first');+ const unmount = observe(queryClient, 'mounted-first');+ visit(queryClient, 'left-first');+ stop = retainMessages(queryClient, { isPinned: (id) => pinned.has(id) });+ pinned.add('mounted-first').add('left-first').add('running');+ unmount();+ visit(queryClient, 'running');++ jest.advanceTimersByTime(NATIVE_CACHE_TIME * 2);++ expect(isCached(queryClient, 'mounted-first')).toBe(true);+ expect(isCached(queryClient, 'left-first')).toBe(true);+ expect(isCached(queryClient, 'running')).toBe(true);+ });++ it('releases a history seeded without ever being observed', () => {+ seed(queryClient, 'forked');++ jest.advanceTimersByTime(TTL);+ expect(isCached(queryClient, 'forked')).toBe(true);+ jest.advanceTimersByTime(RELEASE_SETTLE_MS);+ expect(isCached(queryClient, 'forked')).toBe(false);+ });++ it('applies the configured grace and recent count', () => {+ stop();+ stop = retainMessages(queryClient, { isPinned: () => false, recent: 2, ttlMs: 10_000 });+ visit(queryClient, 'a');+ jest.advanceTimersByTime(10);+ visit(queryClient, 'b');+ jest.advanceTimersByTime(10);+ visit(queryClient, 'c');++ jest.advanceTimersByTime(RELEASE_SETTLE_MS);+ expect(isCached(queryClient, 'a')).toBe(false);+ expect(isCached(queryClient, 'b')).toBe(true);+ expect(isCached(queryClient, 'c')).toBe(true);++ jest.advanceTimersByTime(10_000);+ expect(isCached(queryClient, 'b')).toBe(false);+ expect(isCached(queryClient, 'c')).toBe(false);+ });++ it('rechecks a pinned history soon after its pin clears, whatever the TTL', () => {+ stop();+ stop = retainMessages(queryClient, {+ isPinned: (id) => pinned.has(id),+ recent: 0,+ ttlMs: 60 * 60_000,+ });+ pinned.add('running');+ visit(queryClient, 'running');+ jest.advanceTimersByTime(RELEASE_SETTLE_MS);+ expect(isCached(queryClient, 'running')).toBe(true);++ pinned.delete('running');+ jest.advanceTimersByTime(PIN_RECHECK_MS);++ expect(isCached(queryClient, 'running')).toBe(false);+ });++ it('keeps exempt histories without polling them', () => {+ stop();+ stop = retainMessages(queryClient, {+ isPinned: () => false,+ isExempt: (id) => id === 'assistant',+ recent: 0,+ });+ visit(queryClient, 'assistant');++ jest.advanceTimersByTime(RELEASE_SETTLE_MS);++ expect(isCached(queryClient, 'assistant')).toBe(true);+ expect(jest.getTimerCount()).toBe(0);+ });++ it('leaves a fetching history alone at startup instead of re-arming it', async () => {+ stop();+ queryClient.clear();+ let signal: AbortSignal | undefined;+ const pending = queryClient.fetchQuery([QueryKeys.messages, 'sharing'], (context) => {+ signal = context.signal;+ return new Promise<TMessage[]>(() => undefined);+ });+ stop = retainMessages(queryClient, { isPinned: () => false });++ expect(signal?.aborted).toBe(false);+ expect(queryClient.getQueryState([QueryKeys.messages, 'sharing'])?.fetchStatus).toBe(+ 'fetching',+ );+ void pending.catch(() => undefined);+ });++ it('restores the messages query defaults on cleanup', () => {+ expect(queryClient.getQueryDefaults([QueryKeys.messages])?.cacheTime).toBe(Infinity);+ stop();+ expect(queryClient.getQueryDefaults([QueryKeys.messages])?.cacheTime).toBeUndefined();+ });++ it('releases nothing after cleanup', () => {+ visit(queryClient, 'a');+ visit(queryClient, 'b');+ stop();++ jest.advanceTimersByTime(TTL * 2);++ expect(isCached(queryClient, 'a')).toBe(true);+ expect(isCached(queryClient, 'b')).toBe(true);+ });+});diff --git a/client/src/data-provider/Messages/retention.ts b/client/src/data-provider/Messages/retention.tsnew file mode 100644index 0000000000..4ec0129325--- /dev/null+++ b/client/src/data-provider/Messages/retention.ts@@ -0,0 +1,204 @@+import { QueryObserver } from '@tanstack/react-query';+import {+ Constants,+ QueryKeys,+ DEFAULT_HISTORY_CACHE_RECENT,+ DEFAULT_HISTORY_CACHE_TTL_MS,+} from 'librechat-data-provider';+import type { Query, QueryClient } from '@tanstack/react-query';++/** Gives a route change time to mount the next view before anything unobserved is judged. */+export const RELEASE_SETTLE_MS = 1_000;+/** How soon a history kept only because it is pinned or fetching is judged again. */+export const PIN_RECHECK_MS = 5_000;++export type MessagesRetentionOptions = {+ /** Conversations whose history must stay regardless of age, such as the routed conversation+ * or one whose job is still running. Read at release time, so it sees live state. */+ isPinned: (conversationId: string) => boolean;+ /** Conversations whose history is never released, for a reason that does not lapse on its+ * own (such as an Assistants thread id that deletion reads from the cache). Unlike pins,+ * these are not polled. */+ isExempt?: (conversationId: string) => boolean;+ /** How many of the most recently left conversations keep their history for `ttlMs`. */+ recent?: number;+ /** How long a left conversation's history stays cached. */+ ttlMs?: number;+};++type IdleHistory = {+ query: Query;+ conversationId: string;+ leftAt: number;+};++const isPlaceholderId = (conversationId: string): boolean =>+ conversationId === Constants.NEW_CONVO ||+ conversationId === Constants.PENDING_CONVO ||+ conversationId === Constants.SEARCH;++/** Only per-conversation histories qualify; list and search queries share the root with+ * object keys and keep their own cache times. */+function historyConversationId(query: Query): string | null {+ const [root, conversationId] = query.queryKey;+ if (+ query.queryKey.length !== 2 ||+ root !== QueryKeys.messages ||+ typeof conversationId !== 'string' ||+ isPlaceholderId(conversationId)+ ) {+ return null;+ }+ return conversationId;+}++/** React Query only reschedules a query's collection when its observers change or a fetch+ * settles, so a history already counting down keeps its old timer. A momentary observer+ * re-arms it under the new `cacheTime`, which for `Infinity` cancels it. A fetching history is+ * left alone: removing its last observer would cancel the request, and settling re-arms it. */+function rearmCollection(queryClient: QueryClient, query: Query): void {+ const observer = new QueryObserver(queryClient, { queryKey: query.queryKey, enabled: false });+ observer.subscribe(() => undefined)();+}++const isUnobservedHistory = (query: Query): boolean =>+ historyConversationId(query) != null && query.getObserversCount() === 0;++const newestFirst = (a: IdleHistory, b: IdleHistory): number => b.leftAt - a.leftAt;++/**+ * Releases the message histories of conversations the user has left, so long transcripts do+ * not pile up in memory across conversation switches. React Query's own `cacheTime` cannot+ * express this: it is fixed per query (only ever raised), counts down even while a run is still+ * writing into the cache, and does not bound how many histories a burst of switches retains.+ * While active this module therefore owns their lifetime: per-conversation histories get an+ * infinite `cacheTime`, so React Query never collects one this policy still retains.+ *+ * A history is released once it has no observers, is not fetching, is neither pinned nor exempt,+ * and is either older than `ttlMs` since it was left or beyond the `recent` most recently left+ * conversations.+ * Releases wait while any mutation is pending, since mutation callbacks write into these caches.+ * Returning to a released conversation mounts a fresh query, which fetches the history again.+ *+ * @returns Cleanup that stops tracking and restores the messages query defaults; it releases+ * nothing (sign-out removes every query anyway).+ */+export function retainMessages(+ queryClient: QueryClient,+ {+ isPinned,+ isExempt = () => false,+ recent = DEFAULT_HISTORY_CACHE_RECENT,+ ttlMs = DEFAULT_HISTORY_CACHE_TTL_MS,+ }: MessagesRetentionOptions,+): () => void {+ const cache = queryClient.getQueryCache();+ const leftAt = new Map<string, number>();+ const previousDefaults = queryClient.getQueryDefaults([QueryKeys.messages]);+ queryClient.setQueryDefaults([QueryKeys.messages], { ...previousDefaults, cacheTime: Infinity });+ cache.findAll([QueryKeys.messages]).forEach((query) => {+ if (historyConversationId(query) == null) {+ return;+ }+ query.cacheTime = Infinity;+ if (query.getObserversCount() === 0 && query.state.fetchStatus === 'idle') {+ rearmCollection(queryClient, query);+ }+ });+ let timer: ReturnType<typeof setTimeout> | undefined;+ let dueAt = Infinity;++ const schedule = (delay: number) => {+ const at = Date.now() + delay;+ if (timer != null && dueAt <= at) {+ return;+ }+ clearTimeout(timer);+ dueAt = at;+ timer = setTimeout(release, delay);+ };++ const collectIdle = (now: number): IdleHistory[] =>+ cache.findAll([QueryKeys.messages]).reduce<IdleHistory[]>((idle, query) => {+ const conversationId = historyConversationId(query);+ if (conversationId == null) {+ return idle;+ }+ if (query.getObserversCount() > 0) {+ leftAt.delete(conversationId);+ return idle;+ }+ const since = leftAt.get(conversationId) ?? now;+ leftAt.set(conversationId, since);+ idle.push({ query, conversationId, leftAt: since });+ return idle;+ }, []);++ function release() {+ timer = undefined;+ dueAt = Infinity;+ if (queryClient.isMutating() > 0) {+ schedule(RELEASE_SETTLE_MS);+ return;+ }+ const now = Date.now();+ const candidates = collectIdle(now).filter((entry) => {+ if (isExempt(entry.conversationId)) {+ return false;+ }+ if (entry.query.state.fetchStatus === 'idle' && !isPinned(entry.conversationId)) {+ return true;+ }+ schedule(PIN_RECHECK_MS);+ return false;+ });+ candidates.sort(newestFirst).forEach((entry, index) => {+ const expiresAt = entry.leftAt + ttlMs;+ if (index < recent && expiresAt > now) {+ schedule(expiresAt - now);+ return;+ }+ leftAt.delete(entry.conversationId);+ cache.remove(entry.query);+ });+ }++ const unsubscribe = cache.subscribe((event) => {+ if (+ event.type !== 'added' &&+ event.type !== 'observerAdded' &&+ event.type !== 'observerRemoved' &&+ event.type !== 'removed'+ ) {+ return;+ }+ const conversationId = historyConversationId(event.query);+ if (conversationId == null) {+ return;+ }+ if (event.type === 'added') {+ schedule(RELEASE_SETTLE_MS);+ return;+ }+ if (event.type !== 'observerRemoved') {+ leftAt.delete(conversationId);+ return;+ }+ if (event.query.getObserversCount() > 0) {+ return;+ }+ leftAt.set(conversationId, Date.now());+ schedule(RELEASE_SETTLE_MS);+ });++ if (cache.findAll([QueryKeys.messages]).some(isUnobservedHistory)) {+ schedule(RELEASE_SETTLE_MS);+ }++ return () => {+ unsubscribe();+ clearTimeout(timer);+ timer = undefined;+ queryClient.setQueryDefaults([QueryKeys.messages], previousDefaults ?? {});+ };+}diff --git a/client/src/hooks/Messages/__tests__/useMessagesRetention.spec.tsx b/client/src/hooks/Messages/__tests__/useMessagesRetention.spec.tsxnew file mode 100644index 0000000000..ccbe0df14e--- /dev/null+++ b/client/src/hooks/Messages/__tests__/useMessagesRetention.spec.tsx@@ -0,0 +1,167 @@+import React, { useEffect } from 'react';+import { RecoilRoot } from 'recoil';+import { QueryKeys, dataService } from 'librechat-data-provider';+import { act, render, screen, waitFor } from '@testing-library/react';+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';+import {+ Route,+ Routes,+ useParams,+ useNavigate,+ MemoryRouter,+ useSearchParams,+} from 'react-router-dom';+import type { TMessage, TStartupConfig } from 'librechat-data-provider';+import type { NavigateFunction } from 'react-router-dom';+import { useGetMessagesByConvoId } from '~/data-provider/Messages/queries';+import { RELEASE_SETTLE_MS } from '~/data-provider/Messages/retention';+import useMessagesRetention from '../useMessagesRetention';++jest.mock('librechat-data-provider', () => {+ const actual = jest.requireActual('librechat-data-provider');+ return {+ ...actual,+ dataService: {+ ...actual.dataService,+ getMessagesByConvoId: jest.fn(),+ getStartupConfig: jest.fn(),+ },+ };+});++const getMessagesByConvoId = jest.mocked(dataService.getMessagesByConvoId);+const getStartupConfig = jest.mocked(dataService.getStartupConfig);++/** A deployment-configured grace, distinct from the default, to prove the config is applied. */+const TTL = 20_000;++const history = (conversationId: string): TMessage[] => [+ {+ ...(conversationId === 'assistant' && { thread_id: 'thread_abc' }),+ messageId: `${conversationId}-1`,+ conversationId,+ parentMessageId: '00000000-0000-0000-0000-000000000000',+ text: `transcript of ${conversationId}`,+ sender: 'User',+ isCreatedByUser: true,+ createdAt: '2026-10-01T12:00:00.000Z',+ updatedAt: '2026-10-01T12:00:00.000Z',+ } as TMessage,+];++function Transcript() {+ const { conversationId = '' } = useParams();+ const { data } = useGetMessagesByConvoId(conversationId);+ return <p>{data?.[0]?.text ?? 'loading'}</p>;+}++/** Stands in for the gap between a route change and the next view subscribing. */+function Chat() {+ const [params] = useSearchParams();+ return params.has('mount') ? null : <Transcript />;+}++function Shell({ onNavigate }: { onNavigate: (navigate: NavigateFunction) => void }) {+ const navigate = useNavigate();+ useMessagesRetention();+ useEffect(() => {+ onNavigate(navigate);+ }, [navigate, onNavigate]);+ return (+ <Routes>+ <Route path="/c/:conversationId" element={<Chat />} />+ </Routes>+ );+}++const isCached = (queryClient: QueryClient, conversationId: string) =>+ queryClient.getQueryData([QueryKeys.messages, conversationId]) != null;++const fetchesOf = (conversationId: string) =>+ getMessagesByConvoId.mock.calls.filter(([id]) => id === conversationId).length;++describe('useMessagesRetention', () => {+ let queryClient: QueryClient;+ let navigate: NavigateFunction;++ const open = async (conversationId: string) => {+ act(() => {+ navigate(`/c/${conversationId}`);+ });+ expect(await screen.findByText(`transcript of ${conversationId}`)).toBeInTheDocument();+ };++ const elapse = (ms: number) =>+ act(() => {+ jest.advanceTimersByTime(ms);+ });++ beforeEach(() => {+ jest.useFakeTimers();+ getMessagesByConvoId.mockImplementation(async (id: string) => history(id));+ getStartupConfig.mockResolvedValue({+ interface: { historyCacheTtlMs: TTL, historyCacheRecent: 1 },+ } as TStartupConfig);+ queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });+ render(+ <QueryClientProvider client={queryClient}>+ <RecoilRoot>+ <MemoryRouter initialEntries={['/c/idle']}>+ <Shell+ onNavigate={(next) => {+ navigate = next;+ }}+ />+ </MemoryRouter>+ </RecoilRoot>+ </QueryClientProvider>,+ );+ });++ afterEach(() => {+ queryClient.clear();+ jest.useRealTimers();+ jest.clearAllMocks();+ });++ it('releases a left conversation after the configured grace, keeps running and Assistants ones, and refetches on return', async () => {+ expect(await screen.findByText('transcript of idle')).toBeInTheDocument();+ await waitFor(() => expect(getStartupConfig).toHaveBeenCalled());+ await open('running');+ queryClient.setQueryData([QueryKeys.activeJobs], { activeJobIds: ['running'] });+ await open('assistant');+ await open('current');++ elapse(RELEASE_SETTLE_MS);+ expect(isCached(queryClient, 'idle')).toBe(true);++ elapse(TTL * 2);+ expect(isCached(queryClient, 'idle')).toBe(false);+ expect(isCached(queryClient, 'running')).toBe(true);+ expect(isCached(queryClient, 'assistant')).toBe(true);+ expect(isCached(queryClient, 'current')).toBe(true);++ queryClient.setQueryData([QueryKeys.activeJobs], { activeJobIds: [] });+ elapse(TTL);+ expect(isCached(queryClient, 'running')).toBe(false);++ expect(fetchesOf('idle')).toBe(1);+ await open('idle');+ expect(fetchesOf('idle')).toBe(2);+ await waitFor(() => expect(isCached(queryClient, 'idle')).toBe(true));+ });++ it('keeps the routed conversation while its view has not subscribed yet', async () => {+ expect(await screen.findByText('transcript of idle')).toBeInTheDocument();+ await open('other');+ act(() => {+ navigate('/c/idle?mount=later');+ });+ expect(screen.queryByText(/transcript of/)).not.toBeInTheDocument();++ elapse(TTL * 2);++ expect(isCached(queryClient, 'other')).toBe(false);+ expect(isCached(queryClient, 'idle')).toBe(true);+ });+});diff --git a/client/src/hooks/Messages/index.ts b/client/src/hooks/Messages/index.tsindex 6015ed83f2..fa328cdffd 100644--- a/client/src/hooks/Messages/index.ts+++ b/client/src/hooks/Messages/index.ts@@ -21,6 +21,7 @@ export {} from './useProgressiveRowMount';export type { RowMountWindow } from './useProgressiveRowMount';export { default as useMessageActions } from './useMessageActions';+export { default as useMessagesRetention } from './useMessagesRetention';export { useLatestMessage, useLatestMessageId } from './useLatestMessage';export { default as useMemoizedChatContext } from './useMemoizedChatContext';export { default as useMessageProcess } from './useMessageProcess';diff --git a/client/src/hooks/Messages/useMessagesRetention.ts b/client/src/hooks/Messages/useMessagesRetention.tsnew file mode 100644index 0000000000..d60b89fd6b--- /dev/null+++ b/client/src/hooks/Messages/useMessagesRetention.ts@@ -0,0 +1,51 @@+import { useEffect, useRef } from 'react';+import { useMatch } from 'react-router-dom';+import { QueryKeys } from 'librechat-data-provider';+import { useQueryClient } from '@tanstack/react-query';+import type { QueryClient } from '@tanstack/react-query';+import type { TMessage } from 'librechat-data-provider';+import type { ActiveJobsResponse } from '~/data-provider';+import { retainMessages } from '~/data-provider/Messages/retention';+import { useGetStartupConfig } from '~/data-provider';++/** Running jobs include ones paused for an approval decision, while that decision is live. */+const hasActiveJob = (queryClient: QueryClient, conversationId: string): boolean =>+ queryClient+ .getQueryData<ActiveJobsResponse>([QueryKeys.activeJobs])+ ?.activeJobIds.includes(conversationId) === true;++/** Deleting an Assistants conversation reads its OpenAI thread id from the cached history, so+ * those (small) histories stay until the conversation is deleted or the session ends. */+const carriesAssistantThread = (queryClient: QueryClient, conversationId: string): boolean => {+ const messages = queryClient.getQueryData<TMessage[]>([QueryKeys.messages, conversationId]);+ return (messages?.[messages.length - 1]?.thread_id ?? '') !== '';+};++/**+ * Releases left conversations' message histories from the query cache (see `retainMessages`),+ * keeping the routed conversation, any conversation with a running job, and Assistants+ * conversations. The grace period and how many conversations keep it come from+ * `interface.historyCacheTtlMs` and `interface.historyCacheRecent`.+ */+export default function useMessagesRetention(): void {+ const queryClient = useQueryClient();+ const { data: startupConfig } = useGetStartupConfig();+ const ttlMs = startupConfig?.interface?.historyCacheTtlMs;+ const recent = startupConfig?.interface?.historyCacheRecent;+ const routeConversationId = useMatch('/c/:conversationId')?.params.conversationId;+ const routeConversationIdRef = useRef(routeConversationId);+ routeConversationIdRef.current = routeConversationId;++ useEffect(+ () =>+ retainMessages(queryClient, {+ ttlMs,+ recent,+ isPinned: (conversationId) =>+ conversationId === routeConversationIdRef.current ||+ hasActiveJob(queryClient, conversationId),+ isExempt: (conversationId) => carriesAssistantThread(queryClient, conversationId),+ }),+ [queryClient, ttlMs, recent],+ );+}diff --git a/client/src/routes/Root.tsx b/client/src/routes/Root.tsxindex 338339fee7..dae5aeec17 100644--- a/client/src/routes/Root.tsx+++ b/client/src/routes/Root.tsx@@ -11,6 +11,7 @@ import {useReplyWatcher,useSearchEnabled,useCatalogWarmup,+ useMessagesRetention,useAssistantsMap,useUnseenConversations,} from '~/hooks';@@ -58,6 +59,12 @@ function ReplyNotifications() {return null;}+/** Isolates the route subscription that keeps the routed conversation's history cached. */+function MessagesRetention() {+ useMessagesRetention();+ return null;+}+/** Isolates keyboard shortcut listeners so they only mount after auth. */function KeyboardShortcutsProvider() {useKeyboardShortcuts();@@ -233,6 +240,7 @@ function RootLayout() {</PromptGroupsProvider><KeyboardShortcutsProvider /><ReplyNotifications />+ <MessagesRetention /></AgentsMapContext.Provider>{config?.interface?.termsOfService?.modalAcceptance === true && (<TermsAndConditionsModaldiff --git a/librechat.example.yaml b/librechat.example.yamlindex e930f56b6f..f1040ff19c 100644--- a/librechat.example.yaml+++ b/librechat.example.yaml@@ -161,6 +161,10 @@ interface:# rename for running chats and unowned placeholder titles; other actions stay available.# Minimum interval between syntax-highlighting passes while streamed code changes (default: 300 ms)# codeHighlightThrottleMs: 300+ # How long a conversation's message history stays cached in the browser after leaving it (default: 60000 ms),+ # and how many of the most recently left conversations keep that grace (default: 1). Older ones are refetched.+ # historyCacheTtlMs: 60000+ # historyCacheRecent: 1# Deployment theme applied to every user, in both light and dark mode (default: unset).# It is not saved to the browser, outranks REACT_APP_THEME_* colors and stored themes,# and yields to the high-contrast modes. Either a bundled theme name (librechat, clickhouse):diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.tsindex 6dc04740e6..5fdaccf951 100644--- a/packages/data-provider/src/config.ts+++ b/packages/data-provider/src/config.ts@@ -2368,6 +2368,10 @@ export const DEFAULT_QUEUED_TURN_RECONCILIATION_TIMEOUT_MS = 60_000;export const DEFAULT_QUEUED_SEND_LOCK_TIMEOUT_MS = 60_000;/** How many recently touched files the composer palette offers to reuse. */export const DEFAULT_COMPOSER_RECENT_FILES = 5;+/** Milliseconds a left conversation's message history stays cached in the browser. */+export const DEFAULT_HISTORY_CACHE_TTL_MS = 60_000;+/** Most recently left conversations whose message history keeps that grace. */+export const DEFAULT_HISTORY_CACHE_RECENT = 1;const mcpServersSchema = z.object({@@ -2772,6 +2776,18 @@ export const interfaceSchema = z* own default maximum (`fileListLimit`) so the palette can never ask for* more than a typical deployment will return. */composerRecentFiles: z.number().int().min(0).max(100).default(DEFAULT_COMPOSER_RECENT_FILES),+ /** Milliseconds a conversation's message history stays cached in the browser after the+ * user leaves it, so returning soon renders without refetching. Long agent transcripts+ * run to tens of megabytes each, so mobile browsers need this short. */+ historyCacheTtlMs: z+ .number()+ .int()+ .min(0)+ .max(60 * 60_000)+ .default(DEFAULT_HISTORY_CACHE_TTL_MS),+ /** How many of the most recently left conversations keep that grace; older ones are+ * released at the next conversation switch. */+ historyCacheRecent: z.number().int().min(0).max(20).default(DEFAULT_HISTORY_CACHE_RECENT),}).default({modelSelect: true,@@ -2856,6 +2872,8 @@ export const interfaceSchema = zqueuedTurnReconciliationTimeoutMs: DEFAULT_QUEUED_TURN_RECONCILIATION_TIMEOUT_MS,queuedSendLockTimeoutMs: DEFAULT_QUEUED_SEND_LOCK_TIMEOUT_MS,composerRecentFiles: DEFAULT_COMPOSER_RECENT_FILES,+ historyCacheTtlMs: DEFAULT_HISTORY_CACHE_TTL_MS,+ historyCacheRecent: DEFAULT_HISTORY_CACHE_RECENT,});export type TInterfaceConfig = z.infer<typeof interfaceSchema>;diff --git a/packages/data-schemas/src/app/interface.spec.ts b/packages/data-schemas/src/app/interface.spec.tsindex f546f8d9d0..632b32e855 100644--- a/packages/data-schemas/src/app/interface.spec.ts+++ b/packages/data-schemas/src/app/interface.spec.ts@@ -105,6 +105,23 @@ describe('loadDefaultInterface', () => {expect(configuredInterface?.composerRecentFiles).toBe(10);});+ it('uses and preserves the schema defaults for the client history cache', async () => {+ const configDefaults = getConfigDefaults();+ const defaultInterface = await loadDefaultInterface({+ config: {},+ configDefaults,+ });+ expect(defaultInterface?.historyCacheTtlMs).toBe(60_000);+ expect(defaultInterface?.historyCacheRecent).toBe(1);++ const configuredInterface = await loadDefaultInterface({+ config: { interface: { historyCacheTtlMs: 0, historyCacheRecent: 3 } },+ configDefaults,+ });+ expect(configuredInterface?.historyCacheTtlMs).toBe(0);+ expect(configuredInterface?.historyCacheRecent).toBe(3);+ });+it('uses and preserves the schema default for steer arm confirmation', async () => {const configDefaults = getConfigDefaults();const interfaceDefaults = {diff --git a/packages/data-schemas/src/app/interface.ts b/packages/data-schemas/src/app/interface.tsindex 8e4340c5d5..b1f0ab9693 100644--- a/packages/data-schemas/src/app/interface.ts+++ b/packages/data-schemas/src/app/interface.ts@@ -58,6 +58,8 @@ export async function loadDefaultInterface({queuedSendLockTimeoutMs:interfaceConfig?.queuedSendLockTimeoutMs ?? defaults.queuedSendLockTimeoutMs,composerRecentFiles: interfaceConfig?.composerRecentFiles ?? defaults.composerRecentFiles,+ historyCacheTtlMs: interfaceConfig?.historyCacheTtlMs ?? defaults.historyCacheTtlMs,+ historyCacheRecent: interfaceConfig?.historyCacheRecent ?? defaults.historyCacheRecent,// Permissions and related settings - only include if explicitly configuredbookmarks: interfaceConfig?.bookmarks,