mem0/skills/mem0-vercel-ai-sdk/references/memory-utilities.md

Memory Utilities Reference

Complete reference for standalone utility functions exported from @mem0/vercel-ai-provider. These functions give you manual control over memory retrieval and storage, independent of the wrapped model pattern.

Source: integrations/vercel-ai-sdk/src/mem0-utils.ts

addMemories(messages, config?)

Stores messages to Mem0 as new memories.

import { addMemories } from "@mem0/vercel-ai-provider";

await addMemories(
  [
    { role: "user", content: [{ type: "text", text: "I love Italian food" }] },
    { role: "assistant", content: [{ type: "text", text: "Noted! I'll remember that." }] },
  ],
  { user_id: "alice", mem0ApiKey: "m0-xxx" }
);

Signature:

async function addMemories(
  messages: LanguageModelV3Prompt,
  config?: Mem0ConfigSettings
): Promise<any>;

Parameters:

Parameter	Type	Description
messages	LanguageModelV3Prompt	Messages to store. A plain string is also handled at runtime (wrapped as [{ role: "user", content: string }]) but is not part of the declared type
config	Mem0ConfigSettings	Optional. Must include entity scope (user_id, etc.) and API key

Behavior:

1. If messages is a string, wraps it as a single user message
2. Otherwise, converts LanguageModelV3Prompt to Mem0 format via convertToMem0Format (maps multimodal parts, but the add endpoint rejects them with a 400)
3. Calls POST {host}/v3/memories/add/ with body { messages, user_id?, app_id?, agent_id?, run_id?, metadata?, infer? } (entity IDs are top-level on add)
4. Throws HTTP error! status: <code> on a non-2xx response

Returns: The parsed JSON response from Mem0. The v3 add endpoint queues extraction and responds with { status: "PENDING", event_id } (the provider returns the raw REST JSON, so keys stay snake_case, unlike the mem0ai client). With infer: false messages are stored verbatim synchronously and the response also includes results.

---

retrieveMemories(prompt, config?)

Retrieves memories and returns a formatted system prompt string ready to inject into a system parameter.

import { retrieveMemories } from "@mem0/vercel-ai-provider";

const systemPrompt = await retrieveMemories("What restaurants do I like?", {
  user_id: "alice",
  mem0ApiKey: "m0-xxx",
});
// Returns: "System Message: These are the memories I have stored... Memory: User loves Italian food\n\n ..."

Signature:

async function retrieveMemories(
  prompt: LanguageModelV3Prompt | string,
  config?: Mem0ConfigSettings
): Promise<string>;

Parameters:

Parameter	Type	Description
prompt	LanguageModelV3Prompt | string	The query to search memories for
config	Mem0ConfigSettings	Optional. Entity scope and API key

Behavior:

1. Flattens the prompt to a plain string (extracts text from LanguageModelV3Prompt parts)
2. Calls searchInternalMemories (POST /v3/memories/search/)
3. Accepts either a flat array or a { results: [...] } response and formats each memory as "Memory: {memory.memory}\n\n"
4. Wraps everything in a system prompt preamble

Returns: A string containing the formatted system prompt with embedded memories. Returns "" (empty string) if no memories found.

Output format:

System Message: These are the memories I have stored. Give more weightage to the question by users and try to answer that first. You have to modify your answer based on the memories I have provided. If the memories are irrelevant you can ignore them. Also don't reply to this section of the prompt, or the memories, they are only for your reference. The System prompt starts after text System Message:

Memory: User loves Italian food

Memory: User is vegetarian

---

getMemories(prompt, config?)

Retrieves memories and returns the raw memory array.

import { getMemories } from "@mem0/vercel-ai-provider";

const memories = await getMemories("What are my preferences?", {
  user_id: "alice",
  mem0ApiKey: "m0-xxx",
});
// Returns: [{ memory: "User loves Italian food", id: "...", ... }, ...]

Signature:

async function getMemories(
  prompt: LanguageModelV3Prompt | string,
  config?: Mem0ConfigSettings
): Promise<any>;

Parameters:

Parameter	Type	Description
prompt	LanguageModelV3Prompt | string	The query to search memories for
config	Mem0ConfigSettings	Optional. Entity scope and API key

Behavior:

1. Flattens the prompt to a plain string
2. Calls searchInternalMemories (POST /v3/memories/search/)
3. Normalizes the response: returns the response itself if it is an array, otherwise response.results (or [])

Returns: Flat memory object array.

---

searchMemories(prompt, config?)

Retrieves the raw search API response including results, scores, and metadata.

import { searchMemories } from "@mem0/vercel-ai-provider";

const response = await searchMemories("cooking preferences", {
  user_id: "alice",
  mem0ApiKey: "m0-xxx",
});
// Returns: { results: [{ memory: "...", score: 0.95, ... }] }

Signature:

async function searchMemories(
  prompt: LanguageModelV3Prompt | string,
  config?: Mem0ConfigSettings
): Promise<any>;

Parameters:

Parameter	Type	Description
prompt	LanguageModelV3Prompt | string	The query to search memories for
config	Mem0ConfigSettings	Optional. Entity scope and API key

Behavior:

1. Flattens the prompt to a plain string
2. Calls searchInternalMemories (POST /v3/memories/search/)
3. Returns the response without any normalization

Returns: The API response as-is (an object with results, or a flat array if the API returns one). On error, logs and returns [] instead of throwing (unlike the other utilities, which rethrow).

Note: Unlike getMemories, this does not unwrap results.

---

When to Use Which Function

Function	Returns	Use when
retrieveMemories	Formatted system prompt string	Injecting directly into a system parameter for generateText/streamText
getMemories	Memory array	Processing memories programmatically (filtering, transforming, counting)
searchMemories	Raw API response	Need similarity scores or complete metadata
addMemories	API response	Storing new conversation messages as memories

Internal: searchInternalMemories(query, config?, top_k?)

Not exported. Used by all retrieval functions.

async function searchInternalMemories(
  query: string,
  config?: Mem0ConfigSettings,
  top_k: number = 10
): Promise<any>;

Behavior:

1. Builds a filters object from config.filters, then sets user_id, app_id, agent_id, run_id on it when present (entity IDs go inside filters, never top-level)
2. Loads the API key from config.mem0ApiKey or MEM0_API_KEY env var
3. Calls POST {host}/v3/memories/search/ with:
   • query: the search string
   • filters: the filter object with entity identifiers
   • top_k: config.top_k or default 10 (an explicit 0 is respected)
   • threshold, rerank, metadata: only when set in config
   • No other config fields (infer, page, page_size, host, mem0ApiKey) are sent
4. Sends Authorization: Token <key> plus X-Mem0-Source: VERCEL_AI_SDK and X-Mem0-Client: mem0-vercel-ai-provider/<version> headers
5. Throws HTTP error! status: <code> on a non-2xx response

Default host: https://api.mem0.ai

Internal: convertToMem0Format(messages)

Not exported. Used by addMemories to convert LanguageModelV3Prompt messages to Mem0's format.

Multimodal content mapping:

Input type	Input format	Output type	Output format
Text	{ type: "text", text: "..." }	Plain string	{ role, content: "..." }
Image	{ type: "image_url", image_url: { url } } or { type: "image", ... }	Image URL	{ role, content: { type: "image_url", image_url: { url } } }
PDF file	{ type: "file", data: url, mediaType: "application/pdf" }	PDF URL	{ role, content: { type: "pdf_url", pdf_url: { url } } }
Markdown file	{ type: "file", data: url, mediaType: "text/markdown" } or "application/mdx"	MDX URL	{ role, content: { type: "mdx_url", mdx_url: { url } } }
Image file	{ type: "file", data: url, mediaType: "image/*" }	Image URL	{ role, content: { type: "image_url", image_url: { url } } }
MDX content	{ type: "mdx_url", mdx_url: { url } } or { type: "mdx", ... }	MDX URL	{ role, content: { type: "mdx_url", mdx_url: { url } } }
PDF content	{ type: "pdf_url", pdf_url: { url } } or { type: "pdf", ... }	PDF URL	{ role, content: { type: "pdf_url", pdf_url: { url } } }

/v3/memories/add/ rejects structured (non-string) content with a 400 Not a valid string. (live-tested on the Python SDK with infer true and false), so a prompt containing these parts is expected to fail with HTTP error! status: 400 (checked against the endpoint, not through the provider). Only text parts are storable.

The function handles three message content shapes:

1. String content: passed through directly
2. Array content: each element mapped individually, nulls filtered out
3. Single object content: mapped as a single element

Internal: flattenPrompt(prompt)

Not exported. Extracts plain text from LanguageModelV3Prompt for use as a search query.

• Iterates over prompt parts, extracting text from user role messages
• For text type content: extracts .text
• For file type content: returns descriptive placeholders ([PDF document], [Markdown document], [Image], [File attachment])
• For other content types: returns [multimodal content]
• Joins all parts with spaces

Mem0ConfigSettings Fields Reference

All fields are optional. Used across all utility functions.

Field	Type	Default	Description
user_id	string	--	Scope memories to a user
app_id	string	--	Scope memories to an application
agent_id	string	--	Scope memories to an agent
run_id	string	--	Scope memories to a session/run
metadata	Record<string, any>	--	Custom metadata
filters	Record<string, any>	--	Custom search filters (entity IDs above are merged in and win on conflicts)
infer	boolean	--	Sent on add only. false stores messages verbatim without extraction
page	number	--	Declared in the type, not sent by the provider
page_size	number	--	Declared in the type, not sent by the provider
mem0ApiKey	string	MEM0_API_KEY env	Mem0 API key
top_k	number	10	Number of memories to retrieve
threshold	number	--	Server-side relevance cutoff, not a floor on the returned score; sent only when set
rerank	boolean	-- (API default false)	Enable re-ranking, sent only when set
host	string	https://api.mem0.ai	Custom API host