mem0 TypeScript SDK 开发指南：mem0-ts 包的构建、测试、目录结构与发布流程全解析

本文以 mem0 仓库中 TypeScript SDK 模块（mem0-ts/）的开发者指南为核心，完整覆盖 npm 包 mem0ai 的构建与测试命令、工程约定、源码目录布局、公开 API 表面以及基于 Git Tag 的发布机制。读完本文后，你将掌握如何在本地以 pnpm 驱动完成 mem0-ts 的构建、类型检查与单元/集成测试，理解 hosted 客户端 MemoryClient 与自托管 OSS 内存 Memory 两条导出的组织方式，并了解从打 Tag 到发布 npm 的完整链路。

一、mem0-ts 包的定位：一个包，两种内存形态

mem0-ts/ 目录对应 npm 上的 mem0ai 包（当前仓库中版本为 3.1.7），其定位在 mem0-ts/AGENTS.md 开篇即被明确定义：hosted client plus self-hosted OSS memory——同一个包内同时提供托管平台客户端与自托管开源（OSS）内存两种形态。

从 mem0-ts/package.json 的 exports 字段可以确认这一"双入口"设计在包层面的落地方式：

"exports": {
  ".": {
    "types": "./dist/index.d.ts",
    "require": "./dist/index.js",
    "import": "./dist/index.mjs"
  },
  "./oss": {
    "types": "./dist/oss/index.d.ts",
    "require": "./dist/oss/index.js",
    "import": "./dist/oss/index.mjs"
  }
}

也就是说，使用者根据部署形态选择不同的导入路径：托管平台走 mem0ai 主入口，自托管走 mem0ai/oss 子路径。typesVersions 字段同时为 TypeScript 声明文件做了相同的子路径映射，保证两种形态都能获得完整的类型支持。

二、命令体系：pnpm 驱动的开发工作流

mem0-ts/AGENTS.md 给出的标准命令集如下，且明确要求只使用 pnpm，绝不用 npm 或 yarn：

pnpm install
pnpm run build              # tsup (CJS + ESM)
pnpm run test               # jest, all tests
pnpm run test:unit          # jest --coverage
pnpm run test:integration   # jest, needs MEM0_API_KEY
pnpm run test:ci            # jest --coverage --ci
pnpm run test:watch
pnpm run typecheck          # tsc --noEmit

对照 mem0-ts/package.json 中的 scripts 字段，可以补充几条文档未展开但影响实操的细节：

• build 实际上是三段式流程：rimraf dist 清理 → prettier --check . 格式校验 → npx tsup 构建。这意味着构建失败可能不是编译错误，而是 Prettier 格式检查不通过，可用 pnpm run format 先修复格式；
• test:unit 在 jest --coverage 基础上排除了 integration 路径，即单元测试不需要外部服务；
• test:integration 使用独立的 jest.integration.config.js，并带 --forceExit；按文档说明，它依赖环境变量 MEM0_API_KEY，即集成测试会访问真实的托管平台 API；
• 文档要求每次改动后都运行 pnpm run typecheck（对应 tsc --noEmit），这与 mem0-ts/tsconfig.json 中 "strict": true 的配置相互呼应——整个 SDK 在 TypeScript 严格模式下开发。

从 tsconfig.json 还能看到编译目标为 ES2018、模块体系为 ESNext、esModuleInterop 开启，这与文档中"仅允许 ES module import 语法、禁止 require()"的约定一致。

三、工程约定：构建、格式化与测试的边界

mem0-ts/AGENTS.md 的 Conventions 一节定义了 mem0-ts 的工程规范，逐条说明如下：

1. Node 版本：CI 实际测试的版本是 Node 20 和 Node 22。注意 package.json 中 engines 声明为 node >= 18，即 18 及以上可安装，但只有 20/22 是经过 CI 验证的承诺版本；
2. 构建：使用 tsup 输出双格式（CJS + ESM）。mem0-ts/package.json 中的 tsup 配置块显示入口为 src/index.ts，格式为 cjs + esm，开启 dts 声明解析、sourcemap 与 tree-shake，并且将 @mem0/community 标记为 external；
3. 格式化：仅配置了 Prettier，本模块没有 linter。文档特别警告：不要假设仓库共享同一套代码检查配置——cli/node/ 使用 Biome，integrations/vercel-ai-sdk/ 使用 ESLint，三者互不通用；
4. 测试：mem0-ts 使用 jest；而 cli/node/ 与 integrations/openclaw/ 使用的是 vitest。跨模块工作时必须按各自目录的实际配置执行；
5. 命名约定：源码文件采用 snake_case.ts（如 mem0.ts、aws_bedrock.py 风格的 aws_bedrock.ts），测试文件统一为 <module>.test.ts；
6. 模块语法：仅允许 ES module import 语法，绝不使用 require()。

这些约定共同决定了 mem0-ts 的 CI 行为与贡献者工作流：改动后依次执行 pnpm run typecheck、pnpm run test:unit，再执行 pnpm run build（内含格式校验）。

四、源码布局：client 与 oss 的双层结构

文档给出的目录骨架为：

mem0-ts/src/
├── client/          MemoryClient (hosted platform)
└── oss/             Memory (self-hosted)
    ├── llms/
    ├── embeddings/
    ├── vector_stores/
    └── graphs/

结合仓库实际结构，可以更完整地描述为：

• mem0-ts/src/client/：托管平台客户端，包含 mem0.ts（MemoryClient 主实现）、mem0.types.ts（全部公共类型）、config.ts、telemetry.ts 与测试目录；
• mem0-ts/src/oss/src/：自托管实现，实际子目录包括 config/、embeddings/、llms/、memory/、prompts/、rerankers/、storage/、types/、utils/、vector_stores/ 等（文档骨架中的 graphs/ 在当前的 oss 源码目录下已不再单列，实际目录以仓库为准）；
• 此外还有 mem0-ts/src/common/（共享异常等基础设施）与 mem0-ts/src/community/（社区 provider 构建产物被 tsup 内联进 OSS 包，对应 noExternal: ["!src/community/**"] 配置）。

从源码结构看，OSS 侧的组织方式与 Python SDK（mem0/ 目录）保持同构：llms/、embeddings/、vector_stores/、rerankers/ 各自提供 base.ts 抽象与多家具体 provider，memory/ 承载核心 Memory 类。这种同构是文档中"方法表面与 Python SDK 镜像"约定的基础。

五、公开 API：三大导出与方法表面

mem0-ts/AGENTS.md 定义的公开 API 表面为：

导出	用途	导入方式
MemoryClient	托管平台客户端	import { MemoryClient } from 'mem0ai'
Memory	自托管 OSS 内存	import { Memory } from 'mem0ai/oss'
Providers	OSS 构建块	import { OpenAIEmbedding } from 'mem0ai/oss'

三个导出在源码中的证据：

1. MemoryClient（主入口）：mem0-ts/src/client/index.ts 从 ./mem0 导出主类 MemoryClient（并作为 default export），同时重导出 AddMemoryOptions、SearchMemoryOptions、GetAllMemoryOptions 等类型，以及 Feedback、WebhookEvent 两个以值形式导出的枚举；
2. 结构化异常：同一入口还导出 MemoryError、AuthenticationError、RateLimitError、ValidationError、MemoryNotFoundError、NetworkError、ConfigurationError、MemoryQuotaExceededError 与工厂函数 createExceptionFromResponse（来自 src/common/exceptions）。这使调用方可以按错误类型做精细化捕获，而非解析错误消息字符串；
3. Memory 与 Providers（OSS 入口）：mem0-ts/src/oss/src/index.ts 通过 export * 聚合了 memory/（核心 Memory 类与类型）、全部 embeddings provider（AWS Bedrock、HuggingFace、OpenAI、Ollama、LM Studio、Together、Google、Azure、LangChain、VertexAI、FastEmbed）、llms provider（OpenAI、Google、Anthropic、Groq、Ollama、LM Studio、Mistral、LangChain、LiteLLM、vLLM、AWS Bedrock 等）、十余种 vector stores（Qdrant、Redis、Valkey、Supabase、pgvector、Databricks、Elasticsearch、Upstash、Cassandra、S3 Vectors、Pinecone、Turbopuffer、Milvus、MongoDB、OpenSearch、Weaviate、OracleDB 等）以及 rerankers（Cohere、LLM、ZeroEntropy、Cross Encoder）。这些 provider 均为可选依赖，与 mem0-ts/package.json 中 peerDependenciesMeta 里标记 optional: true 的大量 provider 包一一对应——只安装你实际使用的向量库/模型依赖即可，这也是 peerDependencies + peerDependenciesMeta 组合的用意。

文档同时约定：核心方法表面镜像 Python SDK，即 add、search、get、getAll、update、delete、deleteAll、history 八个操作。并且有一条硬性规则——任何公共签名变更都必须在同一个 PR 中同步更新 docs/ 文档，保持 TypeScript 与 Python 两条 SDK 线（以及文档站 docs/open-source/ 中的 Node 快速上手）三方一致。

六、发布流程：ts-v* Tag 触发 OIDC 发布

mem0-ts/AGENTS.md 的 Releasing 一节说明了 mem0-ts 的发布机制：

• 版本先行：先修改 mem0-ts/package.json 中的 version 字段（当前为 3.1.7）；
• Tag 触发：打上 ts-v* 前缀的 Git Tag（例如 ts-v3.1.7），会触发 CI 工作流 .github/workflows/ts-sdk-cd.yml；
• OIDC 发布：该工作流通过 OIDC（OpenID Connect）身份向 npm 发布，即仓库侧不持有静态 npm token，而是由 CI 平台临时换取发布凭据。

ts-v* 前缀与 Python 侧的发布 Tag 隔离，使同一 monorepo 内两条 SDK 的 CD 互不干扰。发布产物只包含 dist/ 目录（见 package.json 的 files: ["dist"]），与上文 tsup 的双格式输出闭环对应。

七、适用前提小结

• 本指南适用于 mem0 仓库 mem0-ts/ 目录下的 mem0ai 包开发；运行环境要求 Node >= 18（CI 承诺 Node 20/22）；
• 集成测试（pnpm run test:integration）需要 MEM0_API_KEY，指向可访问的托管平台；
• 所有工具链约定（jest、tsup、Prettier、严格模式）均以 mem0-ts/AGENTS.md、mem0-ts/package.json 与 mem0-ts/tsconfig.json 为最终依据；仓库其他模块（CLI、各 integration）拥有独立的工具链，不可套用本文约定。