pkg(tools): Expose raw search results in MemoryPromptData for prompt templates (#787)

Expose raw search results in `MemoryPromptData` so prompt templates can traverse, filter, and selectively include results based on metadata (e.g. score, source).

##### Usage example

```typescript
const promptTemplate = (data: MemoryPromptData) => {
  const relevant = data.searchResults.filter(
    (r) => (r.metadata?.score as number) > 0.7
  )
  return `${data.userMemories}\n${relevant.map(r => r.memory).join('\n')}`
}
```

apps/docs/ai-sdk/user-profiles.mdx

@@ -154,6 +154,7 @@ The `MemoryPromptData` object passed to your template function provides:
 
 - `userMemories`: Pre-formatted markdown combining static profile facts (name, preferences, goals) and dynamic context (current projects, recent interests)
 - `generalSearchMemories`: Pre-formatted search results based on semantic similarity to the current query (empty string if mode is "profile")
+- `searchResults`: Raw search results array (`Array<{ memory: string; metadata?: Record<string, unknown> }>`) for traversing, filtering, or selectively including results based on metadata
 
 ### XML-Based Prompting for Claude
 
@@ -179,6 +180,31 @@ const model = withSupermemory(anthropic("claude-3-sonnet"), "user-123", {
 })
 ```
 
+### Filtering Search Results
+
+Use `searchResults` to traverse the raw data and pick what's important:
+
+```typescript
+const selectivePrompt = (data: MemoryPromptData) => {
+  const relevant = data.searchResults.filter(
+    (r) => (r.metadata?.score as number) > 0.7
+  )
+  return `
+<user_memories>
+${data.userMemories}
+</user_memories>
+<relevant_context>
+${relevant.map((r) => `- ${r.memory}`).join("\n")}
+</relevant_context>
+`.trim()
+}
+
+const model = withSupermemory(openai("gpt-4"), "user-123", {
+  mode: "full",
+  promptTemplate: selectivePrompt
+})
+```
+
 ### Custom Branding
 
 Remove "supermemories" references and use your own branding:

apps/docs/integrations/ai-sdk.mdx

@@ -75,7 +75,7 @@ const model = withSupermemory(openai("gpt-4"), "user-123", { mode: "full" })
 
 ### Custom Prompt Templates
 
-Customize how memories are formatted:
+Customize how memories are formatted. The template receives `userMemories`, `generalSearchMemories`, and `searchResults` (raw array for filtering by metadata):
 
 ```typescript
 import { withSupermemory, type MemoryPromptData } from "@supermemory/tools/ai-sdk"

apps/docs/integrations/mastra.mdx

@@ -162,7 +162,7 @@ await agent.generate("My favorite framework is Next.js")
 
 ## Custom Prompt Templates
 
-Customize how memories are formatted and injected:
+Customize how memories are formatted and injected. The template receives `userMemories`, `generalSearchMemories`, and `searchResults` (raw array for filtering by metadata):
 
 ```typescript
 import { Agent } from "@mastra/core/agent"

packages/tools/README.md

@@ -253,6 +253,7 @@ const result = await generateText({
 The `MemoryPromptData` object provides:
 - `userMemories`: Pre-formatted markdown combining static profile facts (name, preferences, goals) and dynamic context (current projects, recent interests)
 - `generalSearchMemories`: Pre-formatted search results based on semantic similarity to the current query
+- `searchResults`: Raw search results array for traversing, filtering, or selectively including results based on metadata
 
 ### OpenAI SDK Usage
 

packages/tools/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@supermemory/tools",
   "type": "module",
-  "version": "1.4.00",
+  "version": "1.4.01",
   "description": "Memory tools for AI SDK and OpenAI function calling with supermemory",
   "scripts": {
     "build": "tsdown",

packages/tools/src/shared/memory-client.ts

@@ -154,6 +154,7 @@ export const buildMemoriesText = async (
 	const promptData: MemoryPromptData = {
 		userMemories,
 		generalSearchMemories,
+		searchResults: memoriesResponse.searchResults?.results ?? [],
 	}
 
 	const memories = promptTemplate(promptData)

packages/tools/src/shared/types.ts

@@ -13,6 +13,12 @@ export interface MemoryPromptData {
 	 * Empty string if mode is "profile" only.
 	 */
 	generalSearchMemories: string
+	/**
+	 * Raw search results from the API for the current query.
+	 * Use this to traverse, filter, or selectively include results based on metadata.
+	 * Empty array if mode is "profile" or when no search was performed.
+	 */
+	searchResults: Array<{ memory: string; metadata?: Record<string, unknown> }>
 }
 
 /**
@@ -28,6 +34,7 @@ export interface MemoryPromptData {
  * ${data.generalSearchMemories}
  * </user_memories>
  * `.trim()
+ * // data.searchResults provides raw results for custom filtering/formatting
  * ```
  */
 export type PromptTemplate = (data: MemoryPromptData) => string

packages/tools/src/vercel/memory-prompt.ts

@@ -8,7 +8,7 @@ export {
 	type BuildMemoriesTextOptions,
 } from "../shared"
 
-import type { Logger } from "../shared"
+import type { Logger, MemoryPromptData } from "../shared"
 import type { LanguageModelCallOptions } from "./util"
 
 /**
@@ -100,10 +100,7 @@ export const addSystemPrompt = async (
 	mode: "profile" | "query" | "full",
 	baseUrl: string,
 	apiKey: string,
-	promptTemplate?: (data: {
-		userMemories: string
-		generalSearchMemories: string
-	}) => string,
+	promptTemplate?: (data: MemoryPromptData) => string,
 ): Promise<LanguageModelCallOptions> => {
 	const { buildMemoriesText } = await import("../shared")