Skip to content

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

🫗 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.tsx
index 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 && (
<TermsAndConditionsModal
diff --git a/librechat.example.yaml b/librechat.example.yaml
index 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.ts
index 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 = z
queuedTurnReconciliationTimeoutMs: 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.ts
index 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.ts
index 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 configured
bookmarks: interfaceConfig?.bookmarks,