diff options
Diffstat (limited to 'packages/tools/src')
| -rw-r--r-- | packages/tools/src/index.ts | 3 | ||||
| -rw-r--r-- | packages/tools/src/openai/index.ts | 92 | ||||
| -rw-r--r-- | packages/tools/src/openai/middleware.ts | 393 | ||||
| -rw-r--r-- | packages/tools/src/openai/tools.ts (renamed from packages/tools/src/openai.ts) | 4 |
4 files changed, 489 insertions, 3 deletions
diff --git a/packages/tools/src/index.ts b/packages/tools/src/index.ts index 4f21246e..404e0943 100644 --- a/packages/tools/src/index.ts +++ b/packages/tools/src/index.ts @@ -1,2 +1,3 @@ -// Export shared types and utilities export type { SupermemoryToolsConfig } from "./types" + +export type { OpenAIMiddlewareOptions } from "./openai" diff --git a/packages/tools/src/openai/index.ts b/packages/tools/src/openai/index.ts new file mode 100644 index 00000000..517fe282 --- /dev/null +++ b/packages/tools/src/openai/index.ts @@ -0,0 +1,92 @@ +import type OpenAI from "openai" +import { + createOpenAIMiddleware, + type OpenAIMiddlewareOptions, +} from "./middleware" + +/** + * Wraps an OpenAI client with SuperMemory middleware to automatically inject relevant memories + * into the system prompt based on the user's message content. + * + * This middleware searches the supermemory API for relevant memories using the container tag + * and user message, then either appends memories to an existing system prompt or creates + * a new system prompt with the memories. + * + * @param openaiClient - The OpenAI client to wrap with SuperMemory middleware + * @param containerTag - The container tag/identifier for memory search (e.g., user ID, project ID) + * @param options - Optional configuration options for the middleware + * @param options.conversationId - Optional conversation ID to group messages into a single document for contextual memory generation + * @param options.verbose - Optional flag to enable detailed logging of memory search and injection process (default: false) + * @param options.mode - Optional mode for memory search: "profile" (default), "query", or "full" + * @param options.addMemory - Optional mode for memory addition: "always" (default), "never" + * + * @returns An OpenAI client with SuperMemory middleware injected + * + * @example + * ```typescript + * import { withSupermemory } from "@supermemory/tools/openai" + * import OpenAI from "openai" + * + * // Create OpenAI client with supermemory middleware + * const openai = new OpenAI({ + * apiKey: process.env.OPENAI_API_KEY, + * }) + * const openaiWithSupermemory = withSupermemory(openai, "user-123", { + * conversationId: "conversation-456", + * mode: "full", + * addMemory: "always" + * }) + * + * // Use normally - memories will be automatically injected + * const response = await openaiWithSupermemory.chat.completions.create({ + * model: "gpt-4", + * messages: [ + * { role: "user", content: "What's my favorite programming language?" } + * ] + * }) + * ``` + * + * @throws {Error} When SUPERMEMORY_API_KEY environment variable is not set + * @throws {Error} When supermemory API request fails + */ +export function withSupermemory( + openaiClient: OpenAI, + containerTag: string, + options?: OpenAIMiddlewareOptions, +) { + if (!process.env.SUPERMEMORY_API_KEY) { + throw new Error("SUPERMEMORY_API_KEY is not set") + } + + const conversationId = options?.conversationId + const verbose = options?.verbose ?? false + const mode = options?.mode ?? "profile" + const addMemory = options?.addMemory ?? "never" + + const openaiWithSupermemory = createOpenAIMiddleware( + openaiClient, + containerTag, + { + conversationId, + verbose, + mode, + addMemory, + }, + ) + + return openaiWithSupermemory +} + +export type { OpenAIMiddlewareOptions } +export type { MemorySearchResult, MemoryAddResult } from "./tools" +export { + createSearchMemoriesFunction, + createAddMemoryFunction, + supermemoryTools, + getToolDefinitions, + createToolCallExecutor, + createToolCallsExecutor, + createSearchMemoriesTool, + createAddMemoryTool, + memoryToolSchemas, +} from "./tools" diff --git a/packages/tools/src/openai/middleware.ts b/packages/tools/src/openai/middleware.ts new file mode 100644 index 00000000..8d83874d --- /dev/null +++ b/packages/tools/src/openai/middleware.ts @@ -0,0 +1,393 @@ +import type OpenAI from "openai" +import Supermemory from "supermemory" +import { createLogger, type Logger } from "../vercel/logger" +import { convertProfileToMarkdown } from "../vercel/util" + +export interface OpenAIMiddlewareOptions { + conversationId?: string + verbose?: boolean + mode?: "profile" | "query" | "full" + addMemory?: "always" | "never" +} + +interface SupermemoryProfileSearch { + profile: { + static?: Array<{ memory: string; metadata?: Record<string, unknown> }> + dynamic?: Array<{ memory: string; metadata?: Record<string, unknown> }> + } + searchResults: { + results: Array<{ memory: string; metadata?: Record<string, unknown> }> + } +} + +/** + * Extracts the last user message from an array of chat completion messages. + * + * Searches through the messages array in reverse order to find the most recent + * message with role "user" and returns its content as a string. + * + * @param messages - Array of chat completion message parameters + * @returns The content of the last user message, or empty string if none found + * + * @example + * ```typescript + * const messages = [ + * { role: "system", content: "You are a helpful assistant." }, + * { role: "user", content: "Hello there!" }, + * { role: "assistant", content: "Hi! How can I help you?" }, + * { role: "user", content: "What's the weather like?" } + * ] + * + * const lastMessage = getLastUserMessage(messages) + * // Returns: "What's the weather like?" + * ``` + */ +const getLastUserMessage = ( + messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[], +) => { + const lastUserMessage = messages + .slice() + .reverse() + .find((msg) => msg.role === "user") + + return typeof lastUserMessage?.content === "string" + ? lastUserMessage.content + : "" +} + +/** + * Searches for memories using the SuperMemory profile API. + * + * Makes a POST request to the SuperMemory API to retrieve user profile memories + * and search results based on the provided container tag and optional query text. + * + * @param containerTag - The container tag/identifier for memory search (e.g., user ID, project ID) + * @param queryText - Optional query text to search for specific memories. If empty, returns all profile memories + * @returns Promise that resolves to the SuperMemory profile search response + * @throws {Error} When the API request fails or returns an error status + * + * @example + * ```typescript + * // Search with query + * const results = await supermemoryProfileSearch("user-123", "favorite programming language") + * + * // Get all profile memories + * const profile = await supermemoryProfileSearch("user-123", "") + * ``` + */ +const supermemoryProfileSearch = async ( + containerTag: string, + queryText: string, +): Promise<SupermemoryProfileSearch> => { + const payload = queryText + ? JSON.stringify({ + q: queryText, + containerTag: containerTag, + }) + : JSON.stringify({ + containerTag: containerTag, + }) + + try { + const response = await fetch("https://api.supermemory.ai/v4/profile", { + method: "POST", + headers: { + "Content-Type": "application/json", + Authorization: `Bearer ${process.env.SUPERMEMORY_API_KEY}`, + }, + body: payload, + }) + + if (!response.ok) { + const errorText = await response.text().catch(() => "Unknown error") + throw new Error( + `Supermemory profile search failed: ${response.status} ${response.statusText}. ${errorText}`, + ) + } + + return await response.json() + } catch (error) { + if (error instanceof Error) { + throw error + } + throw new Error(`Supermemory API request failed: ${error}`) + } +} + +/** + * Adds memory-enhanced system prompts to chat completion messages. + * + * Searches for relevant memories based on the specified mode and injects them + * into the conversation. If a system prompt already exists, memories are appended + * to it. Otherwise, a new system prompt is created with the memories. + * + * @param messages - Array of chat completion message parameters + * @param containerTag - The container tag/identifier for memory search + * @param logger - Logger instance for debugging and info output + * @param mode - Memory search mode: "profile" (all memories), "query" (search-based), or "full" (both) + * @returns Promise that resolves to enhanced messages with memory-injected system prompt + * + * @example + * ```typescript + * const messages = [ + * { role: "user", content: "What's my favorite programming language?" } + * ] + * + * const enhancedMessages = await addSystemPrompt( + * messages, + * "user-123", + * logger, + * "full" + * ) + * // Returns messages with system prompt containing relevant memories + * ``` + */ +const addSystemPrompt = async ( + messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[], + containerTag: string, + logger: Logger, + mode: "profile" | "query" | "full", +) => { + const systemPromptExists = messages.some((msg) => msg.role === "system") + + const queryText = mode !== "profile" ? getLastUserMessage(messages) : "" + + const memoriesResponse = await supermemoryProfileSearch( + containerTag, + queryText, + ) + + const memoryCountStatic = memoriesResponse.profile.static?.length || 0 + const memoryCountDynamic = memoriesResponse.profile.dynamic?.length || 0 + + logger.info("Memory search completed", { + containerTag, + memoryCountStatic, + memoryCountDynamic, + queryText: + queryText.substring(0, 100) + (queryText.length > 100 ? "..." : ""), + mode, + }) + + const profileData = + mode !== "query" + ? convertProfileToMarkdown({ + profile: { + static: memoriesResponse.profile.static?.map((item) => item.memory), + dynamic: memoriesResponse.profile.dynamic?.map( + (item) => item.memory, + ), + }, + searchResults: { + results: memoriesResponse.searchResults.results.map((item) => ({ + memory: item.memory, + })) as [{ memory: string }], + }, + }) + : "" + const searchResultsMemories = + mode !== "profile" + ? `Search results for user's recent message: \n${memoriesResponse.searchResults.results + .map((result) => `- ${result.memory}`) + .join("\n")}` + : "" + + const memories = `${profileData}\n${searchResultsMemories}`.trim() + + if (memories) { + logger.debug("Memory content preview", { + content: memories, + fullLength: memories.length, + }) + } + + if (systemPromptExists) { + logger.debug("Added memories to existing system prompt") + return messages.map((msg) => + msg.role === "system" + ? { ...msg, content: `${msg.content} \n ${memories}` } + : msg, + ) + } + + logger.debug( + "System prompt does not exist, created system prompt with memories", + ) + return [{ role: "system" as const, content: memories }, ...messages] +} + +/** + * Converts an array of chat completion messages into a formatted conversation string. + * + * Transforms the messages array into a readable conversation format where each + * message is prefixed with its role (User/Assistant) and messages are separated + * by double newlines. + * + * @param messages - Array of chat completion message parameters + * @returns Formatted conversation string with role prefixes + * + * @example + * ```typescript + * const messages = [ + * { role: "user", content: "Hello!" }, + * { role: "assistant", content: "Hi there!" }, + * { role: "user", content: "How are you?" } + * ] + * + * const conversation = getConversationContent(messages) + * // Returns: "User: Hello!\n\nAssistant: Hi there!\n\nUser: How are you?" + * ``` + */ +const getConversationContent = ( + messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[], +) => { + return messages + .map((msg) => { + const role = msg.role === "user" ? "User" : "Assistant" + const content = typeof msg.content === "string" ? msg.content : "" + return `${role}: ${content}` + }) + .join("\n\n") +} + +/** + * Adds a new memory to the SuperMemory system. + * + * Saves the provided content as a memory with the specified container tag and + * optional custom ID. Logs success or failure information for debugging. + * + * @param client - SuperMemory client instance + * @param containerTag - The container tag/identifier for the memory + * @param content - The content to save as a memory + * @param customId - Optional custom ID for the memory (e.g., conversation ID) + * @param logger - Logger instance for debugging and info output + * @returns Promise that resolves when memory is saved (or fails silently) + * + * @example + * ```typescript + * await addMemoryTool( + * supermemoryClient, + * "user-123", + * "User prefers React with TypeScript", + * "conversation-456", + * logger + * ) + * ``` + */ +const addMemoryTool = async ( + client: Supermemory, + containerTag: string, + content: string, + customId: string | undefined, + logger: Logger, +): Promise<void> => { + try { + const response = await client.memories.add({ + content, + containerTags: [containerTag], + customId, + }) + + logger.info("Memory saved successfully", { + containerTag, + customId, + contentLength: content.length, + memoryId: response.id, + }) + } catch (error) { + logger.error("Error saving memory", { + error: error instanceof Error ? error.message : "Unknown error", + }) + } +} + +/** + * Creates SuperMemory middleware for OpenAI clients. + * + * This function creates middleware that automatically injects relevant memories + * into OpenAI chat completions and optionally saves new memories. The middleware + * can wrap existing OpenAI clients or create new ones with SuperMemory capabilities. + * + * @param containerTag - The container tag/identifier for memory search (e.g., user ID, project ID) + * @param options - Optional configuration options for the middleware + * @param options.conversationId - Optional conversation ID to group messages for contextual memory generation + * @param options.verbose - Enable detailed logging of memory operations (default: false) + * @param options.mode - Memory search mode: "profile" (all memories), "query" (search-based), or "full" (both) (default: "profile") + * @param options.addMemory - Automatic memory storage mode: "always" or "never" (default: "never") + * @returns Object with `wrapClient` and `createClient` methods + * @throws {Error} When SUPERMEMORY_API_KEY environment variable is not set + * + * @example + * ```typescript + * const openaiWithSupermemory = createOpenAIMiddleware(openai, "user-123", { + * conversationId: "conversation-456", + * mode: "full", + * addMemory: "always", + * verbose: true + * }) + * + * ``` + */ +export function createOpenAIMiddleware( + openaiClient: OpenAI, + containerTag: string, + options?: OpenAIMiddlewareOptions, +) { + const logger = createLogger(options?.verbose ?? false) + const client = new Supermemory({ + apiKey: process.env.SUPERMEMORY_API_KEY, + }) + + const originalCreate = openaiClient.chat.completions.create + + const createWithMemory = async ( + params: OpenAI.Chat.Completions.ChatCompletionCreateParams, + ) => { + const messages = Array.isArray(params.messages) ? params.messages : [] + + if (addMemory === "always") { + const userMessage = getLastUserMessage(messages) + if (userMessage?.trim()) { + const content = conversationId + ? getConversationContent(messages) + : userMessage + const customId = conversationId + ? `conversation:${conversationId}` + : undefined + + addMemoryTool(client, containerTag, content, customId, logger) + } + } + + if (mode !== "profile") { + const userMessage = getLastUserMessage(messages) + if (!userMessage) { + logger.debug("No user message found, skipping memory search") + return originalCreate.call(openaiClient.chat.completions, params) + } + } + + logger.info("Starting memory search", { + containerTag, + conversationId, + mode, + }) + + const enhancedMessages = await addSystemPrompt( + messages, + containerTag, + logger, + mode, + ) + + return originalCreate.call(openaiClient.chat.completions, { + ...params, + messages: enhancedMessages, + }) + } + + openaiClient.chat.completions.create = + createWithMemory as typeof originalCreate + + return openaiClient +} diff --git a/packages/tools/src/openai.ts b/packages/tools/src/openai/tools.ts index 5c79a9c1..4078df09 100644 --- a/packages/tools/src/openai.ts +++ b/packages/tools/src/openai/tools.ts @@ -5,8 +5,8 @@ import { PARAMETER_DESCRIPTIONS, TOOL_DESCRIPTIONS, getContainerTags, -} from "./shared" -import type { SupermemoryToolsConfig } from "./types" +} from "../shared" +import type { SupermemoryToolsConfig } from "../types" /** * Result types for memory operations |