8.2 · TypeScript/JavaScript SDK

TypeScript/JavaScript SDK

TypeScript/JavaScript SDK

相关源文件

本章引用的主要源码文件：

• docs/components/vectordbs/dbs/vectorize.mdx
• docs/open-source/multimodal-support.mdx
• mem0-ts/package.json
• mem0-ts/pnpm-lock.yaml
• mem0-ts/src/client/index.ts
• mem0-ts/src/client/mem0.ts
• mem0-ts/src/client/mem0.types.ts
• mem0-ts/src/client/telemetry.ts
• mem0-ts/src/client/tests/memoryClient.webhooks.test.ts
• mem0-ts/src/oss/package.json
• mem0-ts/src/oss/src/config/defaults.ts
• mem0-ts/src/oss/src/config/manager.ts
• mem0-ts/src/oss/src/index.ts
• mem0-ts/src/oss/src/llms/anthropic.ts
• mem0-ts/src/oss/src/llms/deepseek.ts
• mem0-ts/src/oss/src/llms/groq.ts
• mem0-ts/src/oss/src/llms/openai.ts
• mem0-ts/src/oss/src/llms/openai_structured.ts
• mem0-ts/src/oss/src/memory/index.ts
• mem0-ts/src/oss/src/storage/SQLiteManager.ts
• mem0-ts/src/oss/src/tests/better-sqlite3-migration.test.ts
• mem0-ts/src/oss/src/tests/sqlite-backward-compat.test.ts
• mem0-ts/src/oss/src/types/index.ts
• mem0-ts/src/oss/src/utils/entity_extraction.ts
• mem0-ts/src/oss/src/utils/factory.ts
• mem0-ts/src/oss/src/vector_stores/memory.ts
• mem0-ts/src/oss/src/vector_stores/redis.ts
• mem0-ts/src/oss/tests/deepseek.test.ts
• mem0-ts/src/oss/tests/factory.unit.test.ts
• mem0-ts/src/oss/tests/openai-llm.test.ts
• mem0-ts/src/oss/tests/openai-structured-llm.test.ts
• mem0-ts/src/oss/tests/vector-store.unit.test.ts
• mem0-ts/src/oss/tests/vector-stores-compat.test.ts

TypeScript/JavaScript SDK（mem0ai 包）提供两种不同的部署模式：

1. 平台模式（MemoryClient）：用于托管在 api.mem0.ai 的 Mem0 平台 API 的客户端，提供托管内存存储，支持自动扩缩容、Webhook 和分析功能。
2. 开源模式（Memory）：自托管内存系统，支持可配置的大语言模型（LLM）、嵌入向量生成器、向量存储和历史记录存储提供者。

本文档记录了平台模式客户端和底层的开源模式架构。

相关文档：

• Python SDK（平台）：#8.1
• Vercel AI SDK 提供者：#8.3
• 开源内存系统：#3.1
• 平台 API 参考：#7.2

安装与设置

包安装

SDK 以 mem0ai npm 包形式发布，同时支持 CommonJS 和 ESM：

npm install mem0ai
# 或
yarn add mem0ai
# 或
pnpm add mem0ai

包元数据：

来源：mem0-ts/package.json:1-29, mem0-ts/package.json:129-131

基本初始化

MemoryClient 类是平台 API 交互的主要接口：

import MemoryClient from 'mem0ai';

const client = new MemoryClient({
  apiKey: 'your-api-key',
  host: 'https://api.mem0.ai' // 可选
});

初始化流程： 构造函数会自动执行以下步骤：

1. 通过 _validateApiKey() 校验 API 密钥格式 mem0-ts/src/client/mem0.ts:90-100。
2. 创建一个超时时间为 60 秒的 Axios 实例 mem0-ts/src/client/mem0.ts:113-117。
3. 调用 _initializeClient() 通过 ping() 验证密钥并生成遥测 ID mem0-ts/src/client/mem0.ts:124-146。

来源：mem0-ts/src/client/mem0.ts:81-122

SDK 架构

双导出系统

该包使用双入口点系统来分离平台客户端和开源（OSS）逻辑。

来源：mem0-ts/package.json:18-29, mem0-ts/src/oss/src/index.ts:1-30

开源工厂模式

在开源模式下，Memory 类使用工厂模式根据 MemoryConfig 实例化提供者。

来源：mem0-ts/src/oss/src/utils/factory.ts:40-136, mem0-ts/src/oss/src/memory/index.ts:153-189

内存操作（平台）

添加记忆

add() 方法将消息发送到平台进行事实提取和存储。

async add(
    messages: Array<Message>,
    options: AddMemoryOptions = {}
): Promise<Array<Memory>>

实现细节：

• 验证没有顶级实体参数（如 user_id、agent_id）被传递到 options 对象之外 mem0-ts/src/client/mem0.ts:54-67。
• 使用 camelToSnakeKeys 准备载荷以匹配 API 要求 mem0-ts/src/client/mem0.ts:199-206。
• 向记忆端点发送 POST 请求 mem0-ts/src/client/mem0.ts:251-260。

来源：mem0-ts/src/client/mem0.ts:251-275, mem0-ts/src/client/mem0.types.ts:10-17

搜索记忆

对存储的记忆执行语义搜索。

async search(query: string, options: SearchMemoryOptions = {}): Promise<any>

搜索逻辑：

• 路由到平台搜索端点 mem0-ts/src/client/mem0.ts:430-440。
• 支持 threshold（0-1）、topK 和 rerank 参数 mem0-ts/src/client/mem0.types.ts:19-27。

来源：mem0-ts/src/client/mem0.ts:413-443

开源存储后端

开源模式支持多种向量存储和历史记录管理器。

向量存储提供者

支持的提供者包括 memory（基于 SQLite）、qdrant、redis、supabase、vectorize、azure-ai-search 和 pgvector mem0-ts/src/oss/src/utils/factory.ts:94-117。

示例：Memory（SQLite）实现 MemoryVectorStore 使用 better-sqlite3 提供本地持久化存储：

• 通过 getDefaultVectorStoreDbPath() 自动确定数据库路径 mem0-ts/src/oss/src/vector_stores/memory.ts:42。
• 在 TypeScript 中实现 cosineSimilarity 用于本地搜索 mem0-ts/src/oss/src/vector_stores/memory.ts:76-86。
• 支持高级元数据过滤，包括逻辑运算符（AND、OR、NOT）和比较运算符（eq、gt、contains 等）mem0-ts/src/oss/src/vector_stores/memory.ts:160-221。

来源：mem0-ts/src/oss/src/vector_stores/memory.ts:17-221

示例：Redis 实现 RedisDB 类使用 RediSearch 进行向量索引：

• 转义 TAG 过滤器中的特殊字符（如 UUID 中的 -），以防止 RediSearch 查询中的语法错误 mem0-ts/src/oss/src/vector_stores/redis.ts:18-23。
• 定义包含 user_id、agent_id 和 run_id 的 TAG 字段的模式 mem0-ts/src/oss/src/vector_stores/redis.ts:92-112。
• 使用 FLAT 算法进行余弦相似度计算 mem0-ts/src/oss/src/vector_stores/redis.ts:219-225。

来源：mem0-ts/src/oss/src/vector_stores/redis.ts:148-254

遥测

SDK 包含一个遥测系统，用于跟踪客户端使用情况和错误，可以通过 MEM0_TELEMETRY 环境变量禁用它。

遥测流程：

1. 客户端方法调用 captureClientEvent mem0-ts/src/client/mem0.ts:172-180。
2. UnifiedTelemetry 通过 MEM0_TELEMETRY 检查遥测是否启用 mem0-ts/src/client/telemetry.ts:11-14。
3. 事件被发送到 PostHog（us.i.posthog.com），包含客户端版本和方法元数据 mem0-ts/src/client/telemetry.ts:35-75。

来源：mem0-ts/src/client/telemetry.ts:1-151

类型定义

核心接口

来源：mem0-ts/src/client/mem0.types.ts:1-217, mem0-ts/src/oss/src/types/index.ts:54-145