为 OpenAI Python 应用接入持久记忆supermemory-openai-sdk 中间件与 Function Calling 工具全指南【免费下载链接】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本篇技术指南围绕开源仓库supermemory中的packages/openai-sdk-python子包展开系统讲解如何通过supermemory-openai-sdk为官方 OpenAI Python SDK 增加两种记忆能力自动记忆注入中间件with_supermemory与手动记忆工具SupermemoryTools七种 function calling 工具。读者读完可以掌握完整的安装、配置、三种记忆模式的选择、后台记忆存储任务的管理、错误处理体系以及从源码层面理解记忆是如何被检索、去重、注入到系统提示词中的。包定位与核心能力supermemory-openai-sdk是 Supermemory 生态中面向 Python 开发者的官方集成包其核心定位是为 OpenAI 官方 Python SDKopenai1.102.0提供无限上下文能力。包内主要包含两大模块自动记忆注入中间件位于 middleware.py通过with_supermemory()包装 OpenAI 客户端在每次chat.completions.create()调用前自动检索用户历史记忆并注入系统提示词同时可自动将对话内容异步保存为记忆手动记忆工具位于 tools.py暴露 7 个符合 OpenAI function calling 规范的工具让模型在对话过程中自主决定何时搜索、添加、删除记忆。包版本为1.0.8见 pyproject.toml要求 Python3.9同时依赖supermemory3.50.0官方客户端与requests2.25.0作为 HTTP 回退方案。安装与环境准备推荐使用uv进行安装uv add supermemory-openai-sdk或使用pippip install supermemory-openai-sdk由于中间件面向AsyncOpenAI客户端时依赖aiohttp发起异步 HTTP 请求建议安装 async 扩展对于异步客户端强烈推荐uv add supermemory-openai-sdk[async] # 或 pip install supermemory-openai-sdk[async]依赖细节根据 pyproject.toml 的声明必选依赖为openai1.102.0、supermemory3.50.0、typing-extensions4.0.0、requests2.25.0可选依赖aiohttp3.8.0仅通过[async]扩展标记启用。从源码看middleware.py若未安装aiohttp中间件会自动回退到requests同步实现因此即使不装 async 扩展也可运行只是异步场景下性能会受影响。安装完成后需要设置以下环境变量SUPERMEMORY_API_KEYSupermemory API 密钥若在中间件选项中显式传入api_key则可省略OPENAI_API_KEYOpenAI API 密钥示例代码运行必需SUPERMEMORY_BASE_URL可选自定义 Supermemory API 地址默认https://api.supermemory.aiMODEL_NAME可选测试用的模型名默认gpt-4。快速开始方式一自动记忆注入中间件推荐with_supermemory()是接入记忆的最简路径它包装 OpenAI 客户端并在每次请求前自动完成检索记忆 → 注入系统提示词的全过程业务代码几乎无需改动import asyncio from openai import AsyncOpenAI from supermemory_openai import with_supermemory, OpenAIMiddlewareOptions async def main(): # 创建 OpenAI 客户端 openai AsyncOpenAI(api_keyyour-openai-api-key) # 用 Supermemory 中间件包装 openai_with_memory with_supermemory( openai, OpenAIMiddlewareOptions( container_taguser-123, # 必填用户/容器的唯一标识 custom_idchat-123, # 必填将多轮消息归组为同一文档 modefull, # profile、query 或 full verboseTrue, # 开启日志 add_memoryalways, # 自动保存对话默认值 api_keyyour-supermemory-api-key, # 或使用 SUPERMEMORY_API_KEY 环境变量 # base_urlhttps://api.supermemory.ai, # 可选自定义端点 ) ) # 正常使用即可——记忆会被自动注入 response await openai_with_memory.chat.completions.create( modelgpt-4, messages[ {role: user, content: Whats my favorite programming language?} ] ) print(response.choices[0].message.content) asyncio.run(main())从源码层面看with_supermemory返回的并不是原始客户端而是一个SupermemoryOpenAIWrapper包装器middleware.py。该包装器在构造时完成三件事解析 API key 与 base URL——显式传入的api_key优先其次读取SUPERMEMORY_API_KEY环境变量两者皆无则直接抛出SupermemoryConfigurationError实例化内部的supermemory.Supermemory客户端通过setattr替换client.chat.completions.create方法使其先执行记忆注入逻辑再调用原始方法middleware.py。包装器通过__getattr__将所有其他属性如models委托给原始客户端middleware.py所以包装后客户端的其余 API 不受影响。方式二使用记忆工具Function Calling若不希望记忆注入是全自动的而是让模型按需调用记忆能力可以使用SupermemoryToolsimport asyncio import openai from supermemory_openai import SupermemoryTools, execute_memory_tool_calls async def main(): # 初始化 OpenAI 客户端 client openai.AsyncOpenAI(api_keyyour-openai-api-key) # 初始化 Supermemory 工具 tools SupermemoryTools( api_keyyour-supermemory-api-key, config{project_id: my-project} ) # 携带记忆工具进行对话 response await client.chat.completions.create( modelgpt-5, messages[ { role: system, content: You are a helpful assistant with access to user memories. }, { role: user, content: Remember that I prefer tea over coffee } ], toolstools.get_tool_definitions() ) # 处理模型发起的工具调用 if response.choices[0].message.tool_calls: tool_results await execute_memory_tool_calls( api_keyyour-supermemory-api-key, tool_callsresponse.choices[0].message.tool_calls, config{project_id: my-project} ) print(Tool results:, tool_results) print(response.choices[0].message.content) asyncio.run(main())同步客户端支持中间件同样支持同步OpenAI客户端用法完全一致from openai import OpenAI from supermemory_openai import with_supermemory # 同步客户端 openai OpenAI(api_keyyour-openai-api-key) openai_with_memory with_supermemory( openai, OpenAIMiddlewareOptions( container_taguser-123, custom_idsession-456 ) ) # 用法相同 response openai_with_memory.chat.completions.create( modelgpt-4, messages[{role: user, content: Hello!}] )事件循环管理同步路径下中间件内部使用asyncio.run()驱动记忆检索与注入若同步客户端恰好在已有的异步上下文中被调用例如在 async 函数内误用了OpenAI而非AsyncOpenAIasyncio.run()会抛出RuntimeError: cannot be called from a running event loop此时中间件会自动将任务提交到独立的ThreadPoolExecutor线程中执行以避免冲突middleware.py。测试用例test_sync_client_in_async_context专门覆盖了这一场景见 tests/test_middleware.py。后台任务管理当add_memoryalways时对话内容会通过asyncio.create_task在后台异步保存不阻塞主请求。因此建议使用上下文管理器确保退出时后台任务完成或手动调用wait_for_background_tasks()from supermemory_openai import with_supermemory, OpenAIMiddlewareOptions # 异步上下文管理器推荐 async with with_supermemory( openai, OpenAIMiddlewareOptions(container_taguser-123, custom_idsession-456) ) as client: response await client.chat.completions.create(...) # 退出时自动等待后台任务完成 # 手动清理 client with_supermemory( openai, OpenAIMiddlewareOptions(container_taguser-123, custom_idsession-456) ) response await client.chat.completions.create(...) await client.wait_for_background_tasks() # 确保记忆已保存wait_for_background_tasks()的默认超时为 10 秒middleware.py超时后它会取消所有未完成任务并抛出asyncio.TimeoutError异步上下文管理器退出时使用 5 秒超时。后台任务保存失败网络错误等只会记录日志不会影响主请求的返回——这正是记忆是增强而非依赖的设计理念。中间件配置详解记忆注入模式Memory Modes中间件通过mode参数控制记忆检索策略对应三种模式模式行为适用场景profile默认仅注入静态动态用户画像记忆不针对当前消息做检索需要每轮请求都携带稳定用户上下文的场景query仅检索与当前用户消息相关的记忆记忆库较大、追求检索效率的场景full画像记忆 相关检索结果两者结合既要用户画像又要即时相关性的场景# profile 模式注入全部静态与动态画像记忆 openai_with_memory with_supermemory( openai, OpenAIMiddlewareOptions(container_taguser-123, custom_idsession-456, modeprofile) ) # query 模式仅检索与当前消息相关的记忆 openai_with_memory with_supermemory( openai, OpenAIMiddlewareOptions(container_taguser-123, custom_idsession-456, modequery) ) # full 模式画像 相关检索 openai_with_memory with_supermemory( openai, OpenAIMiddlewareOptions(container_taguser-123, custom_idsession-456, modefull) )从 middleware.py 的实现可以看到三种模式的本质差异中间件统一调用/v4/profile端点获取profile含static/dynamic与searchResultsmode ! profile时会用get_last_user_message()提取最后一条用户消息作为检索查询词qmode query时static/dynamic画像会被丢弃传入空列表只保留检索结果mode ! query时画像记忆会经convert_profile_to_markdown转换为 Markdown 格式## Static Profile、## Dynamic Profile两个小节mode ! profile且存在检索结果时会追加一段Search results for users recent message:前缀的列表。另外当mode为query/full但消息列表中没有 user 消息时中间件会跳过记忆检索直接透传请求middleware.py。记忆存储策略Memory Storage通过add_memory控制对话是否自动保存为记忆# 总是保存对话为记忆v2.0.0 默认行为 OpenAIMiddlewareOptions(container_taguser-123, custom_idsession-456, add_memoryalways) # 从不保存对话 OpenAIMiddlewareOptions(container_taguser-123, custom_idsession-456, add_memorynever)底层行为middleware.py值得注意add_memoryalways时中间件提取最后一条用户消息若配置了custom_id还会用get_conversation_content()将整段对话格式化为User: ...\n\nAssistant: ...的文本并以conversation:{custom_id}作为custom_id提交给 Supermemory——这意味着同一custom_id的多轮对话会被归组进同一个记忆文档实现会话级记忆同步客户端下保存是同步执行的且网络错误仅记录 warning 而不中断主流程。完整配置示例from supermemory_openai import with_supermemory, OpenAIMiddlewareOptions openai_with_memory with_supermemory( openai_client, OpenAIMiddlewareOptions( container_taguser-123, # 必填用户/容器唯一标识 custom_idchat-session-456, # 必填将消息归组为同一文档 verboseTrue, # 开启详细日志 modefull, # 同时使用画像与检索 add_memoryalways # 自动保存对话默认 ) )记忆注入的底层机制幂等的标签包裹与去重注入并不是简单地把记忆拼到 system prompt 后面。工具函数wrap_memory_contextutils.py会把检索结果包裹进一个带标记的只读块supermemory contextuser-memories readonly ...记忆内容... /supermemory中间件在注入前会先通过strip_memory_context()正则移除上一轮遗留的旧记忆块再注入新记忆从而保证多轮对话中记忆内容始终是最新一次检索结果不会累积膨胀模型输出内容中若出现/supermemory等标签会被转义为lt;/gt;防止记忆文本意外逃逸出块边界_escape_memory_context_delimitersutils.py记忆块优先注入developer消息其次system消息若两者皆不存在则自动在消息列表头部创建一条 system 消息middleware.py。此外deduplicate_memories()utils.py会对 static、dynamic、search results 三类来源的记忆做去重优先级为 Static Dynamic Search Results同一事实只在最高优先级来源保留一次。去重时会剥离[recent]前缀和[2026-01-01]这类日期前缀再比较归一化文本避免同一条事实因时间戳差异被重复注入。测试 tests/test_middleware.py 中的test_existing_system_prompt_enhancement验证了上述机制预置的旧supermemory块被新记忆替换、且块数量保持为 1test_empty_memories_do_not_modify_messages则验证了记忆为空时不会向消息列表追加空 system 消息或空白字符避免污染上下文。手动记忆工具SupermemoryToolsSupermemoryTools共暴露七个 OpenAI function calling 工具search_memories与add_memoryget_profiledocument_list、document_add与document_deletememory_forget工具调用的作用域由project_id或container_tags决定配置的第一个容器标签用于 profile、list、search、forget 等单空间操作而所有配置的标签都会应用于添加操作并限定document_delete允许删除的文档范围——模型无法自行选择不同的标签源码见 tools.py 的SupermemoryToolsConfig文档字符串。SupermemoryTools 类用法from supermemory_openai import SupermemoryTools tools SupermemoryTools( api_keyyour-supermemory-api-key, config{ project_id: my-project, # 或使用 container_tags base_url: https://custom-endpoint.com, # 可选 } ) # 搜索记忆 result await tools.search_memories( information_to_getuser preferences, limit10 ) # 添加记忆 result await tools.add_memory( memoryUser prefers tea over coffee ) # 获取配置用户的画像 result await tools.get_profile(queryfavorite drinks) # 列出、添加或删除源文档 documents await tools.document_list(limit10, page1) document await tools.document_add( contentMeeting notes..., titleWeekly meeting ) deleted await tools.document_delete(document_iddocument-id-here) # 软遗忘一条抽取出的记忆 forgotten await tools.memory_forget( memory_idmemory-entry-id-here, reasonoutdated )作用域解析规则_resolve_container_tagstools.py同时传入project_id与container_tags会抛出SupermemoryConfigurationError传入project_id时自动映射为标签sm_project_{project_id}传入container_tags时要求至少一个非空标签两者皆不传时使用默认标签sm_project_default。关于include_full_docs该参数作为兼容性参数保留Python 层仍可传入会触发DeprecationWarning但 v4 搜索只返回相关记忆与文本块chunk不再返回完整源文档因此它已不再出现在 OpenAI 工具 schema 中tools.py。测试test_search_memories_uses_search_memories_hybrid明确断言include_full_docs不会进入底层调用参数。单独创建工具SupermemoryTools之外包还提供 7 个独立工具类及对应的工厂函数适合只注册单个工具的轻量场景from supermemory_openai import ( create_search_memories_tool, create_add_memory_tool, create_get_profile_tool, create_document_list_tool, create_document_delete_tool, create_document_add_tool, create_memory_forget_tool, ) search_tool create_search_memories_tool(your-api-key) add_tool create_add_memory_tool(your-api-key) profile_tool create_get_profile_tool(your-api-key) list_tool create_document_list_tool(your-api-key) delete_tool create_document_delete_tool(your-api-key) document_add_tool create_document_add_tool(your-api-key) forget_tool create_memory_forget_tool(your-api-key)每个独立工具类如SearchMemoriesTool都持有definition即 OpenAI 工具 schema与execute()方法tools.py可直接作为 OpenAI 的tools参数使用。Function Calling 集成from supermemory_openai import execute_memory_tool_calls # 拿到 OpenAI 返回的 tool_calls 之后 if response.choices[0].message.tool_calls: tool_results await execute_memory_tool_calls( api_keyyour-supermemory-api-key, tool_callsresponse.choices[0].message.tool_calls, config{project_id: my-project} ) # 将工具结果追加回对话 messages.append(response.choices[0].message) messages.extend(tool_results)execute_memory_tool_calls内部会为每个 tool call 创建独立的SupermemoryTools实例并通过asyncio.gather并行执行tools.py返回格式为 OpenAI 标准的ChatCompletionToolMessageParamroletool、tool_call_id与 JSON 字符串形式的content。七个工具的参数 Schema 速查工具的 JSON Schema 集中定义在MEMORY_TOOL_SCHEMAStools.py关键约束如下工具必填参数其他参数与约束search_memoriesinformation_to_getlimit默认 10范围 1–100add_memorymemory建议单句或短段落get_profile无query可选附带检索结果document_list无limit默认 10最大 1100page1 起document_deletedocument_id拒绝删除作用域外/共享/处理中的文档document_addcontenttitle、description可选内容排队异步处理自动抽取记忆memory_forget无二选一memory_id或memory_content至少一个reason可选document_add与add_memory的分工是设计重点add_memory用于保存单条可泛化的事实document_add用于一次性摄入大段原始文本粘贴的文本、对话转录、笔记、URL 等Supermemory 会在后台完成分块、向量化、索引并自动抽取画像记忆——模型无需再对文档内的事实逐条调用add_memory。API 参考中间件函数与配置def with_supermemory( openai_client: Union[OpenAI, AsyncOpenAI], options: OpenAIMiddlewareOptions ) - Union[OpenAI, AsyncOpenAI]参数说明openai_clientOpenAI或AsyncOpenAI客户端实例options配置选项见下。dataclass class OpenAIMiddlewareOptions: container_tag: str # 必填记忆存储的唯一标识 custom_id: str # 必填将消息归组为同一文档 verbose: bool False # 是否输出详细日志 mode: Literal[profile, query, full] profile # 记忆注入模式 add_memory: Literal[always, never] always # 自动保存行为 api_key: Optional[str] None # 缺省时回退到 SUPERMEMORY_API_KEY base_url: Optional[str] None # 缺省时回退到 SUPERMEMORY_BASE_URL补充说明从源码 middleware.py 看api_key与base_url的解析顺序均为选项显式值 → 环境变量 → 默认值其中base_url的最终默认值为常量DEFAULT_SUPERMEMORY_BASE_URL https://api.supermemory.ai并会去除尾部/。SupermemoryTools 方法get_tool_definitions()— 获取全部 OpenAI function 定义7 个工具search_memories()— 搜索用户记忆add_memory()— 添加新记忆get_profile()— 获取配置用户的画像document_list()— 列出源文档元数据含分页document_add()— 排队处理一个源文档document_delete()— 删除作用域内的源文档删除前会校验文档的全部标签均在配置的作用域内tools.pymemory_forget()— 软遗忘一条抽取的记忆execute_tool_call()— 执行单个工具调用含参数校验tools.py。错误处理体系包内定义了层次化的异常体系exceptions.pySupermemoryError所有 Supermemory 异常的基类持有original_error便于追溯SupermemoryConfigurationError配置问题如缺失 API key、project_id与container_tags冲突SupermemoryAPIErrorAPI 请求失败携带status_code与response_textSupermemoryNetworkError网络连通性问题OSError/ConnectionError的包装SupermemoryMemoryOperationError记忆搜索/添加操作失败SupermemoryTimeoutError操作超时。典型用法from supermemory_openai import ( with_supermemory, OpenAIMiddlewareOptions, SupermemoryConfigurationError, SupermemoryAPIError, SupermemoryNetworkError, SupermemoryMemoryOperationError, ) try: # API key 缺失时这里会抛出 SupermemoryConfigurationError client with_supermemory( openai_client, OpenAIMiddlewareOptions(container_taguser-123, custom_idsession-456) ) response await client.chat.completions.create( messages[{role: user, content: Hello}], modelgpt-4 ) except SupermemoryConfigurationError as e: print(fConfiguration issue: {e}) except SupermemoryAPIError as e: print(fSupermemory API error: {e} (Status: {e.status_code})) except SupermemoryNetworkError as e: print(fNetwork error: {e}) except SupermemoryMemoryOperationError as e: print(fMemory operation failed: {e}) except Exception as e: print(fUnexpected error: {e})所有异常在构造时都保留了原始错误对象并生成包含上下文的描述性错误信息SupermemoryAPIError的__str__还会拼出状态码与响应体文本exceptions.py。需要注意记忆检索失败不会静默吞掉——supermemory_profile_search中的非 2xx 响应会直接抛出SupermemoryAPIError并中断本次请求middleware.py而后台记忆保存失败则只记日志、不影响主请求。底层调用链一次请求发生了什么综合源码middleware.py以AsyncOpenAImodefulladd_memoryalways为例一次chat.completions.create()的完整链路为包装with_supermemory构造SupermemoryOpenAIWrapper替换chat.completions.create触发调用包装后的create()进入_create_with_memory_async后台保存若add_memoryalways提取最后一条 user 消息格式化整段对话通过asyncio.create_task提交add_memory_tool异步保存任务被登记到_background_tasks集合记忆检索add_system_prompt调用supermemory_profile_search向{base_url}/v4/profile发起 POST请求体为{containerTag: ..., include: [static, dynamic], q: ...}q仅在非 profile 模式携带携带Authorization: Bearer {api_key}头aiohttp不可用时回退requests单次请求超时 30 秒去重与格式化deduplicate_memories按 Static Dynamic Search 优先级去重convert_profile_to_markdown将画像转为 Markdown注入_update_chat_memory_contexts将记忆块注入 developer/system 消息或新建 system 消息同时清除上一轮旧记忆块透传调用原始create()并返回结果。对应测试可参考 tests/test_middleware.py内存注入、去重替换、空记忆、后台任务、超时取消等场景与 tests/test_tools.py7 工具 schema、作用域冲突校验、client.add/search.memories底层调用参数断言。仓库根目录还提供了真实 API 联调脚本 test_integration.py设置OPENAI_API_KEY与SUPERMEMORY_API_KEY后可直接运行验证。开发与测试仓库内该包使用uv管理依赖与开发环境# 安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh # 克隆仓库后进入子包目录 cd packages/openai-sdk-python uv sync --dev运行测试与代码检查# 运行全部测试 uv run pytest # 带覆盖率运行 uv run pytest --covsupermemory_openai # 运行单个测试文件 uv run pytest tests/test_infinite_chat.py # 类型检查 uv run mypy src/supermemory_openai # 格式化 uv run black src/ tests/ uv run isort src/ tests/测试配置见 pyproject.tomlpytest-asyncio的asyncio_mode automypy 采用严格模式配置注意部分集成测试如tests/test_tools.py中的TestMemoryOperations需要真实SUPERMEMORY_API_KEY未设置时会自动跳过。总结supermemory-openai-sdk为 OpenAI Python 应用提供了一条低侵入的记忆接入路径中间件路线适合开箱即用通过with_supermemoryOpenAIMiddlewareOptions三个关键决策点container_tag/custom_id标识、mode检索策略、add_memory存储策略即可获得自动记忆注入与保存工具路线适合对记忆行为有精细控制需求的应用7 个 function calling 工具覆盖了从记忆搜索、画像读取到文档管理与遗忘的完整闭环。结合其幂等的记忆块注入、跨来源去重、作用域安全校验与完善的异常体系开发者可以在几行代码内为任意 OpenAI 对话应用赋予真正的长期记忆能力。【免费下载链接】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），仅供参考