Hindsight × Vapi 集成指南为语音 AI 通话注入持久化长期记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本指南讲解如何在 Vapi 语音 AI 平台上通过一个轻量级 Webhook 处理器hindsight-vapi把 Hindsight 的持久化长期记忆接入每一通电话来电开始即自动召回与来电者相关的历史记忆并注入助手系统提示通话结束时将完整对话记录异步写入记忆库。读完本文你将掌握 Webhook 的接入方式、全部配置参数、来电/去电两条记忆注入路径以及不依赖真实 Vapi 账号的手动联调方法。为什么 Vapi 需要专门的 Webhook 集成Vapi 是语音 AI 平台其服务端会在通话生命周期中触发 Webhook 事件。与 Pipecat提供按轮次的 FrameProcessor不同Vapi 不暴露按轮次per-turn的钩子——这意味着无法在对话每一轮都动态注入记忆只能在每通电话开始时注入一次见 webhook.py 的模块注释。hindsight-vapi仓库路径 hindsight-integrations/vapi正是为这一架构差异设计的它把召回记忆与写入记忆两个动作分别挂在 Vapi 的两个服务端事件上用一个类HindsightVapiWebhook完成全部接线。它本身框架无关可嵌入 FastAPI、Flask、aiohttp 等任意 HTTP 服务只需两行即可接入见 CHANGELOG.md。快速开始五分钟接入 Webhook安装与最小示例pip install hindsight-vapi一个完整的 FastAPI 接入如下直接取自 README.md 与 webhook.py 的用法示例from fastapi import FastAPI, Request from hindsight_vapi import HindsightVapiWebhook app FastAPI() memory HindsightVapiWebhook( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_your_token_here, ) app.post(/webhook) async def vapi_webhook(request: Request): event await request.json() response await memory.handle(event) return response or {}把 Vapi 控制台的Server URL指向这个端点记忆功能即生效。自托管替代若使用本地 Hindsight 实例只需把 URL 换成http://localhost:8888并省略api_keymemory HindsightVapiWebhook( bank_iduser-123, hindsight_api_urlhttp://localhost:8888, )客户端解析逻辑从源码看构造函数通过_resolve_clientwebhook.py按优先级解析 Hindsight 客户端显式传入client优先其次从hindsight_api_url/api_key参数构造两者都没有则回落到全局配置仍无 URL 时抛出HindsightVapiError(No Hindsight API URL configured...)errors.py。底层客户端来自hindsight-client0.4.0依赖见 pyproject.toml。工作原理一次通话中的记忆闭环Incoming call └─ Vapi fires assistant-request webhook └─ Recall memories (query callers phone number) └─ Return as assistantOverrides with hindsight_memories system message └─ Vapi merges into assistant config before the call begins Call ends └─ Vapi fires end-of-call-report webhook └─ Retain full transcript (fire-and-forget — webhook responds immediately)整个闭环由handle()方法webhook.py路由它读取event[message][type]仅处理assistant-request与end-of-call-report两类事件其余事件一律返回None对应 HTTP 200 空响应体。来电开始assistant-request 召回_handle_assistant_requestwebhook.py的逻辑从msg[call][customer][number]取出来电者电话号码作为召回查询词query号码缺失时使用兜底查询词returning caller这一点有测试专门验证见 test_webhook.py调用客户端arecall()进行语义召回无结果或召回禁用时返回{}Vapi 不会因此报错有结果时通过_build_overrideswebhook.py构造assistantOverrides其中注入一条 system 消息内容以hindsight_memories标记开头、以/hindsight_memories结尾内部为带编号的记忆条目列表。从客户端 SDK 看arecall()hindsight_client.py的budget参数即召回预算low/mid/high默认midmax_tokens默认 4096hindsight_client.py——Webhook 的recall_budget与recall_max_tokens参数正是透传给这两个底层参数。通话结束end-of-call-report 保留_handle_end_of_callwebhook.py从msg[artifact][transcript]取出完整通话记录若非空则通过asyncio.create_task(self._retain(transcript))**异步fire-and-forget**提交aretain()写入记忆库——Webhook 响应体不被延迟。底层aretain()hindsight_client.py会把通话记录交给 Hindsight 后台做事实抽取与记忆沉淀。优雅失败设计召回阶段异常被捕获并logger.warning返回{}通话照常进行continuing without memories见 webhook.py保留阶段异常同样被吞掉仅记日志见 webhook.py测试 test_webhook.py 验证了召回网络错误时返回空 dict 不抛异常test_webhook.py 验证保留失败不向上传播。记忆随通话累积同一来电者打到第二、三次电话时Hindsight 就会自动浮现相关历史信息。去电Outbound Calls没有 Webhook就在建呼时注入Vapi 的去电没有assistant-requestWebhook因此必须在调用 Vapi 创建通话 API 时用build_assistant_overrides()webhook.py在建呼时刻注入记忆overrides await memory.build_assistant_overrides(Ben from Vectorize) vapi.calls.create( assistant_id..., assistant_overridesoverrides, customer{number: 15555550100}, )该方法以你提供的查询词如对方姓名或通话主题描述召回记忆返回可直接作为assistantOverrides传入的 dict当召回被禁用或无结果时返回{}有测试覆盖见 test_webhook.py。前置条件准备一个可用的 Hindsight 实例自托管pip install hindsight-all export HINDSIGHT_API_LLM_API_KEYyour-api-key hindsight-api # starts on http://localhost:8888Hindsight Cloud直接注册获取 API Key免去自托管部署随后在配置中使用https://api.hindsight.vectorize.io与hsk_开头的 API Key。配置参数详解实例级配置HindsightVapiWebhook( bank_iduser-123, # Required: memory bank to use hindsight_api_url..., # Hindsight API URL api_keyhsk_..., # API key (Hindsight Cloud) recall_budgetmid, # low, mid, or high recall_max_tokens4096, # Max tokens for recall results enable_recallTrue, # Inject memories at call start enable_retainTrue, # Store transcript at call end memory_prefixRelevant memories from past conversations:\n, )各参数在构造函数webhook.py中的实际语义参数默认值作用bank_id必填读写的 Hindsight 记忆库memory bankIDclientNone预配置的 Hindsight 客户端优先使用hindsight_api_urlNoneAPI 地址未传client时用于构造客户端api_keyNoneHindsight Cloud 的 API Keyrecall_budgetmid召回预算档位low/mid/high透传给arecall(budget...)recall_max_tokens4096召回结果最大 token 数透传给arecall(max_tokens...)enable_recallTrue关闭后完全不召回来电与去电均返回{}enable_retainTrue关闭后通话结束不写入记忆memory_prefixRelevant memories from past conversations:\n注入系统提示中记忆块的前缀文案全局配置configure()多个 Webhook 共享同一连接信息时用configure()避免重复传参config.pyfrom hindsight_vapi import configure configure( hindsight_api_urlhttp://localhost:8888, api_keyhsk_..., recall_budgetmid, ) # Now create webhooks without repeating connection details memory HindsightVapiWebhook(bank_iduser-123)实现细节configure()返回HindsightVapiConfigdataclassconfig.py其中hindsight_api_url默认https://api.hindsight.vectorize.ioapi_key未显式传入时自动回落到HINDSIGHT_API_KEY环境变量config.pyWebhook 构造时recall_budget/recall_max_tokens若传空值也会从全局配置补齐webhook.py配套提供get_config()与reset_config()测试在 test_webhook.py 中验证了全局 URL 会被客户端解析器采用。Vapi 控制台配置三步走在 Vapi dashboard 中把Server URL设置为你的 Webhook 端点启用assistant-request与end-of-call-report两种事件类型来电场景下Vapi 触发assistant-request时记忆即自动召回注入。不注册 Vapi 账号也能联调交互式 Webhook 模拟器examples/目录提供了一个交互式 Webhook 模拟器interactive_webhook.py可模拟assistant-request与end-of-call-report事件无需真实 Vapi 账号或电话号码即可观察记忆的保留与召回全过程python examples/interactive_webhook.py --bank demo-user命令行参数--bank id记忆库 ID默认vapi-demo-USER--hindsight-url urlHindsight API 地址默认取HINDSIGHT_API_URL环境变量兜底http://localhost:8888--hindsight-api-key keyAPI Key默认取HINDSIGHT_API_KEY环境变量。交互命令:script引导式演示——先结束一通带完整对话记录的电话等待约 8 秒让异步事实抽取完成并dump_memories展示沉淀出的记忆再模拟第二通来电观察是否成功召回 Alex 的偏好interactive_webhook.py:end transcript模拟通话结束触发end-of-call-report保留对话脚本会等待数秒供后台任务推进见 interactive_webhook.py:call number模拟来电触发assistant-request召回并打印注入的系统提示内容:memories直接调用GET /v1/default/banks/{bank}/memories/list接口列出记忆库全部条目:bank显示当前记忆库 ID:quit/:q退出。典型演示序列来自脚本头部示例vapi :end User: My name is Alex. Assistant: Hi Alex! User: I prefer email. Assistant: Got it. vapi :memories vapi :call 15551234567运行测试仓库自带完整单元测试套件覆盖客户端解析、来电召回注入、去电 overrides 构建、通话结束保留、未知事件忽略等场景uv sync uv run pytest tests/ -v测试要点test_webhook.py记忆正确注入assistantOverrides的 system 消息且包含hindsight_memories标记与记忆正文L89-L99空召回、召回异常、禁用召回三种情况下均返回{}且不抛错L101-L138电话号码作为召回查询词、缺失时用returning callerL115-L130通话记录以 fire-and-forget 方式异步保留、空记录为 no-op、禁用保留时跳过L151-L194call-started、speech-update、transcript等未知事件一律返回None且不触发任何 Hindsight 调用L232-L238。项目配置要求 Python 3.10采用 pytest-asyncio 的asyncio_mode auto代码以 ruff 按 line-length 100、target py310 约束见 pyproject.toml。延伸阅读完整实现webhook.py、config.py底层 Python 客户端arecall/aretain的完整参数hindsight_client.py交互式模拟器interactive_webhook.py集成包变更记录CHANGELOG.md同类的语音 Agent 记忆集成按轮次注入的对比实现可参考仓库中的 pipecat 集成 目录。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hindsight × Vapi 集成指南：为语音 AI 通话注入持久化长期记忆
Hindsight × Vapi 集成指南为语音 AI 通话注入持久化长期记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本指南讲解如何在 Vapi 语音 AI 平台上通过一个轻量级 Webhook 处理器hindsight-vapi把 Hindsight 的持久化长期记忆接入每一通电话来电开始即自动召回与来电者相关的历史记忆并注入助手系统提示通话结束时将完整对话记录异步写入记忆库。读完本文你将掌握 Webhook 的接入方式、全部配置参数、来电/去电两条记忆注入路径以及不依赖真实 Vapi 账号的手动联调方法。为什么 Vapi 需要专门的 Webhook 集成Vapi 是语音 AI 平台其服务端会在通话生命周期中触发 Webhook 事件。与 Pipecat提供按轮次的 FrameProcessor不同Vapi 不暴露按轮次per-turn的钩子——这意味着无法在对话每一轮都动态注入记忆只能在每通电话开始时注入一次见 webhook.py 的模块注释。hindsight-vapi仓库路径 hindsight-integrations/vapi正是为这一架构差异设计的它把召回记忆与写入记忆两个动作分别挂在 Vapi 的两个服务端事件上用一个类HindsightVapiWebhook完成全部接线。它本身框架无关可嵌入 FastAPI、Flask、aiohttp 等任意 HTTP 服务只需两行即可接入见 CHANGELOG.md。快速开始五分钟接入 Webhook安装与最小示例pip install hindsight-vapi一个完整的 FastAPI 接入如下直接取自 README.md 与 webhook.py 的用法示例from fastapi import FastAPI, Request from hindsight_vapi import HindsightVapiWebhook app FastAPI() memory HindsightVapiWebhook( bank_iduser-123, hindsight_api_urlhttps://api.hindsight.vectorize.io, api_keyhsk_your_token_here, ) app.post(/webhook) async def vapi_webhook(request: Request): event await request.json() response await memory.handle(event) return response or {}把 Vapi 控制台的Server URL指向这个端点记忆功能即生效。自托管替代若使用本地 Hindsight 实例只需把 URL 换成http://localhost:8888并省略api_keymemory HindsightVapiWebhook( bank_iduser-123, hindsight_api_urlhttp://localhost:8888, )客户端解析逻辑从源码看构造函数通过_resolve_clientwebhook.py按优先级解析 Hindsight 客户端显式传入client优先其次从hindsight_api_url/api_key参数构造两者都没有则回落到全局配置仍无 URL 时抛出HindsightVapiError(No Hindsight API URL configured...)errors.py。底层客户端来自hindsight-client0.4.0依赖见 pyproject.toml。工作原理一次通话中的记忆闭环Incoming call └─ Vapi fires assistant-request webhook └─ Recall memories (query callers phone number) └─ Return as assistantOverrides with hindsight_memories system message └─ Vapi merges into assistant config before the call begins Call ends └─ Vapi fires end-of-call-report webhook └─ Retain full transcript (fire-and-forget — webhook responds immediately)整个闭环由handle()方法webhook.py路由它读取event[message][type]仅处理assistant-request与end-of-call-report两类事件其余事件一律返回None对应 HTTP 200 空响应体。来电开始assistant-request 召回_handle_assistant_requestwebhook.py的逻辑从msg[call][customer][number]取出来电者电话号码作为召回查询词query号码缺失时使用兜底查询词returning caller这一点有测试专门验证见 test_webhook.py调用客户端arecall()进行语义召回无结果或召回禁用时返回{}Vapi 不会因此报错有结果时通过_build_overrideswebhook.py构造assistantOverrides其中注入一条 system 消息内容以hindsight_memories标记开头、以/hindsight_memories结尾内部为带编号的记忆条目列表。从客户端 SDK 看arecall()hindsight_client.py的budget参数即召回预算low/mid/high默认midmax_tokens默认 4096hindsight_client.py——Webhook 的recall_budget与recall_max_tokens参数正是透传给这两个底层参数。通话结束end-of-call-report 保留_handle_end_of_callwebhook.py从msg[artifact][transcript]取出完整通话记录若非空则通过asyncio.create_task(self._retain(transcript))**异步fire-and-forget**提交aretain()写入记忆库——Webhook 响应体不被延迟。底层aretain()hindsight_client.py会把通话记录交给 Hindsight 后台做事实抽取与记忆沉淀。优雅失败设计召回阶段异常被捕获并logger.warning返回{}通话照常进行continuing without memories见 webhook.py保留阶段异常同样被吞掉仅记日志见 webhook.py测试 test_webhook.py 验证了召回网络错误时返回空 dict 不抛异常test_webhook.py 验证保留失败不向上传播。记忆随通话累积同一来电者打到第二、三次电话时Hindsight 就会自动浮现相关历史信息。去电Outbound Calls没有 Webhook就在建呼时注入Vapi 的去电没有assistant-requestWebhook因此必须在调用 Vapi 创建通话 API 时用build_assistant_overrides()webhook.py在建呼时刻注入记忆overrides await memory.build_assistant_overrides(Ben from Vectorize) vapi.calls.create( assistant_id..., assistant_overridesoverrides, customer{number: 15555550100}, )该方法以你提供的查询词如对方姓名或通话主题描述召回记忆返回可直接作为assistantOverrides传入的 dict当召回被禁用或无结果时返回{}有测试覆盖见 test_webhook.py。前置条件准备一个可用的 Hindsight 实例自托管pip install hindsight-all export HINDSIGHT_API_LLM_API_KEYyour-api-key hindsight-api # starts on http://localhost:8888Hindsight Cloud直接注册获取 API Key免去自托管部署随后在配置中使用https://api.hindsight.vectorize.io与hsk_开头的 API Key。配置参数详解实例级配置HindsightVapiWebhook( bank_iduser-123, # Required: memory bank to use hindsight_api_url..., # Hindsight API URL api_keyhsk_..., # API key (Hindsight Cloud) recall_budgetmid, # low, mid, or high recall_max_tokens4096, # Max tokens for recall results enable_recallTrue, # Inject memories at call start enable_retainTrue, # Store transcript at call end memory_prefixRelevant memories from past conversations:\n, )各参数在构造函数webhook.py中的实际语义参数默认值作用bank_id必填读写的 Hindsight 记忆库memory bankIDclientNone预配置的 Hindsight 客户端优先使用hindsight_api_urlNoneAPI 地址未传client时用于构造客户端api_keyNoneHindsight Cloud 的 API Keyrecall_budgetmid召回预算档位low/mid/high透传给arecall(budget...)recall_max_tokens4096召回结果最大 token 数透传给arecall(max_tokens...)enable_recallTrue关闭后完全不召回来电与去电均返回{}enable_retainTrue关闭后通话结束不写入记忆memory_prefixRelevant memories from past conversations:\n注入系统提示中记忆块的前缀文案全局配置configure()多个 Webhook 共享同一连接信息时用configure()避免重复传参config.pyfrom hindsight_vapi import configure configure( hindsight_api_urlhttp://localhost:8888, api_keyhsk_..., recall_budgetmid, ) # Now create webhooks without repeating connection details memory HindsightVapiWebhook(bank_iduser-123)实现细节configure()返回HindsightVapiConfigdataclassconfig.py其中hindsight_api_url默认https://api.hindsight.vectorize.ioapi_key未显式传入时自动回落到HINDSIGHT_API_KEY环境变量config.pyWebhook 构造时recall_budget/recall_max_tokens若传空值也会从全局配置补齐webhook.py配套提供get_config()与reset_config()测试在 test_webhook.py 中验证了全局 URL 会被客户端解析器采用。Vapi 控制台配置三步走在 Vapi dashboard 中把Server URL设置为你的 Webhook 端点启用assistant-request与end-of-call-report两种事件类型来电场景下Vapi 触发assistant-request时记忆即自动召回注入。不注册 Vapi 账号也能联调交互式 Webhook 模拟器examples/目录提供了一个交互式 Webhook 模拟器interactive_webhook.py可模拟assistant-request与end-of-call-report事件无需真实 Vapi 账号或电话号码即可观察记忆的保留与召回全过程python examples/interactive_webhook.py --bank demo-user命令行参数--bank id记忆库 ID默认vapi-demo-USER--hindsight-url urlHindsight API 地址默认取HINDSIGHT_API_URL环境变量兜底http://localhost:8888--hindsight-api-key keyAPI Key默认取HINDSIGHT_API_KEY环境变量。交互命令:script引导式演示——先结束一通带完整对话记录的电话等待约 8 秒让异步事实抽取完成并dump_memories展示沉淀出的记忆再模拟第二通来电观察是否成功召回 Alex 的偏好interactive_webhook.py:end transcript模拟通话结束触发end-of-call-report保留对话脚本会等待数秒供后台任务推进见 interactive_webhook.py:call number模拟来电触发assistant-request召回并打印注入的系统提示内容:memories直接调用GET /v1/default/banks/{bank}/memories/list接口列出记忆库全部条目:bank显示当前记忆库 ID:quit/:q退出。典型演示序列来自脚本头部示例vapi :end User: My name is Alex. Assistant: Hi Alex! User: I prefer email. Assistant: Got it. vapi :memories vapi :call 15551234567运行测试仓库自带完整单元测试套件覆盖客户端解析、来电召回注入、去电 overrides 构建、通话结束保留、未知事件忽略等场景uv sync uv run pytest tests/ -v测试要点test_webhook.py记忆正确注入assistantOverrides的 system 消息且包含hindsight_memories标记与记忆正文L89-L99空召回、召回异常、禁用召回三种情况下均返回{}且不抛错L101-L138电话号码作为召回查询词、缺失时用returning callerL115-L130通话记录以 fire-and-forget 方式异步保留、空记录为 no-op、禁用保留时跳过L151-L194call-started、speech-update、transcript等未知事件一律返回None且不触发任何 Hindsight 调用L232-L238。项目配置要求 Python 3.10采用 pytest-asyncio 的asyncio_mode auto代码以 ruff 按 line-length 100、target py310 约束见 pyproject.toml。延伸阅读完整实现webhook.py、config.py底层 Python 客户端arecall/aretain的完整参数hindsight_client.py交互式模拟器interactive_webhook.py集成包变更记录CHANGELOG.md同类的语音 Agent 记忆集成按轮次注入的对比实现可参考仓库中的 pipecat 集成 目录。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考