From e6929f5ca05836669da5a4331f397b25e337befc Mon Sep 17 00:00:00 2001 From: "lia-by-librechat[bot]" <328778573+lia-by-librechat[bot]@users.noreply.github.com> Date: Thu, 24 Sep 2026 08:43:36 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=AA=B4=20fix:=20Surface=20Persistent=20Me?= =?UTF-8?q?mory=20Before=20First=20Save=20(#16301)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix: Surface Persistent Memory Before First Save * fix: Distinguish Unreadable Memory From Empty Memory --------- Co-authored-by: Lia --- .../agents/__tests__/openai.spec.js | 28 ++++ .../agents/__tests__/responses.unit.spec.js | 28 ++++ api/server/controllers/agents/client.js | 7 +- api/server/controllers/agents/client.test.js | 120 ++++++++++++++ packages/api/src/agents/memory.spec.ts | 154 +++++++++++++++++- packages/api/src/agents/memory.ts | 76 ++++++--- .../data-schemas/src/methods/memory.spec.ts | 25 +++ packages/data-schemas/src/methods/memory.ts | 7 +- packages/data-schemas/src/types/memory.ts | 23 ++- 9 files changed, 430 insertions(+), 38 deletions(-) diff --git a/api/server/controllers/agents/__tests__/openai.spec.js b/api/server/controllers/agents/__tests__/openai.spec.js index 1adfef2ba2..1ba6190482 100644 --- a/api/server/controllers/agents/__tests__/openai.spec.js +++ b/api/server/controllers/agents/__tests__/openai.spec.js @@ -820,6 +820,34 @@ describe('OpenAIChatCompletionController', () => { expect(mockExecution.beginProviderExecution).toHaveBeenCalledTimes(1); }); + it('includes persistent-memory guidance in an inline agent with no saved memories', async () => { + const api = require('@librechat/api'); + const { memoryInstructions, buildInlineMemoryContext } = jest.requireActual('@librechat/api'); + const agent = { + id: 'agent-123', + model: 'gpt-4', + model_parameters: {}, + toolRegistry: {}, + edges: [], + memoryToolsRegistered: true, + }; + api.initializeAgent.mockResolvedValueOnce(agent); + mockBuildInlineMemoryContext.mockImplementationOnce(buildInlineMemoryContext); + + await OpenAIChatCompletionController(req, res); + + expect(mockApplyContextToAgent).toHaveBeenCalledWith( + expect.objectContaining({ + agent, + sharedRunContext: expect.stringContaining(memoryInstructions), + }), + ); + expect(require('~/models').getFormattedMemories).toHaveBeenCalledWith({ + userId: 'user-123', + agentId: undefined, + }); + }); + it('resolves saved graph subagents for remote chat-completion runs', async () => { const { initializeAgent, diff --git a/api/server/controllers/agents/__tests__/responses.unit.spec.js b/api/server/controllers/agents/__tests__/responses.unit.spec.js index 0e7c655156..069ad64c29 100644 --- a/api/server/controllers/agents/__tests__/responses.unit.spec.js +++ b/api/server/controllers/agents/__tests__/responses.unit.spec.js @@ -813,6 +813,34 @@ describe('createResponse controller', () => { expect(mockExecution.beginProviderExecution).toHaveBeenCalledTimes(1); }); + it('includes persistent-memory guidance in an inline agent with no saved memories', async () => { + const api = require('@librechat/api'); + const { memoryInstructions, buildInlineMemoryContext } = jest.requireActual('@librechat/api'); + const agent = { + id: 'agent-123', + model: 'claude-3', + model_parameters: {}, + toolRegistry: {}, + edges: [], + memoryToolsRegistered: true, + }; + api.initializeAgent.mockResolvedValueOnce(agent); + mockBuildInlineMemoryContext.mockImplementationOnce(buildInlineMemoryContext); + + await createResponse(req, res); + + expect(mockApplyContextToAgent).toHaveBeenCalledWith( + expect.objectContaining({ + agent, + sharedRunContext: expect.stringContaining(memoryInstructions), + }), + ); + expect(require('~/models').getFormattedMemories).toHaveBeenCalledWith({ + userId: 'user-123', + agentId: undefined, + }); + }); + it('resolves saved graph subagents for remote Responses API runs', async () => { const { initializeAgent, resolveSubagentGraphs } = require('@librechat/api'); const primaryConfig = { diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.js index fcf65b8c02..a76dd8e650 100644 --- a/api/server/controllers/agents/client.js +++ b/api/server/controllers/agents/client.js @@ -17,7 +17,7 @@ const { getBalanceConfig, omitTitleOptions, getProviderConfig, - memoryInstructions, + formatMemoryContext, createCachedTokenCounter, applyContextToAgent, isMemoryAgentEnabled, @@ -2872,8 +2872,6 @@ class AgentClient extends BaseClient { * `delete_memory`; everyone else gets the unkeyed values only. */ /** Partition the loaded memories belong to (the primary agent's). */ const loadedMemoryAgentId = getMemoryAgentId(this.options.agent); - const buildMemoryContext = (text) => - text ? `${memoryInstructions}\n\n# Existing memory about the user:\n${text}` : undefined; /** Resolves formatted memories for an agent's own partition. A defined * `memories` means the run-level gates (permission, opt-out, config) * passed; agents on other partitions fetch through the request-scoped @@ -3014,7 +3012,7 @@ class AgentClient extends BaseClient { modelBoundMemoryContexts.add(partitionMemories.withoutKeys); agentMemoryContexts.push(partitionMemories.withoutKeys); } - const agentMemoryContext = buildMemoryContext( + const agentMemoryContext = formatMemoryContext( agentHasMemory ? partitionMemories?.withKeys : partitionMemories?.withoutKeys, ); if (agentMemoryContext) { @@ -3380,6 +3378,7 @@ class AgentClient extends BaseClient { getUserMemories: db.getUserMemories, getFormattedMemories: db.getFormattedMemories, }, + req: this.options.req, res: this.options.res, user: createSafeUser(this.options.req.user), tenantId: resolveRequestTenantId(this.options.req), diff --git a/api/server/controllers/agents/client.test.js b/api/server/controllers/agents/client.test.js index c646df0436..4cc2f02655 100644 --- a/api/server/controllers/agents/client.test.js +++ b/api/server/controllers/agents/client.test.js @@ -7936,6 +7936,88 @@ describe('AgentClient - titleConvo', () => { expect(parallelAgent2.additional_instructions ?? '').not.toContain(memoryContent); }); + it('tells the primary read-only agent about persistent memory when the store is empty', async () => { + const { memoryInstructions } = require('@librechat/api'); + client.useMemory = jest.fn().mockResolvedValue({ withKeys: '', withoutKeys: '' }); + const parallelAgent = { + id: 'parallel-agent-1', + instructions: 'Parallel instructions', + provider: EModelEndpoint.openAI, + }; + client.agentConfigs = new Map([['parallel-agent-1', parallelAgent]]); + + await client.buildMessages( + [ + { + messageId: 'msg-1', + parentMessageId: null, + sender: 'User', + text: 'Remember that I like tea', + isCreatedByUser: true, + }, + ], + null, + { instructions: 'Base instructions', additional_instructions: null }, + ); + + expect(client.options.agent.additional_instructions).toContain(memoryInstructions); + expect(client.options.agent.additional_instructions).not.toContain('# Existing memory'); + expect(client.options.agent.additional_instructions).not.toContain('set_memory'); + expect(parallelAgent.additional_instructions ?? '').not.toContain(memoryInstructions); + }); + + it('keeps memory guidance out of agents when memory was unavailable', async () => { + const { memoryInstructions } = require('@librechat/api'); + client.useMemory = jest.fn().mockResolvedValue(undefined); + client.agentConfigs = new Map(); + + await client.buildMessages( + [ + { + messageId: 'msg-1', + parentMessageId: null, + sender: 'User', + text: 'Hello', + isCreatedByUser: true, + }, + ], + null, + { instructions: 'Base instructions', additional_instructions: null }, + ); + + expect(client.options.agent.additional_instructions ?? '').not.toContain(memoryInstructions); + }); + + it('provides empty-state memory guidance to parallel agents when automatic extraction is on', async () => { + const { memoryInstructions } = require('@librechat/api'); + client.useMemory = jest.fn().mockResolvedValue({ withKeys: '', withoutKeys: '' }); + mockReq.config.memory.agent = { enabled: true, id: 'memory-agent' }; + const parallelAgent = { + id: 'parallel-agent-1', + instructions: 'Parallel instructions', + provider: EModelEndpoint.openAI, + }; + client.agentConfigs = new Map([['parallel-agent-1', parallelAgent]]); + + await client.buildMessages( + [ + { + messageId: 'msg-1', + parentMessageId: null, + sender: 'User', + text: 'Remember that I like tea', + isCreatedByUser: true, + }, + ], + null, + { instructions: 'Base instructions', additional_instructions: null }, + ); + + expect(client.options.agent.additional_instructions).toContain(memoryInstructions); + expect(parallelAgent.additional_instructions).toContain(memoryInstructions); + expect(parallelAgent.additional_instructions).not.toContain('# Existing memory'); + }); + it('applies scoped context to graph-only members without promoting them', async () => { client.useMemory = jest.fn().mockResolvedValue(undefined); const graphMember = { @@ -8388,6 +8470,21 @@ describe('AgentClient - titleConvo', () => { ); }); + it('retains automatic memory extraction when the first conversation has no memories', async () => { + const processMemory = jest.fn(); + mockCheckAccess.mockResolvedValue(true); + mockInitializeAgent.mockResolvedValue({ ...mockAgent }); + mockCreateMemoryProcessor.mockResolvedValue(['', processMemory]); + + client = new AgentClient(mockOptions); + client.conversationId = 'convo-123'; + client.responseMessageId = 'response-123'; + + await expect(client.useMemory()).resolves.toEqual({ withKeys: '', withoutKeys: '' }); + expect(mockCreateMemoryProcessor).toHaveBeenCalledTimes(1); + expect(client.processMemory).toBe(processMemory); + }); + it('should return existing memories without auto-processing when memory agent is not enabled', async () => { mockReq.config.memory = { personalize: true, @@ -8438,6 +8535,29 @@ describe('AgentClient - titleConvo', () => { expect(client.processMemory).toBeUndefined(); }); + it('does not interpret a failed memory read as an eligible empty store', async () => { + mockReq.config.memory = { personalize: true }; + mockCheckAccess.mockResolvedValue(true); + mockGetFormattedMemories.mockResolvedValue({ + readFailed: true, + withKeys: undefined, + withoutKeys: undefined, + totalTokens: 0, + }); + + client = new AgentClient(mockOptions); + client.conversationId = 'convo-123'; + client.responseMessageId = 'response-123'; + + const result = await client.useMemory(); + + expect(result).toEqual({ withKeys: undefined, withoutKeys: undefined }); + expect(mockCreateMemoryProcessor).not.toHaveBeenCalled(); + expect(client.processMemory).toBeUndefined(); + const { formatMemoryContext } = require('@librechat/api'); + expect(formatMemoryContext(result.withoutKeys)).toBeUndefined(); + }); + it('should return existing memories without auto-processing when memory agent config lacks explicit enablement', async () => { mockReq.config.memory.agent = { id: 'agent-123', diff --git a/packages/api/src/agents/memory.spec.ts b/packages/api/src/agents/memory.spec.ts index 918f979782..3f1285207a 100644 --- a/packages/api/src/agents/memory.spec.ts +++ b/packages/api/src/agents/memory.spec.ts @@ -9,6 +9,8 @@ import type { Response } from 'express'; import type { ServerRequest } from '~/types'; import { processMemory, + memoryInstructions, + formatMemoryContext, createMemoryProcessor, createMemoryTool, getMemoryAgentId, @@ -159,7 +161,7 @@ describe('Memory attachment generation fencing', () => { }, }); - await runMemory([]); + await runMemory!([]); expect(GenerationJobManager.emitChunk).toHaveBeenCalledWith( 'conversation-1', @@ -797,7 +799,7 @@ describe('memory token limit guidance', () => { }, }); - await process([]); + await process!([]); const runCalls = (Run.create as jest.Mock).mock.calls; const runConfig = runCalls[runCalls.length - 1][0]; @@ -869,6 +871,38 @@ describe('buildInlineMemoryTool content filtering', () => { }); }); +describe('buildInlineMemoryTool read failure', () => { + it('refuses a limited write when current usage could not be read', async () => { + const setMemory = jest.fn(); + const getFormattedMemories = jest.fn().mockResolvedValue({ + withKeys: undefined, + withoutKeys: undefined, + totalTokens: 0, + readFailed: true, + }); + const req = { + config: { + endpoints: { [EModelEndpoint.agents]: { capabilities: [AgentCapabilities.memory] } }, + memory: { disabled: false, tokenLimit: 100 }, + }, + user: { id: 'user-1', personalization: { memories: true } }, + } as ServerRequest; + + const memoryTool = await buildInlineMemoryTool({ + toolName: 'set_memory', + req, + agent: { tools: [AgentCapabilities.memory] }, + userId: 'user-1', + memoryMethods: { setMemory, deleteMemory: jest.fn(), getFormattedMemories }, + getRoleByName: jest.fn(), + }); + + expect(memoryTool).toBeNull(); + expect(getFormattedMemories).toHaveBeenCalledTimes(1); + expect(setMemory).not.toHaveBeenCalled(); + }); +}); + describe('agentHasInlineMemoryTools', () => { it('returns false for a nullish agent', () => { expect(agentHasInlineMemoryTools(null)).toBe(false); @@ -893,6 +927,23 @@ describe('agentHasInlineMemoryTools', () => { }); }); +describe('formatMemoryContext', () => { + it('distinguishes unavailable memory from an eligible empty store', () => { + expect(formatMemoryContext(undefined)).toBeUndefined(); + expect(formatMemoryContext('')).toBe(memoryInstructions); + expect(memoryInstructions).toMatch(/persistent memory.*across conversations/i); + expect(memoryInstructions).not.toContain('automatically stores'); + expect(memoryInstructions).not.toContain('No existing memories'); + expect(memoryInstructions).not.toMatch(/librechat/i); + }); + + it('includes existing memories without losing the capability guidance', () => { + expect(formatMemoryContext('name: Danny')).toBe( + `${memoryInstructions}\n\n# Existing memory about the user:\nname: Danny`, + ); + }); +}); + describe('buildInlineMemoryContext', () => { it('loads keyed memories for an initialized inline-memory agent', async () => { const getFormattedMemories = jest.fn().mockResolvedValue({ @@ -919,6 +970,74 @@ describe('buildInlineMemoryContext', () => { }); }); + it('announces persistent memory before an inline agent has saved anything', async () => { + const getFormattedMemories = jest.fn().mockResolvedValue({ + withKeys: '', + withoutKeys: '', + totalTokens: 0, + }); + const context = await buildInlineMemoryContext({ + agent: { id: 'agent_memory', memoryToolsRegistered: true }, + req: {} as never, + userId: 'user-1', + memoryAvailable: true, + getFormattedMemories, + }); + + expect(context).toBe(memoryInstructions); + expect(context).not.toContain('# Existing memory about the user:'); + expect(getFormattedMemories).toHaveBeenCalledWith({ + userId: 'user-1', + agentId: undefined, + }); + }); + + it('does not load or announce memory when permission is denied', async () => { + const getFormattedMemories = jest.fn(); + await expect( + buildInlineMemoryContext({ + agent: { id: 'agent_memory', memoryToolsRegistered: true }, + req: {} as never, + userId: 'user-1', + memoryAvailable: false, + getFormattedMemories, + }), + ).resolves.toBe(''); + expect(getFormattedMemories).not.toHaveBeenCalled(); + }); + + it('keeps failed loads distinct from an empty store', async () => { + const getFormattedMemories = jest.fn().mockRejectedValue(new Error('read failed')); + await expect( + buildInlineMemoryContext({ + agent: { id: 'agent_memory', memoryToolsRegistered: true }, + req: {} as never, + userId: 'user-1', + memoryAvailable: true, + getFormattedMemories, + }), + ).resolves.toBe(''); + }); + + it('suppresses guidance when a real database read is marked as failed', async () => { + const getFormattedMemories = jest.fn().mockResolvedValue({ + withKeys: undefined, + withoutKeys: undefined, + totalTokens: 0, + readFailed: true, + }); + await expect( + buildInlineMemoryContext({ + agent: { id: 'agent_memory', memoryToolsRegistered: true }, + req: {} as never, + userId: 'user-1', + memoryAvailable: true, + getFormattedMemories, + }), + ).resolves.toBe(''); + expect(getFormattedMemories).toHaveBeenCalledTimes(1); + }); + it('does not load memories when inline tools are unavailable', async () => { const getFormattedMemories = jest.fn(); await expect( @@ -934,6 +1053,37 @@ describe('buildInlineMemoryContext', () => { }); }); +describe('createMemoryProcessor read failure', () => { + it('skips extraction and reuses the failed snapshot within the request', async () => { + const req = {}; + const getFormattedMemories = jest.fn().mockResolvedValue({ + withKeys: undefined, + withoutKeys: undefined, + totalTokens: 0, + readFailed: true, + }); + const result = await createMemoryProcessor({ + req, + res: { headersSent: false, write: jest.fn() } as unknown as Response, + userId: 'user-1', + messageId: 'message-1', + conversationId: 'conversation-1', + memoryMethods: { + setMemory: jest.fn(), + deleteMemory: jest.fn(), + getUserMemories: jest.fn(), + getFormattedMemories, + }, + }); + expect(result).toEqual([undefined, undefined]); + await expect( + getRequestMemories({ req, userId: 'user-1', getFormattedMemories }), + ).resolves.toMatchObject({ readFailed: true, withKeys: undefined, withoutKeys: undefined }); + expect(getFormattedMemories).toHaveBeenCalledTimes(1); + expect(Run.create).not.toHaveBeenCalled(); + }); +}); + describe('getRequestMemories caching', () => { it('memoizes per request, then re-fetches after invalidation', async () => { const getFormattedMemories = jest diff --git a/packages/api/src/agents/memory.ts b/packages/api/src/agents/memory.ts index 9e7627d9aa..97f62332a7 100644 --- a/packages/api/src/agents/memory.ts +++ b/packages/api/src/agents/memory.ts @@ -74,7 +74,16 @@ function normalizeMemoryLLMConfig(llmConfig?: Partial): SanitizedMemo } export const memoryInstructions = - 'The system automatically stores important user information and can update or delete memories based on user requests, enabling dynamic memory management.'; + 'Persistent memory is available across conversations within the current memory scope. Saved memories, if any, are shown below. No entries shown here does not mean memory is unavailable. Use memory tools only if provided; claim a memory was saved or deleted only after the action is confirmed.'; + +export function formatMemoryContext(memory: string | undefined): string | undefined { + if (memory == null) { + return undefined; + } + return memory + ? `${memoryInstructions}\n\n# Existing memory about the user:\n${memory}` + : memoryInstructions; +} export const SET_MEMORY_TOOL_NAME = 'set_memory'; export const DELETE_MEMORY_TOOL_NAME = 'delete_memory'; @@ -505,7 +514,7 @@ export function agentHasInlineMemoryTools(agent: InlineMemoryAgent): boolean { ); } -/** Builds the existing-memory system context for an inline-memory agent. */ +/** Builds the memory system context for an inline-memory agent. */ export async function buildInlineMemoryContext({ agent, req, @@ -529,9 +538,7 @@ export async function buildInlineMemoryContext({ agentId: getMemoryAgentId(agent), getFormattedMemories, }); - return memories.withKeys - ? `${memoryInstructions}\n\n# Existing memory about the user:\n${memories.withKeys}` - : ''; + return formatMemoryContext(memories.withKeys) ?? ''; } catch (error) { logger.error('[memory] Error loading inline agent memory context', error); return ''; @@ -691,8 +698,12 @@ export async function buildInlineMemoryTool({ agentId: memoryAgentId, getFormattedMemories: memoryMethods.getFormattedMemories, }); - totalTokens = formatted?.totalTokens ?? 0; - tokenCountsByKey = formatted?.tokenCountsByKey; + /** A formatted read failure has no trustworthy usage total. */ + if (formatted.readFailed) { + return null; + } + totalTokens = formatted.totalTokens ?? 0; + tokenCountsByKey = formatted.tokenCountsByKey; } catch (error) { logger.error( '[memory] Failed to load memory token count for set_memory', @@ -1025,6 +1036,7 @@ export async function createMemoryProcessor({ messageId, memoryMethods, conversationId, + req, config = {}, filters, streamId = null, @@ -1039,6 +1051,8 @@ export async function createMemoryProcessor({ /** Agent partition; omit for the shared personal pool */ agentId?: string; memoryMethods: RequiredMemoryMethods; + /** Reuses the request-scoped formatted snapshot for the chat context. */ + req?: object; config?: MemoryConfig; filters?: FiltersConfig; streamId?: string | null; @@ -1046,27 +1060,41 @@ export async function createMemoryProcessor({ user?: IUser; tenantId?: string; }): Promise< - [ - string, - ( - messages: BaseMessage[], - inspectionMessages?: BaseMessage[], - ) => Promise<(TAttachment | null)[] | undefined>, - ] + | [undefined, undefined] + | [ + string, + ( + messages: BaseMessage[], + inspectionMessages?: BaseMessage[], + ) => Promise<(TAttachment | null)[] | undefined>, + ] > { const { validKeys, instructions, llmConfig, tokenLimit } = config; const finalInstructions = instructions || getDefaultInstructions(validKeys, tokenLimit); - const [{ withKeys, withoutKeys, totalTokens, tokenCountsByKey }, memoryEntries] = - await Promise.all([ - memoryMethods.getFormattedMemories({ - userId, - agentId, - }), - hasActivePiiPatterns(filters?.memories?.pii) - ? memoryMethods.getUserMemories({ userId, agentId }) - : Promise.resolve(undefined), - ]); + const [formatted, memoryEntries] = await Promise.all([ + (req + ? getRequestMemories({ + req, + userId, + agentId, + getFormattedMemories: memoryMethods.getFormattedMemories, + }) + : memoryMethods.getFormattedMemories({ userId, agentId }) + ).catch((error) => { + logger.error('[memory] Error loading automatic memory context', getSafeErrorMetadata(error)); + return undefined; + }), + hasActivePiiPatterns(filters?.memories?.pii) + ? memoryMethods.getUserMemories({ userId, agentId }) + : Promise.resolve(undefined), + ]); + /** Without the current memory snapshot we cannot safely seed token limits + * or assert that no previous memories exist. Skip extraction for this turn. */ + if (!formatted || formatted.readFailed) { + return [undefined, undefined]; + } + const { withKeys, withoutKeys, totalTokens, tokenCountsByKey } = formatted; return [ withoutKeys, diff --git a/packages/data-schemas/src/methods/memory.spec.ts b/packages/data-schemas/src/methods/memory.spec.ts index ec1f3d4362..09d9d7dec2 100644 --- a/packages/data-schemas/src/methods/memory.spec.ts +++ b/packages/data-schemas/src/methods/memory.spec.ts @@ -256,6 +256,31 @@ describe('memory partitions', () => { expect(partitionA.withKeys).not.toContain('personal one'); }); + it('signals a read failure rather than reporting an empty memory partition', async () => { + const find = jest.spyOn(MemoryEntry, 'find').mockImplementationOnce(() => { + throw new Error('simulated memory read failure'); + }); + try { + const failed = await methods.getFormattedMemories({ userId }); + expect(failed).toEqual({ + withKeys: undefined, + withoutKeys: undefined, + totalTokens: 0, + tokenCountsByKey: new Map(), + readFailed: true, + }); + } finally { + find.mockRestore(); + } + const empty = await methods.getFormattedMemories({ userId }); + expect(empty).toEqual({ + withKeys: '', + withoutKeys: '', + totalTokens: 0, + tokenCountsByKey: new Map(), + }); + }); + it('returns every partition from getAllUserMemories and wipes them all on deleteAllUserMemories', async () => { await methods.setMemory({ userId, key: 'one', value: 'personal', tokenCount: 1 }); await methods.setMemory({ userId, key: 'two', value: 'agent a', tokenCount: 1, agentId }); diff --git a/packages/data-schemas/src/methods/memory.ts b/packages/data-schemas/src/methods/memory.ts index ebff3a2160..c41f3763da 100644 --- a/packages/data-schemas/src/methods/memory.ts +++ b/packages/data-schemas/src/methods/memory.ts @@ -311,11 +311,14 @@ export function createMemoryMethods(mongoose: typeof import('mongoose')): { return { withKeys, withoutKeys, totalTokens, tokenCountsByKey }; } catch (error) { logger.error('Failed to get formatted memories:', error); + /** Keep the current error handling without presenting a read failure + * as an eligible, empty memory partition to prompt consumers. */ return { - withKeys: '', - withoutKeys: '', + withKeys: undefined, + withoutKeys: undefined, totalTokens: 0, tokenCountsByKey: new Map(), + readFailed: true, }; } } diff --git a/packages/data-schemas/src/types/memory.ts b/packages/data-schemas/src/types/memory.ts index a8ccce8fe4..89a3123cb2 100644 --- a/packages/data-schemas/src/types/memory.ts +++ b/packages/data-schemas/src/types/memory.ts @@ -72,9 +72,20 @@ export interface SetMemoryByIdResult extends MemoryResult { memory?: IMemoryEntryLean; } -export interface FormattedMemoriesResult { - withKeys: string; - withoutKeys: string; - totalTokens?: number; - tokenCountsByKey?: Map; -} +/** A failed read is not an empty memory partition. Consumers can suppress + * memory guidance and writes without changing the shape of successful reads. */ +export type FormattedMemoriesResult = + | { + withKeys: string; + withoutKeys: string; + totalTokens?: number; + tokenCountsByKey?: Map; + readFailed?: false; + } + | { + withKeys: undefined; + withoutKeys: undefined; + totalTokens?: number; + tokenCountsByKey?: Map; + readFailed: true; + };