docs(skills): refresh mem0 skills against SDK 2.2.1 / TS 3.3.1 (#7548)

2026-10-07 18:36:15 +05:30
parent d62ce07fac
commit b7ad69afda
33 changed files with 1239 additions and 814 deletions
@@ -25,26 +25,26 @@ When called with no arguments, defaults to `{ provider: "openai" }`.

 ## `Mem0Provider` Interface

-Implements `ProviderV2` from `@ai-sdk/provider`.
+Implements `ProviderV3` from `@ai-sdk/provider` (`specificationVersion: "v3"`, AI SDK v6).

 ```typescript
-interface Mem0Provider extends ProviderV2 {
+interface Mem0Provider extends ProviderV3 {
  // Call directly as a function
-  (modelId: Mem0ChatModelId, settings?: Mem0ChatSettings): LanguageModelV2;
+  (modelId: Mem0ChatModelId, settings?: Mem0ChatSettings): LanguageModelV3;

  // Or use named methods
-  chat(modelId: Mem0ChatModelId, settings?: Mem0ChatSettings): LanguageModelV2;
-  completion(modelId: Mem0ChatModelId, settings?: Mem0ChatSettings): LanguageModelV2;
-  languageModel(modelId: Mem0ChatModelId, settings?: Mem0ChatSettings): LanguageModelV2;
+  chat(modelId: Mem0ChatModelId, settings?: Mem0ChatSettings): LanguageModelV3;
+  completion(modelId: Mem0ChatModelId, settings?: Mem0ChatSettings): LanguageModelV3;
+  languageModel(modelId: Mem0ChatModelId, settings?: Mem0ChatSettings): LanguageModelV3;
 }
 ```

 - **Direct call** (`mem0("gpt-5-mini", {...})`): creates a generic language model (neither chat nor completion mode forced).
- **`chat()`**: creates a model with `modelType: "chat"` (note: in the current source, the chat constructor sets `modelType: "completion"` -- this appears to be a bug; functionally equivalent to `completion()` at present).
+- **`chat()`**: creates a model with `modelType: "chat"`.
 - **`completion()`**: creates a model with `modelType: "completion"`.
 - **`languageModel()`**: alias for the generic model (same as direct call).

-All three return a `Mem0GenericLanguageModel` instance implementing `LanguageModelV2`.
+All three return a `Mem0GenericLanguageModel` instance implementing `LanguageModelV3`.

 ## `Mem0ProviderSettings` Interface

@@ -52,14 +52,14 @@ Configuration passed to `createMem0()`.

 ```typescript
 interface Mem0ProviderSettings {
-  baseURL?: string;            // Base URL for the LLM provider (default: "http://api.openai.com")
-  headers?: Record<string, string>;  // Custom headers for LLM requests
+  baseURL?: string;            // Stored on the model config (default: "https://api.openai.com"), not applied to upstream LLM requests
+  headers?: Record<string, string | undefined>;  // Stored on the model config, not applied to upstream LLM requests
  provider?: string;           // LLM provider name (default: "openai")
  mem0ApiKey?: string;         // Mem0 Platform API key (or use MEM0_API_KEY env var)
  apiKey?: string;             // LLM provider API key (e.g., OpenAI key)
  mem0Config?: Mem0Config;     // Default Mem0 config (user_id, etc.) applied to all calls
  config?: LLMProviderSettings; // Provider-specific settings (OpenAI, Anthropic, etc.)
-  fetch?: typeof fetch;        // Custom fetch implementation (for testing/middleware)
+  fetch?: typeof fetch;        // Stored on the model config, not used by the upstream LLM client or Mem0 API calls
  generateId?: () => string;   // Custom ID generator (internal use)
  name?: string;               // Provider instance name
  modelType?: "completion" | "chat";  // Force model type
@@ -75,7 +75,7 @@ interface Mem0ProviderSettings {
 | `apiKey` | LLM provider API key | `"sk-xxx"` (OpenAI), `"sk-ant-xxx"` (Anthropic) |
 | `mem0Config` | Default Mem0 settings for all calls | `{ user_id: "alice" }` |
 | `config` | Provider-specific SDK settings | `{ organization: "org-xxx" }` for OpenAI |
-| `baseURL` | Override LLM provider base URL | `"https://my-proxy.example.com"` |
+| `config.baseURL` | Override LLM provider base URL (put it inside `config`; the top-level `baseURL` does not reach the upstream client) | `{ baseURL: "https://my-proxy.example.com/v1" }` |

 ## `mem0` Singleton

@@ -94,7 +94,7 @@ Equivalent to `createMem0()` with no arguments.

 ## `Mem0ConfigSettings` Interface

-Configuration for memory operations. Used as `Mem0ChatSettings` (per-call) or `Mem0Config` (provider-level default). All fields are optional.
+Configuration for memory operations. Used as `Mem0ChatSettings` (per-call) or `Mem0Config` (provider-level default; same shape, not exported from the package entry point). All fields are optional.

 ```typescript
 interface Mem0ConfigSettings {
@@ -104,13 +104,13 @@ interface Mem0ConfigSettings {
  run_id?: string;               // Scope memories to a specific run/session
  metadata?: Record<string, any>; // Custom metadata attached to memories
  filters?: Record<string, any>; // Custom filters for memory search
-  infer?: boolean;               // Enable inference during memory operations
-  page?: number;                 // Pagination: page number
-  page_size?: number;            // Pagination: results per page
+  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 (overrides provider-level key)
-  top_k?: number;                // Number of memories to retrieve (default: 5)
-  threshold?: number;            // Minimum similarity score for retrieval (default: 0.1)
-  rerank?: boolean;              // Enable re-ranking of search results (default: false)
+  top_k?: number;                // Number of memories to retrieve (default: 10)
+  threshold?: number;            // Server-side relevance cutoff; sent only when set
+  rerank?: boolean;              // Enable re-ranking of search results; sent only when set (API default: false)
  host?: string;                 // Custom Mem0 API host (default: "https://api.mem0.ai")
 }
 ```
@@ -137,17 +137,18 @@ mem0("gpt-5-mini", { user_id: "alice" })

 ## `LLMProviderSettings` Type

-Union of provider-specific settings. Extends all supported provider setting interfaces:
+Union of provider-specific settings for all supported provider SDKs:

 ```typescript
-interface LLMProviderSettings extends
-  OpenAIProviderSettings,
-  AnthropicProviderSettings,
-  CohereProviderSettings,
-  GroqProviderSettings {}
+type LLMProviderSettings =
+  | OpenAIProviderSettings
+  | AnthropicProviderSettings
+  | CohereProviderSettings
+  | GroqProviderSettings
+  | GoogleGenerativeAIProviderSettings;
 ```

-Pass via the `config` field of `Mem0ProviderSettings` to forward settings to the underlying LLM provider SDK.
+Pass via the `config` field of `Mem0ProviderSettings` to forward settings (e.g., `baseURL`, `headers`, `apiKey`) to the underlying LLM provider SDK. `config` is spread after `apiKey`, so a `config.apiKey` takes precedence.

 ## Provider Selection: `Mem0ClassSelector`

@@ -155,12 +156,12 @@ Internal class that maps the `provider` string to the correct AI SDK provider.

 ```typescript
 class Mem0ClassSelector {
-  static supportedProviders = ["openai", "anthropic", "cohere", "groq", "google"];
+  static supportedProviders = ["openai", "anthropic", "cohere", "groq", "google", "gemini"];
  // ...
 }
 ```

-**Important:** The `"gemini"` alias exists in the provider switch statement (maps to `createGoogleGenerativeAI`) but is **NOT** in the `supportedProviders` list. The constructor validates against `supportedProviders`, so using `"gemini"` will throw `"Model not supported: gemini"`. Use `"google"` instead.
+`"gemini"` is an alias of `"google"` (both map to `createGoogleGenerativeAI`). Any other value throws `"Model not supported: <value>"`.

 ### Provider mapping

@@ -170,7 +171,7 @@ class Mem0ClassSelector {
 | `"anthropic"` | `@ai-sdk/anthropic` | `createAnthropic` |
 | `"cohere"` | `@ai-sdk/cohere` | `createCohere` |
 | `"groq"` | `@ai-sdk/groq` | `createGroq` |
-| `"google"` | `@ai-sdk/google` | `createGoogleGenerativeAI` |
+| `"google"` or `"gemini"` | `@ai-sdk/google` | `createGoogleGenerativeAI` |

 ## `Mem0` Facade Class

@@ -184,7 +185,7 @@ const chatModel = mem0.chat("gpt-5-mini", { user_id: "alice" });
 const completionModel = mem0.completion("gpt-5-mini");
 ```

-The facade defaults its base URL to `"http://127.0.0.1:11434/api"` (Ollama-style) rather than `"http://api.openai.com"`. It always uses `"openai"` as the provider for created models.
+The facade defaults its base URL to `"https://api.openai.com"`. It always uses `"openai"` as the provider for created models, and only stores `baseURL` and `headers` from its options: the `provider`, `mem0ApiKey`, and `apiKey` options are ignored, so `MEM0_API_KEY` and `OPENAI_API_KEY` must come from the environment. Prefer `createMem0` for anything beyond a quick start.

 **Methods:**
 - `chat(modelId, settings?)` -- creates a model with `modelType: "chat"`
@@ -192,13 +193,11 @@ The facade defaults its base URL to `"http://127.0.0.1:11434/api"` (Ollama-style

 ## `Mem0GenericLanguageModel` Class

-The core class implementing `LanguageModelV2`. Created by `createMem0` or the `Mem0` facade.
+The core class implementing `LanguageModelV3`. Created by `createMem0` or the `Mem0` facade.

 ```typescript
-class Mem0GenericLanguageModel implements LanguageModelV2 {
-  readonly specificationVersion = "v2";
-  readonly defaultObjectGenerationMode = "json";
-  readonly supportsImageUrls = false;
+class Mem0GenericLanguageModel implements LanguageModelV3 {
+  readonly specificationVersion = "v3";
  readonly supportedUrls: Record<string, RegExp[]> = { '*': [/.*/] };

  provider: string;   // e.g., "openai"
@@ -206,22 +205,26 @@ class Mem0GenericLanguageModel implements LanguageModelV2 {
  settings: Mem0ChatSettings;
  config: Mem0ChatConfig;

-  async doGenerate(options: LanguageModelV2CallOptions): Promise<...>;
-  async doStream(options: LanguageModelV2CallOptions): Promise<...>;
+  async doGenerate(options: LanguageModelV3CallOptions): Promise<...>;
+  async doStream(options: LanguageModelV3CallOptions): Promise<...>;
 }
 ```

+`defaultObjectGenerationMode` and `supportsImageUrls` (V2 properties) no longer exist.
+
 Both `doGenerate` and `doStream` follow the same internal flow:

-1. Build `Mem0ConfigSettings` from `config.mem0Config` merged with `settings`
+1. Build `Mem0ConfigSettings` from `config.mem0ApiKey`, then `config.mem0Config`, then `settings` (later entries win)
 2. Call `processMemories`:
-   - Fire `addMemories` as fire-and-forget (no await, `.then().catch()`)
-   - Await `getMemories` to retrieve relevant memories
-   - Format memories as a system message and prepend to the prompt
+   - Await `addMemories` (errors are logged and ignored)
+   - Await `getMemories` to retrieve relevant memories (on failure, continue with no memories)
+   - If any memories were found, format them as a system message and prepend it to a copy of the prompt
 3. Create the underlying LLM model via `Mem0ClassSelector`
 4. Delegate to the underlying model's `doGenerate` or `doStream`
 5. Return the result

+`doGenerate` additionally appends a `source` content part (`title: "Mem0 Memories"`) with `providerMetadata.mem0.memories` and `providerMetadata.mem0.memoriesText` when memories were retrieved. `doStream` returns the underlying stream result unchanged (no Mem0 source) and throws `"Streaming failed or method not implemented."` if streaming setup fails.
+
 **Note:** Entity identifier fields use snake_case (`user_id`, `app_id`, `agent_id`, `run_id`) to match the Mem0 API.

 ## Type: `Mem0ChatModelId`
@@ -230,4 +233,4 @@ Both `doGenerate` and `doStream` follow the same internal flow:
 type Mem0ChatModelId = string & NonNullable<unknown>;
 ```

-Any non-null string. The model ID is passed through to the underlying provider (e.g., `"gpt-5-mini"`, `"gemini-pro"`).
+Any non-null string. The model ID is passed through to the underlying provider (e.g., `"gpt-5-mini"`, `"gemini-2.5-flash"`).