Hindsight Go Client 完整指南：用 Go 接入 Agent 记忆 API（Retain / Recall / Reflect）-北京尧图网络

Hindsight Go Client 完整指南用 Go 接入 Agent 记忆 APIRetain / Recall / Reflect【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本篇技术指南以 Hindsight 官方文档 Go Client 参考为主体系统讲解如何在 Go 项目中安装并接入 Hindsight 记忆服务从环境准备、客户端初始化到记忆写入Retain、检索Recall、生成式回答Reflect三大核心操作再到可空字段处理、错误处理与客户端配置调优。读完本文你将能够在自己的 Go 应用中通过类型安全的 API 客户端完成 Hindsight 全量记忆能力的集成并理解客户端背后的生成式实现原理。前置条件与安装Go Client 是 Hindsight 官方维护的 Go 语言客户端由 OpenAPI 3.1 规范通过 OpenAPI Generator 自动生成因此它天然覆盖了 Hindsight HTTP API 的全部端点与数据模型且与服务器端保持同步演进。官方文档要求Go 1.23运行环境。安装命令十分简单go get github.com/vectorize-io/hindsight/hindsight-clients/go安装完成后在你的 Go 源文件中引入import hindsight github.com/vectorize-io/hindsight/hindsight-clients/go从仓库中可以看到该模块的 go.mod 声明了模块路径github.com/vectorize-io/hindsight/hindsight-clients/go运行时依赖仅stretchr/testify测试用与gopkg.in/validator.v2请求参数校验用整体依赖非常轻量适合直接嵌入业务服务。使用前提先有一个可用的 Hindsight 服务Go Client 是一个 HTTP 客户端它本身不包含服务器实现。使用前你需要一个正在运行的 Hindsight 服务实例本地进程、Docker 容器或托管服务默认服务地址为http://localhost:8888。启动方式可参考仓库中 docker/docker-compose 目录下的编排模板。快速开始三步完成记忆写入与读取官方示例保存在 hindsight-docs/examples/api/quickstart.go完整演示了「写入 → 检索 → 生成」的最小闭环。先看最核心的初始化与三连调用cfg : hindsight.NewConfiguration() cfg.Servers hindsight.ServerConfigurations{ {URL: http://localhost:8888}, } client : hindsight.NewAPIClient(cfg) ctx : context.Background() // 1. Retain写入一条记忆 retainReq : hindsight.RetainRequest{ Items: []hindsight.MemoryItem{ {Content: hindsight.TextContent(Alice works at Google)}, }, } client.MemoryAPI.RetainMemories(ctx, my-bank).RetainRequest(retainReq).Execute() // 2. Recall按语义检索记忆 recallReq : hindsight.RecallRequest{ Query: What does Alice do?, } resp, _, _ : client.MemoryAPI.RecallMemories(ctx, my-bank).RecallRequest(recallReq).Execute() for _, r : range resp.Results { fmt.Println(r.Text) } // 3. Reflect基于记忆生成上下文回答 reflectReq : hindsight.ReflectRequest{ Query: Tell me about Alice, } answer, _, _ : client.MemoryAPI.Reflect(ctx, my-bank).ReflectRequest(reflectReq).Execute() fmt.Println(answer.GetText())三个操作分别对应 Hindsight 记忆生命周期中的核心阶段Retain记忆保留把原始信息文本或内容块写入指定 bank记忆库并异步完成抽取、向量化与入库Recall记忆召回以自然语言查询在既有记忆中做语义检索返回最相关的事实片段Reflect反思生成结合召回结果与 bank 的背景设定生成一段有上下文支撑的回答——这是 Hindsight 会用记忆的关键能力。注意到这里的调用风格是 OpenAPI Generator 的标准链式写法先client.MemoryAPI.RetainMemories(ctx, my-bank)拿到请求构造器再用.RetainRequest(req)携带请求体最后.Execute()真正发起 HTTP 请求并返回(响应体, *http.Response, error)三元组。关于 bank_id 与请求路径上面所有操作都传入了my-bank作为bankId。Hindsight 以bank记忆库为隔离单元记忆、指令、心理模型等都挂在某个 bank 之下。从 api_memory.go 的请求构造逻辑可以看到bankId会被拼进形如/v1/default/banks/{bank_id}/memories的 URL 路径中例如POST /v1/default/banks/{bank_id}/memories对应 RetainPOST /v1/default/banks/{bank_id}/memories/recall对应 RecallPOST /v1/default/banks/{bank_id}/reflect对应 Reflect。API 结构按命名空间组织的能力地图官方文档给出了客户端核心命名空间每个命名空间对应一个*APIService命名空间职责client.MemoryAPIRetain、Recall、Reflect 等记忆核心操作client.BanksAPIBank 的创建、更新、删除、配置管理client.DirectivesAPI指令Directive管理client.MentalModelsAPI心理模型Mental Model管理client.DocumentsAPI文档操作上传、列表、分块client.EntitiesAPI实体Entity操作client.OperationsAPI异步操作状态监控从源码 client.go 可以看到APIClient实际暴露的服务比文档列举的还要完整还包含AuditAPI审计日志、BankTemplatesAPI银行模板、DocumentTransferAPI文档迁移、FilesAPI文件、KnowledgeBaseAPI知识库、LLMTracesAPILLM 调用追踪、MonitoringAPI版本/健康/指标与WebhooksAPIWebhook 管理这些均由同一份 OpenAPI 规范生成type APIClient struct { cfg *Configuration common service AuditAPI *AuditAPIService BankTemplatesAPI *BankTemplatesAPIService BanksAPI *BanksAPIService DirectivesAPI *DirectivesAPIService DocumentTransferAPI *DocumentTransferAPIService DocumentsAPI *DocumentsAPIService EntitiesAPI *EntitiesAPIService FilesAPI *FilesAPIService KnowledgeBaseAPI *KnowledgeBaseAPIService LLMTracesAPI *LLMTracesAPIService MemoryAPI *MemoryAPIService MentalModelsAPI *MentalModelsAPIService MonitoringAPI *MonitoringAPIService OperationsAPI *OperationsAPIService WebhooksAPI *WebhooksAPIService }各服务共享同一个service基座结构common client避免为每个服务单独分配堆对象这也是生成代码的经典内存优化。每个 API 类的方法与对应 HTTP 端点的完整映射可参考 hindsight-clients/go/README.md例如MemoryAPI.ListMemories对应GET /v1/default/banks/{bank_id}/memories/list、MentalModelsAPI.RefreshMentalModel对应POST /v1/default/banks/{bank_id}/mental-models/{mental_model_id}/refresh。完整调用示例Bank 管理与异步操作除记忆三连外最常用的还有 Bank 创建与异步操作查询。Bank 是隔离单位先建 bank 再写记忆是推荐路径// 创建/更新 bank幂等PUT 语义 createReq : hindsight.CreateBankRequest{ Name: hindsight.PtrString(Assistant), Mission: hindsight.PtrString(Keep track of user preferences and conversation history.), } client.BanksAPI.CreateOrUpdateBank(ctx, my-bank).CreateBankRequest(createReq).Execute() // Retain 时若使用异步模式可凭 operationId 轮询进度 retainResp, _, _ : client.MemoryAPI.RetainMemories(ctx, my-bank). RetainRequest(retainReq).Execute() if retainResp.HasOperationId() { status, _, _ : client.OperationsAPI.GetOperationStatus(ctx, my-bank, retainResp.GetOperationId()).Execute() fmt.Printf(operation status: %s\n, status.GetStatus()) }注意RetainResponse通过HasOperationId()/GetOperationId()这对方法暴露异步操作标识——凡是这类可空字段客户端都会生成HasXxx()与GetXxx()访问器见下文「可空字段」一节。客户端配置从服务器地址到 HTTP 行为hindsight.NewConfiguration()返回的 Configuration 是客户端行为的唯一入口其字段包括字段作用Servers服务器地址列表OpenAPIservers字段的映射Host/Scheme覆盖请求的主机与协议DefaultHeader为所有请求附加的默认 HTTP 头UserAgent请求 UA默认OpenAPI-Generator/1.0.0/goDebug置为true时打印完整请求/响应转储调试利器HTTPClient自定义*http.Client可注入超时、连接池、缓存等最常用的配置组合是「指定服务器自定义 HTTP 客户端」cfg : hindsight.NewConfiguration() cfg.Servers hindsight.ServerConfigurations{ {URL: http://localhost:8888}, } cfg.HTTPClient http.Client{Timeout: 30 * time.Second} cfg.Debug true // 需要排查请求问题时打开 client : hindsight.NewAPIClient(cfg)从源码看NewAPIClient在HTTPClient为 nil 时会回退到http.DefaultClient见 client.go因此显式设置超时是生产环境的推荐做法。按操作覆盖服务器地址除了全局Servers客户端还支持按操作粒度覆盖服务器。Configuration.OperationServers以{ClassName}Service.{Method}为键如MemoryAPIService.RetainMemories指定不同端点。运行时还可以通过 context 传递索引或模板变量// 指定使用 Servers 列表中的第 1 个下标 0 起 ctx : context.WithValue(context.Background(), hindsight.ContextServerIndex, 1) // 覆盖服务器模板变量 ctx context.WithValue(ctx, hindsight.ContextServerVariables, map[string]string{ basePath: v2, })模板变量会做枚举合法性校验未在枚举内的取值会直接返回错误configuration.go。认证头Hindsight API 默认无需认证但需要时可通过cfg.AddDefaultHeader(Authorization, Bearer token)为所有请求统一附加令牌或在具体请求上使用各 API 生成的Authorization(...)链式方法。处理可空字段NullableString 与 Ptr* 工具函数OpenAPI 生成的 Go 模型中所有可选字段都是指针类型且区分「字段缺省」与「显式置空」两种状态。为此客户端提供两类工具NullableString/NullableTime/NullableInt等包装类型内置isSet标记可区分「未设置」与「设置为 null」PtrString/PtrTime/PtrInt等辅助函数快速把基本类型转为指针见 utils.go。官方示例演示了带上下文的记忆写入timestamp : time.Date(2024, 1, 15, 10, 0, 0, 0, time.UTC) retainReq2 : hindsight.RetainRequest{ Items: []hindsight.MemoryItem{ { Content: hindsight.TextContent(Alice got promoted), Context: *hindsight.NewNullableString(hindsight.PtrString(career update)), Timestamp: *hindsight.NewNullableTimestamp(hindsight.Timestamp{TimeTime: hindsight.PtrTime(timestamp)}), Tags: []string{career}, }, }, } retainResp, _, _ : client.MemoryAPI.RetainMemories(ctx, my-bank).RetainRequest(retainReq2).Execute() // 用 HasXxx 判断字段是否真的存在 if retainResp.HasOperationId() { fmt.Println(OperationId:, retainResp.GetOperationId()) }这里的Context、Timestamp就是典型的可选字段NewNullableString(PtrString(...))表示「设置一个字符串值」而NewNullableString(nil)则代表「显式置 null」——两者在 JSON 序列化时行为不同后者会输出null这正是区分缺省与置空的关键场景。Timestamp字段本身又是一个带内部TimeTime指针的嵌套模型与PtrTime配合使用。对于多态字段如Content生成代码采用 anyOf 反序列化Content结构同时持有*[]ContentAnyOfInner内容块列表支持图文混排与*string纯文本两个指针反序列化时依次尝试匹配并只保留首个成功命中的变体见 model_content.go。hindsight.TextContent(...)正是构造纯文本变体的便捷方法而图片等内容块形式需要 vision 能力的 retain LLM 支持。错误处理标准 Go 惯用法官方示例给出了标准错误处理模式——每次Execute()都返回(模型, *http.Response, error)HTTP 非 2xx 状态码会表现为非 nil 的 error_, httpResp2, err : client.MemoryAPI.RecallMemories(ctx, my-bank). RecallRequest(recallReq). Execute() if err ! nil { log.Fatalf(Recall failed: %v, err) } defer httpResp2.Body.Close()实践建议始终检查 error示例中为了简洁用_, _, _丢弃了返回值但生产代码应检查第三个返回值利用GenericOpenAPIError当服务器返回错误时错误类型为GenericOpenAPIError可通过Body()读取原始响应体、Model()取反序列化后的错误模型见 client.go。对符合 RFC 7807 的错误模型错误信息会自动拼接title (detail)格式注意关闭响应体即使调用成功*http.Response的Body也应defer Close()避免连接泄漏合理设置超时通过自定义HTTPClient或 context 的 deadline/cancel 控制请求生命周期Recall / Reflect 属于 LLM 参与的重操作尤其需要超时兜底。通过 Debug 模式快速定位问题遇到请求异常时把cfg.Debug true打开客户端会在每次请求前httputil.DumpRequestOut、请求后DumpResponse打印完整的请求/响应内容client.go对排查 400/422 参数校验错误非常有效。更多参考与进阶路径本文所有代码示例的完整可运行版本见 hindsight-docs/examples/api/quickstart.go示例自带HINDSIGHT_API_URL环境变量支持默认http://localhost:8888客户端源码位于 hindsight-clients/goAPI 端点与模型文档见其中的 README.md仓库还包含 integration_test.go 与 null_test.go 等测试可作为用法参考多语言 SDK 的 API 概念完全一致可以互相印证Python SDK 文档、Node.js SDK 文档若你的诉求是「在 Go/Python 进程内直接内嵌 Hindsight 服务器免外部服务」可进一步阅读 hindsight-all 嵌入式文档完整 REST API 参考以服务器暴露的 OpenAPI 规范为准/openapi.json客户端各模型字段定义均可在 hindsight-clients/go 中以model_*.go文件查阅。小结Hindsight Go Client 是一条通往 Hindsight 记忆服务的类型安全捷径一条go get安装命令、一次NewAPIClient初始化即可通过MemoryAPI/BanksAPI/MentalModelsAPI等命名空间调用全部记忆能力。掌握好链式请求构造、可空字段的两类处理工具Nullable*与Ptr*、以及(模型, *http.Response, error)三元组的错误处理惯例你就能在 Go 应用中稳定地集成「写入记忆 → 语义召回 → 上下文生成」的完整闭环为 Agent 构建真正会学习的长期记忆底座。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Hindsight Go Client 完整指南：用 Go 接入 Agent 记忆 API（Retain / Recall / Reflect）

相关推荐

病例资料对不上报告规范？医学论文里，多半是两套叫法没接上

Raspberry Pi Pico硬件开发入门：MicroPython固件烧录与REPL实战

SkillPort企业学习平台：功能解析与实施指南

更多资讯

原生JavaScript实现全屏轮播：触摸手势、视口适配与性能优化

宽带FIR波束形成：从窄带相移失效到时域抽头设计

51单片机、STM32F103与F407选型实战决策指南

Allegro 16.6实战教程：聚焦板层设置、网表导入与DXF导出的工程本质

基于MATLAB与混沌系统的图像加密技术实现

基于Java的视频会议系统：WebRTC信令与Spring Boot实战

今日更新

基于高阶循环谱的MPSK载波频率估计与MATLAB实现

MiniPdf方：.NET开源Office转PDF的高效解决方案

Solon AI v3.10：Java全栈智能体开发框架解析

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？