Supermemory REST API 实战指南文档摄取、语义搜索与记忆管理接口全解析【免费下载链接】supermemoryMemory and context engine app that is extremely fast, scalable, and can be run fully locally. The Memory API for the AI era.项目地址: https://gitcode.com/GitHub_Trending/su/supermemorySupermemory 是一套面向 AI Agent 的记忆与上下文基础设施其核心能力通过一组 REST API 对外暴露POST /v3/documents负责把文本、URL、PDF、图片、视频等任意内容摄取为可检索的记忆POST /v4/search提供基于语义理解的高级检索POST /v4/memories允许绕过文档流水线直接写入记忆。本指南以 API 参考文档 为骨架结合仓库中packages/validation的 Zod 请求/响应模式与浏览器扩展的真实调用代码逐接口拆解参数、过滤语法、错误处理与最佳实践帮助你为 AI 应用接入持久记忆能力。认识 Supermemory APIBase URL 与认证所有端点共享同一个 API 根地址https://api.supermemory.ai除少数公开资源外每个请求都必须在Authorization请求头中携带 Bearer TokenAuthorization: Bearer YOUR_API_KEYAPI Key 需要在 Supermemory 控制台console.supermemory.ai创建并复制。仓库中浏览器扩展的真实客户端封装也严格遵循这一约定——api.ts 中的makeAuthenticatedRequest会从存储中取出 token统一拼入Authorization: Bearer ${token}并设置Content-Type: application/json当服务端返回401时抛出AuthenticationError(Invalid or expired token)与 API 文档的 401 语义一致。请求体一律使用application/json。如果使用官方 SDKTypeScript 的supermemory、Python 的supermemorySDK 内部会自动完成 token 注入、错误归一化与重试无需手动拼接请求头。POST /v3/documents文档摄取与记忆提取这是 Supermemory 的写入主入口。提交一条content后服务端会异步执行内容解析、语义切分、向量化、关系索引并自动抽取记忆。端点POST https://api.supermemory.ai/v3/documents请求体参数参数类型必填说明contentstring是待处理内容可以是 URL、纯文本、PDF 路径、图片或视频containerTagstring否组织文档的标识符最大 100 字符仅允许字母数字、连字符与下划线entityContextstring否指导记忆提取的上下文说明最大 1500 字符customIdstring否你的自定义标识符最大 100 字符仅允许字母数字、连字符与下划线metadataobject否自定义键值对值可以是字符串、数字、布尔值或字符串数组示例请求curl -X POST https://api.supermemory.ai/v3/documents \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { content: https://example.com/article, containerTag: user_123, entityContext: Technical blog post about API design, metadata: { source: blog, category: technical, tags: [api, design] } }成功响应200 OK{ id: doc_abc123xyz, status: queued }失败响应401 / 500{ error: Unauthorized, details: Invalid or missing API key }{ error: Internal Server Error, details: Failed to process document }处理流水线从 queued 到 done文档提交后立即返回id与status: queued随后进入异步处理流水线状态依次流转queued文档排队等待处理extracting正在进行内容提取chunking切分为语义段落embedding生成向量嵌入indexing构建记忆之间的关系done处理完成可被检索仓库中 schemas.ts 的DocumentStatusEnum与该状态机完全对应并额外补充了unknown与failed两个状态——failed用于标记提取失败的文档建议在轮询状态时一并处理。同文件中DocumentTypeEnum列出的受支持文档类型包括text、pdf、tweet、google_doc、google_slide、google_sheet、image、video、notion_doc、webpage、onedrive印证了content字段对 URL、PDF、图片、视频等多模态内容的支持。浏览器扩展对/v3/documents的调用是真实应用示例保存网页记忆时调用 saveMemoryPOST/v3/documents批量导入 Twitter 书签时则调用POST /v3/documents/batch并处理409 Conflict内容已存在——这说明除单条写入外还存在批量写入端点适合历史数据一次性回灌。POST /v4/search语义搜索与高级过滤检索是读取记忆的核心路径。v4 版本的搜索基于语义理解并支持复杂的组合过滤是 RAG 应用的首选接口。端点POST https://api.supermemory.ai/v4/search请求体参数参数类型必填说明querystring是搜索查询语句containerTagsstring[]否按容器标签过滤chunkThresholdnumber否段落选取阈值0-1。0 最不敏感返回更多结果1 最敏感返回更少但更准确的结果。默认 0searchModestring否搜索模式semantic默认或hybrid语义 关键词。RAG 应用建议使用hybrid以获得更高准确率docIdstring否在指定文档内搜索最大 255 字符filtersobject否支持 AND/OR 逻辑的高级过滤最多 5 层嵌套filters 过滤语法filters对象支持 5 类过滤条件可任意组合与嵌套{ filters: { // 元数据等值过滤 metadata: { key: value }, // 数值比较 numeric: { field: { $gte: 4.0 } // 支持 , , , , }, // 数组包含 array_contains: { tags: value }, // 字符串包含 string_contains: { content: substring }, // 逻辑运算符 $and: [{ /* filters */ }], $or: [{ /* filters */ }] } }完整示例请求混合模式 组合过滤curl -X POST https://api.supermemory.ai/v4/search \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { query: How do I authenticate users?, searchMode: hybrid, chunkThreshold: 0.5, filters: { metadata: { type: documentation, category: security }, numeric: { rating: { $gte: 4.0 } } } }成功响应200 OK{ results: [ { content: Authentication can be done using JWT tokens..., score: 0.89, docId: doc_123, metadata: { type: documentation, category: security, rating: 4.5 }, chunkId: chunk_456 }, { content: OAuth 2.0 is a standard protocol for authorization..., score: 0.82, docId: doc_789, metadata: { type: documentation, category: security, rating: 5.0 }, chunkId: chunk_789 } ], total: 2 }从源码看 v4 搜索的更多控制维度api.ts 中的Searchv4RequestSchema揭示了 v4 搜索接口更完整的请求参数其中部分参数在 API 参考文档 中未展开值得在生产环境中关注threshold默认 0.6记忆选取阈值语义与chunkThreshold相同0 召回多1 精确但默认值为 0.6。技能文件 SKILL.md 也明确提示v4 search 默认阈值为 0.6在检查检索质量后再微调可作为调参起点。include对象包含documents、summaries、relatedMemories三个布尔开关控制响应中是否附带完整文档、摘要与关联记忆。limit默认 101-100返回结果条数上限。rerank默认 false是否对结果做二次重排确保最相关结果排在最前。rewriteQuery默认 false是否先重写查询语句以提升检索命中率注意开启后延迟约增加 400ms。浏览器扩展的检索封装 search-request.ts 是精简版调用范例构造{ q, include: { relatedMemories: true }, containerTag }后 POST 到/v4/search。另外 search.mdx 说明 v4 检索还有memories、documents、hybrid三种模式分工只检索提取出的记忆用memories只检索文档段落用documents两者都要则用hybrid——文档建议默认优先 hybrid。POST /v4/memories直接写入记忆当记忆内容已经明确例如对话中用户直接陈述的偏好可以绕过文档摄取流水线直接创建记忆并立即获得可搜索能力。端点POST https://api.supermemory.ai/v4/memories请求体参数参数类型必填说明memoriesarray是1-100 条记忆对象组成的数组memories[].contentstring是记忆文本1-10,000 字符建议以实体为中心表述例如 John prefers dark modememories[].isStaticboolean否标记为永久性特质如姓名、职业。默认 falsememories[].metadataobject否自定义键值对字符串、数字、布尔值或字符串数组containerTagstring是这些记忆所属的空间/容器标识符示例请求curl -X POST https://api.supermemory.ai/v4/memories \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { containerTag: user_123, memories: [ { content: User prefers dark mode, isStatic: true, metadata: { category: preferences, source: settings } }, { content: User mentioned working on a React project yesterday, isStatic: false, metadata: { category: activity, timestamp: 2026-02-20T15:30:00Z } } ] }成功响应201 Created{ documentId: doc_abc123, memories: [ { id: mem_xyz789, memory: User prefers dark mode, isStatic: true, createdAt: 2026-02-21T10:00:00Z }, { id: mem_def456, memory: User mentioned working on a React project yesterday, isStatic: false, createdAt: 2026-02-21T10:00:00Z } ] }常见错误响应{ error: Bad Request, details: Invalid request parameters: memories array must contain 1-100 items }{ error: Not Found, details: Space not found for given containerTag }isStatic 与记忆版本化isStatic: true的记忆对应始终成立的静态事实姓名、职业、固定偏好isStatic: false则对应随时间变化的动态情境。从源码看schemas.ts 定义了MemoryRelationEnumupdates、extends、derives与记忆条目的version字段api.ts 的MemorySearchResult中每个记忆还携带context对象内含parents与children数组分别指向被这条记忆更新/扩展/派生的旧版本与由这条记忆衍生出的新版本。也就是说当新事实覆盖旧事实时Supermemory 不是简单覆盖而是以关系图的形式保留记忆演化历史——这与文档中自动处理知识更新与时间变化的描述一致。错误处理与限流HTTP 状态码速查状态码含义说明200OK请求成功201Created资源创建成功400Bad Request请求参数非法401UnauthorizedAPI Key 缺失或无效404Not Found资源不存在429Too Many Requests触发限流500Internal Server Error服务端错误统一错误格式所有错误响应都遵循同一结构仓库 api.ts 的ErrorResponseSchema与此完全一致{ error: Error Type, details: Detailed error message }常见错误示例{ error: Unauthorized, details: Invalid or missing API key }{ error: Too Many Requests, details: Rate limit exceeded. Please try again later. }{ error: Bad Request, details: content field is required }限流Rate Limit为保证系统稳定性API 实施限流。被限流时返回429响应头中携带重试时间HTTP/1.1 429 Too Many Requests Retry-After: 3600具体的额度取决于套餐计划可在 Supermemory 控制台查看。生产环境建议读取Retry-After实现指数退避而不是立即重试。最佳实践1. 使用幂等 ID 防止重复处理为customId传入稳定、可复现的标识重复提交同一内容不会产生重复文档curl -X POST https://api.supermemory.ai/v3/documents \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { content: Important document, customId: doc_2026_02_21_001, containerTag: user_123 }2. 规范的错误处理始终检查状态码并优雅处理错误const response await fetch(https://api.supermemory.ai/v3/documents, { method: POST, headers: { Authorization: Bearer ${API_KEY}, Content-Type: application/json }, body: JSON.stringify({ content: ..., containerTag: user_123 }) }); if (!response.ok) { const error await response.json(); console.error(Error ${response.status}:, error.details); throw new Error(error.details); } const data await response.json();注意官方 TypeScript/Python SDK 已内置此类错误处理与自动重试只有在自行封装 HTTP 客户端时才需要手工实现。3. 保持 containerTag 命名一致containerTag是记忆隔离与租户隔离的核心维度命名必须长期一致否则会导致数据分散# 推荐统一前缀 稳定标识 containerTag: user_123 containerTag: user_456 # 避免同一实体出现多种格式 containerTag: user_123 containerTag: 123 # 格式不一致源码中 MemorySchema 对containerTags的说明也印证了这一点这可以是你的用户 ID、项目 ID或任何用于分组记忆的标识符。4. 写入富 metadatametadata 直接决定检索阶段过滤能力越丰富越有利于精准召回{ content: Product review, containerTag: reviews, metadata: { product: iPhone 15, rating: 4.5, verified: true, date: 2026-02-21, tags: [smartphone, apple] } }注意约束schemas.ts 的MetadataSchema规定 metadata 的值只能是字符串、数字或布尔值不能嵌套对象键名区分大小写。5. 优化搜索阈值从默认值开始根据检索质量逐步调整chunkThreshold: 0是默认起点偏高则提高精确度但减少召回。文档给出的平衡参考值是 0.5-0.6{ query: authentication methods, chunkThreshold: 0.5 }6. 监控处理状态大文档处理需要时间通过列表接口轮询状态# 提交文档 curl -X POST https://api.supermemory.ai/v3/documents \ -H Authorization: Bearer YOUR_API_KEY \ -d { content: large-document.pdf, containerTag: docs } # 返回: { id: doc_123, status: queued } # 稍后查询该容器的文档状态 curl -X GET https://api.supermemory.ai/v3/documents?containerTagdocs \ -H Authorization: Bearer YOUR_API_KEYSDK 与直接调用 API 如何选择场景建议使用 TypeScript/Python 构建应用用 SDK自动错误处理、重试、类型提示需要类型安全与自动补全用 SDK使用其他语言直接调用 REST API需要细粒度控制直接调用 REST API编写 Serverless 函数直接调用 REST API集成现有 HTTP 客户端直接调用 REST API两者的底层是同一组端点SDK 的client.add(...)对应POST /v3/documentsclient.search(...)对应POST /v4/searchclient.profile(...)对应POST /v4/profile。可参考 SKILL.md 中的 TypeScript/Python 快速接入示例理解 SDK 封装方式。完整 cURL 示例合集以下四个示例覆盖文本摄取、URL 摄取、混合检索、直接写记忆四条最常用路径可直接复制改造。1. 添加文本内容curl -X POST https://api.supermemory.ai/v3/documents \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { content: User mentioned they prefer TypeScript over JavaScript for type safety, containerTag: user_123, metadata: { source: chat, timestamp: 2026-02-21T10:00:00Z } }2. 添加 URLcurl -X POST https://api.supermemory.ai/v3/documents \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { content: https://blog.example.com/best-practices, containerTag: knowledge_base, entityContext: Software development best practices article, metadata: { type: article, category: best-practices } }3. 混合模式 逻辑组合过滤RAG 场景curl -X POST https://api.supermemory.ai/v4/search \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { query: React performance optimization, searchMode: hybrid, chunkThreshold: 0.6, filters: { $and: [ { metadata: { type: tutorial } }, { numeric: { rating: { $gte: 4.0 } } } ] } }4. 直接创建记忆curl -X POST https://api.supermemory.ai/v4/memories \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { containerTag: user_789, memories: [ { content: User name is Alice Johnson, isStatic: true, metadata: { type: profile } }, { content: Alice completed the React tutorial today, isStatic: false, metadata: { type: activity, date: 2026-02-21 } } ] }延伸阅读与支持后续计划文档处理状态的 Webhook 通知coming soon可用于替代主动轮询完整的端点文档见 API 参考文档SDK 接入见 SDK 指南架构原理见 架构说明请求/响应的完整类型定义可在 validation/api.ts 与 validation/schemas.ts 中查阅基于 Zod OpenAPI 描述浏览器扩展的端到端调用实例见 api.ts可作为手写 HTTP 客户端时的参考实现API 异常排查可关注状态页status.supermemory.ai常规问题查阅官方文档supermemory.ai/docs。【免费下载链接】supermemoryMemory and context engine app that is extremely fast, scalable, and can be run fully locally. The Memory API for the AI era.项目地址: https://gitcode.com/GitHub_Trending/su/supermemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考