hindsight-all Python 编程式 API 指南在本地进程内一键启动 Hindsight 记忆服务【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本指南围绕 Hindsight 仓库中的 hindsight-all 编程式 APIPython 文档展开系统讲解如何通过hindsight-all包在本地 Python 代码中直接拉起一个完整的 Hindsight 记忆服务——无需部署任何服务器基础设施。读完本文你将掌握HindsightServer显式生命周期与HindsightEmbedded自动托管两种使用方式、Profile 数据隔离机制、四大 API 命名空间banks / mental_models / directives / memories的完整用法以及 daemon 崩溃自动恢复等底层原理可直接在测试、脚本和长期运行的应用中落地。为什么需要 hindsight-all一套安装包零基础设施启动Hindsight 是一个“会学习的 Agent 记忆系统”Agent Memory That Learns。要把它接入自己的应用通常需要部署 API 服务、准备数据库、再引入客户端——这在实际开发中是一笔不小的开销。hindsight-all的目的就是把这套流程压缩成一个安装包和几行 Python 代码。从仓库中的 hindsight-all/pyproject.toml 可以看到它的依赖构成当前版本 0.9.2hindsight-api-slim[all]0.9.2—— Hindsight API 服务端精简版含全部可选依赖hindsight-client0.0.7—— 官方 Python HTTP 客户端hindsight-embed0.9.2—— 嵌入式 daemon 管理模块因此pip install hindsight-all一次安装就能同时获得 API 服务、嵌入式 PostgreSQL 存储和类型化 Python 客户端三件套。需要注意的是这里的“嵌入式”并不意味着服务跑在你的 Python 进程内存里。相反hindsight-all/hindsight/init.py 导出的两个核心入口HindsightServer与HindsightEmbedded其底层 daemon 都以独立的 OS 进程运行在127.0.0.1上你的代码通过 HTTP 与该进程通信。也就是说Python 进程崩溃不影响记忆数据记忆服务随时可以被其他进程、CLI 工具复用。安装与依赖pip install hindsight-all如果你的运行环境没有 LLM API 密钥也可以选择本地推理方案pip install hindsight-all[local-llm]该可选依赖通过hindsight-api-slim[local-llm]引入本地模型支持。仓库的测试套件还声明了test可选依赖pytest、pytest-asyncio用于运行 hindsight-all/tests 下的集成测试。环境要求为python 3.11。如果你已经有运行中的 Hindsight 服务器、只需要一个客户端那么应当直接使用 Python Clienthindsight-client无需引入整套嵌入式依赖。两种 API 形态HindsightServer 与 HindsightEmbeddedhindsight-all暴露两类主要 API二者最终都通过同一个HindsightClientHTTP 接口与同一个底层 daemon 通信区别只在于服务器进程由谁管理API生命周期管理适用场景HindsightServer显式进入上下文即启动退出即关闭测试、短生命周期脚本要求确定性的启停HindsightEmbedded自动首次调用启动跨调用复用空闲自动退出长期运行的应用不想关心生命周期下面分别深入讲解。HindsightServer显式生命周期上下文管理器HindsightServer作为上下文管理器使用进入with块时立即启动服务退出时干净关闭非常适合测试和短脚本import os from hindsight import HindsightServer, HindsightClient with HindsightServer( llm_provideropenai, llm_modelgpt-4o-mini, llm_api_keyos.environ[OPENAI_API_KEY], ) as server: client HindsightClient(base_urlserver.url) client.retain(bank_idmy-bank, contentAlice works at Google) results client.recall(bank_idmy-bank, queryWhat does Alice do?) for r in results: print(r.text) answer client.reflect(bank_idmy-bank, queryTell me about Alice) print(answer.text) # Server is stopped here从源码看hindsight-all/hindsight/server.py 中的Server类提供了完整的生命周期实现启动start(timeout30.0)在一个后台守护线程threading.Thread(daemonTrue)中创建MemoryEngine、构建 FastAPI 应用create_app、并启动 uvicorn 服务器。启动后通过socket.create_connection轮询确认端口已就绪才返回超时则抛出RuntimeError。端口默认通过_find_free_port()自动选择一个空闲端口无需手动指定也可以通过port参数固定端口。停止stop()将uvicorn.Server.should_exit置为 True等待线程退出默认最多 10 秒并完成MemoryEngine.close()清理。URLserver.url属性返回http://{host}:{port}默认绑定127.0.0.1。Server的完整构造参数也是start_server便捷函数接受的参数如下参数默认值说明db_urlpg0数据库 URLpg0表示使用嵌入式 PostgreSQLllm_providergroqLLM 提供商groq、openai、ollama、gemini、anthropic、lmstudio等llm_api_keyLLM 提供商 API 密钥llm_modelopenai/gpt-oss-120b使用的模型名llm_base_urlNone可选的 LLM API 自定义 base URLhost127.0.0.1服务绑定地址portNone绑定端口默认自动选择空闲端口mcp_enabledFalse是否启用 MCP 服务器log_levelinfoServer/warningstart_serveruvicorn 日志级别除了上下文管理器你还可以手动管理生命周期先用start_server(...)或Server(...).start()启动用完调用server.stop()hindsight-all/README.md 的 Quick Start 展示了这种写法。HindsightEmbedded自动托管开箱即用HindsightEmbedded是 Hindsight 在 Python 中使用的最简方式。它自动管理后台 daemon首次调用时启动之后跨调用复用同一个 daemon空闲后自动退出你也可以调用close(stop_daemonTrue)显式停止。from hindsight import HindsightEmbedded import os # Server starts automatically on first call client HindsightEmbedded( profilemyapp, # Profile for data isolation llm_provideropenai, llm_modelgpt-4o-mini, llm_api_keyos.environ[OPENAI_API_KEY], ) # Use immediately - no manual server management needed client.retain(bank_idmy-bank, contentAlice works at Google) results client.recall(bank_idmy-bank, queryWhat does Alice do?) # Server continues running (auto-stops after idle timeout) # Or explicitly stop it: client.close(stop_daemonTrue)HindsightEmbedded的构造参数非常灵活见 hindsight-all/hindsight/embedded.py。关键设计是你显式传入的设置才会被转发给 daemon未指定的参数全部交给 daemon 按序解析——先查 Profile 的.env文件再查父进程环境变量最后使用 daemon 自身默认值。这意味着你可以构造一个不带凭据的客户端让它直接复用某个已配置好凭据的 Profile 或 shell 环境而不会被占位符覆盖源码注释中引用了 issue #3253 的设计约束。重要参数说明参数默认值说明profiledefaultProfile 名称用于数据隔离llm_providerNone继承LLM 提供商省略则继承服务器默认openaillm_api_keyNone继承API 密钥省略则继承显式传表示明确运行在无密钥环境如本地免鉴权服务llm_modelNone继承模型名省略则继承服务器按已解析的提供商选默认模型llm_base_urlNone自定义 LLM API base URLdatabase_urlNone数据库 URL 覆盖项默认使用 Profile 专属 pg0idle_timeout已弃用并被忽略daemon 不再因空闲自动退出保留参数仅为兼容旧调用方log_levelNone继承daemon 日志级别daemon 默认infouiFalse是否随 daemon 一同启动控制平面 Web UIui_portNoneUI 端口默认daemon_port 10000ui_hostname0.0.0.0UI 绑定主机名内部实现上HindsightEmbedded通过get_embed_manager()来自hindsight-embed包获得DaemonEmbedManager其配置以HINDSIGHT_API_LLM_PROVIDER、HINDSIGHT_API_LLM_API_KEY、HINDSIGHT_API_LLM_MODEL等环境变量键的形式传给 daemon。什么是 ProfileProfile 是一个隔离的 Hindsight 环境。每个 Profile 拥有自己的嵌入式 PostgreSQL 数据库存储在~/.pg0/instances/hindsight-embed-{profile}/自己的 API 服务器进程。因此可以用不同 Profile 来隔离开发/生产环境、不同应用甚至不同用户的数据。仓库中的集成测试 hindsight-all/tests/test_embedded.py 中的test_embedded_profile_isolation验证了这一点两个不同 Profile 使用相同的bank_id各自写入内容互相看不到对方的数据。HindsightEmbedded与hindsight-embedCLI 共享同一套 daemon 管理接口和 Profile 存储因此可以放心地与 CLI 工具混用同一份 Profile 数据。何时选择哪种使用场景选择测试、短生命周期脚本、需要确定性启停HindsightServer上下文管理器长期运行的应用、首次使用自动启动、不想管理生命周期HindsightEmbedded已有运行中的 Hindsight 服务器直接使用 hindsight-clientAPI 命名空间组织化的银行、心智模型、指令与记忆操作HindsightEmbedded和HindsightClient都暴露了组织化的 API 命名空间用于银行Bank管理、心智模型Mental Models、指令Directives和记忆Memoriesfrom hindsight import HindsightEmbedded import os embedded HindsightEmbedded( profilemyapp, llm_provideropenai, llm_api_keyos.environ[OPENAI_API_KEY], ) # Core operations embedded.retain(bank_idtest, contentHello) results embedded.recall(bank_idtest, queryHello) # Bank management embedded.banks.create(bank_idtest, nameTest Bank, missionHelp users) embedded.banks.set_mission(bank_idtest, missionUpdated mission) embedded.banks.delete(bank_idtest) # Mental models embedded.mental_models.create( bank_idtest, nameUser Preferences, contentUser prefers dark mode ) models embedded.mental_models.list(bank_idtest) # Directives embedded.directives.create( bank_idtest, nameResponse Style, contentBe concise and friendly ) directives embedded.directives.list(bank_idtest) # List memories memories embedded.memories.list(bank_idtest, typeworld, limit50)这些命名空间由 hindsight-all/hindsight/api_namespaces.py 中的四个类实现BanksAPI、MentalModelsAPI、DirectivesAPI、MemoriesAPI在 hindsight-all/hindsight/client_wrapper.py 中还有一套绑定在HindsightClient上的同名实现。每个命名空间的方法签名与底层客户端方法一一对应bankscreate(bank_id, nameNone, missionNone, dispositionNone)、delete(bank_id)、set_mission(bank_id, mission)、set_disposition(bank_id, disposition)HindsightClient版本另有list()。mental_modelscreate(bank_id, name, content, tagsNone)、list(bank_id, tagsNone, detailNone)、get(bank_id, mental_model_id)、refresh(bank_id, mental_model_id)、update(...)、delete(...)。其中list()默认只返回元数据需要正文时传detailcontent。directivescreate(bank_id, name, content, tagsNone)、list(bank_id, tagsNone)、get(bank_id, directive_id)、update(...)、delete(...)。memorieslist(bank_id, typeNone, search_queryNone, limit100, offset0)支持按记忆类型过滤、文本搜索与分页。为什么推荐走命名空间而不是直接访问 client关键原因在于daemon 崩溃的优雅处理。命名空间的每个方法调用都会先执行_ensure_started()见 hindsight-all/hindsight/embedded.py它会检查 daemon 是否仍在运行若已崩溃则自动清理过期客户端并重启 daemon然后才发起真实 API 调用# ✅ GOOD - Uses API namespace (daemon restarts handled) embedded.banks.create(bank_idtest, nameTest) # ❌ BAD - Direct client access (daemon crashes NOT handled) client embedded.client client.create_bank(bank_idtest, nameTest) # Fails if daemon crashed这一点有测试直接背书hindsight-all/tests/test_embedded_namespaces.py 中的test_daemon_restart_handling模拟了“daemon 崩溃→清除客户端→再次调用”的场景验证命名空间方法能透明地重启 daemon 并继续工作test_multiple_calls_ensure_daemon_each_time则确认每次命名空间调用都会执行_ensure_started()。此外 hindsight-all/tests/test_embedded.py 的test_embedded_daemon_crash_recovery通过client._manager.stop(profile)模拟真实崩溃随后下一次retain调用自动重启 daemon 并成功写入数据。需要注意的是HindsightEmbedded的普通方法代理__getattr__同样会在调用前执行_ensure_started()所以直接调用client.retain(...)也具有崩溃恢复能力真正危险的是先通过embedded.client拿到底层Hindsight客户端引用再保存下来使用——该引用在 daemon 崩溃后不会自动刷新。完整工作流示例从建库到反思结合仓库测试 hindsight-all/tests/test_embedded.py 中的test_embedded_complete_workflow一个典型的完整工作流如下client HindsightEmbedded(profilemyapp, llm_provideropenai, llm_api_keyos.environ[OPENAI_API_KEY]) # 1. 创建记忆银行 client.create_bank(bank_idassistant, nameTest Assistant, missionHelp with programming tasks) # 2. 存储单条记忆 client.retain(bank_idassistant, contentUser prefers Python for data analysis., contextProgramming preferences) # 3. 批量存储记忆 client.retain_batch(bank_idassistant, items[ {content: User works with pandas and numpy.}, {content: User likes matplotlib for visualization.}, {content: User is interested in machine learning with scikit-learn.}, ]) # 4. 检索记忆 results client.recall(bank_idassistant, queryWhat tools does the user prefer?, max_tokens2000) # 5. 反思基于记忆生成上下文回答 answer client.reflect(bank_idassistant, queryWhat programming tools should I recommend?, budgetlow) # 6. 列出记忆 client.list_memories(bank_idassistant, limit10) client.close()retain/recall/reflect的完整参数参考无论客户端以何种方式获得行为一致见 Python Client 页面例如retain支持context、timestamp、document_id、metadata、retain_asyncrecall支持types、max_tokens、budgetlow/mid/high、include_chunksreflect支持budget与context所有方法都有以a前缀开头的异步版本aretain、arecall、areflect等。进阶上下文管理器与 UI 控制平面HindsightEmbedded同样支持上下文管理器退出时自动调用close()from hindsight import HindsightEmbedded with HindsightEmbedded(profilemyapp) as client: client.retain(bank_idalice, contentAlice loves AI) # Daemon managed automatically如果你希望记忆服务同时附带可视化控制平面可以设置uiTrue并可选ui_port、ui_hostname。测试 hindsight-all/tests/test_embedded.py 中的test_embedded_ui_flag验证了启用 UI 后首次调用会同时拉起 daemon 和 UI且 UI 的健康检查端点{ui_url}/api/health返回status: ok且dataplane.status: connected说明数据平面已成功连接。最佳实践小结测试与短脚本用HindsightServer上下文管理器确定性的启停让测试互不干扰server.url可直接注入HindsightClient。应用代码用HindsightEmbedded懒启动 跨调用复用 空闲自动退出配合命名空间获得 daemon 崩溃自愈能力。用 Profile 做环境隔离dev/prod、不同应用或不同用户各用一个 Profile数据库与服务器进程完全隔离存储于~/.pg0/instances/hindsight-embed-{profile}/。优先走 API 命名空间embedded.banks、embedded.mental_models等避免长期保存embedded.client裸引用。无密钥本地服务将llm_api_key显式传可清除继承的 API 密钥配合本地 LLM 服务如ollama、lmstudio使用。省略参数即继承构造HindsightEmbedded时未显式给出的配置会按“Profile.env→ 父进程环境变量 → daemon 默认值”的顺序解析适合复用已配置好的环境。从安装到生产级接入hindsight-all用一套依赖覆盖了 API 服务、嵌入式 PostgreSQL 与类型化客户端让“Agent 记忆”真正成为应用里随手可用的本地基础设施。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 hindsight-all Python 编程式 API 指南：在本地进程内一键启动 Hindsight 记忆服务
hindsight-all Python 编程式 API 指南在本地进程内一键启动 Hindsight 记忆服务【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本指南围绕 Hindsight 仓库中的 hindsight-all 编程式 APIPython 文档展开系统讲解如何通过hindsight-all包在本地 Python 代码中直接拉起一个完整的 Hindsight 记忆服务——无需部署任何服务器基础设施。读完本文你将掌握HindsightServer显式生命周期与HindsightEmbedded自动托管两种使用方式、Profile 数据隔离机制、四大 API 命名空间banks / mental_models / directives / memories的完整用法以及 daemon 崩溃自动恢复等底层原理可直接在测试、脚本和长期运行的应用中落地。为什么需要 hindsight-all一套安装包零基础设施启动Hindsight 是一个“会学习的 Agent 记忆系统”Agent Memory That Learns。要把它接入自己的应用通常需要部署 API 服务、准备数据库、再引入客户端——这在实际开发中是一笔不小的开销。hindsight-all的目的就是把这套流程压缩成一个安装包和几行 Python 代码。从仓库中的 hindsight-all/pyproject.toml 可以看到它的依赖构成当前版本 0.9.2hindsight-api-slim[all]0.9.2—— Hindsight API 服务端精简版含全部可选依赖hindsight-client0.0.7—— 官方 Python HTTP 客户端hindsight-embed0.9.2—— 嵌入式 daemon 管理模块因此pip install hindsight-all一次安装就能同时获得 API 服务、嵌入式 PostgreSQL 存储和类型化 Python 客户端三件套。需要注意的是这里的“嵌入式”并不意味着服务跑在你的 Python 进程内存里。相反hindsight-all/hindsight/init.py 导出的两个核心入口HindsightServer与HindsightEmbedded其底层 daemon 都以独立的 OS 进程运行在127.0.0.1上你的代码通过 HTTP 与该进程通信。也就是说Python 进程崩溃不影响记忆数据记忆服务随时可以被其他进程、CLI 工具复用。安装与依赖pip install hindsight-all如果你的运行环境没有 LLM API 密钥也可以选择本地推理方案pip install hindsight-all[local-llm]该可选依赖通过hindsight-api-slim[local-llm]引入本地模型支持。仓库的测试套件还声明了test可选依赖pytest、pytest-asyncio用于运行 hindsight-all/tests 下的集成测试。环境要求为python 3.11。如果你已经有运行中的 Hindsight 服务器、只需要一个客户端那么应当直接使用 Python Clienthindsight-client无需引入整套嵌入式依赖。两种 API 形态HindsightServer 与 HindsightEmbeddedhindsight-all暴露两类主要 API二者最终都通过同一个HindsightClientHTTP 接口与同一个底层 daemon 通信区别只在于服务器进程由谁管理API生命周期管理适用场景HindsightServer显式进入上下文即启动退出即关闭测试、短生命周期脚本要求确定性的启停HindsightEmbedded自动首次调用启动跨调用复用空闲自动退出长期运行的应用不想关心生命周期下面分别深入讲解。HindsightServer显式生命周期上下文管理器HindsightServer作为上下文管理器使用进入with块时立即启动服务退出时干净关闭非常适合测试和短脚本import os from hindsight import HindsightServer, HindsightClient with HindsightServer( llm_provideropenai, llm_modelgpt-4o-mini, llm_api_keyos.environ[OPENAI_API_KEY], ) as server: client HindsightClient(base_urlserver.url) client.retain(bank_idmy-bank, contentAlice works at Google) results client.recall(bank_idmy-bank, queryWhat does Alice do?) for r in results: print(r.text) answer client.reflect(bank_idmy-bank, queryTell me about Alice) print(answer.text) # Server is stopped here从源码看hindsight-all/hindsight/server.py 中的Server类提供了完整的生命周期实现启动start(timeout30.0)在一个后台守护线程threading.Thread(daemonTrue)中创建MemoryEngine、构建 FastAPI 应用create_app、并启动 uvicorn 服务器。启动后通过socket.create_connection轮询确认端口已就绪才返回超时则抛出RuntimeError。端口默认通过_find_free_port()自动选择一个空闲端口无需手动指定也可以通过port参数固定端口。停止stop()将uvicorn.Server.should_exit置为 True等待线程退出默认最多 10 秒并完成MemoryEngine.close()清理。URLserver.url属性返回http://{host}:{port}默认绑定127.0.0.1。Server的完整构造参数也是start_server便捷函数接受的参数如下参数默认值说明db_urlpg0数据库 URLpg0表示使用嵌入式 PostgreSQLllm_providergroqLLM 提供商groq、openai、ollama、gemini、anthropic、lmstudio等llm_api_keyLLM 提供商 API 密钥llm_modelopenai/gpt-oss-120b使用的模型名llm_base_urlNone可选的 LLM API 自定义 base URLhost127.0.0.1服务绑定地址portNone绑定端口默认自动选择空闲端口mcp_enabledFalse是否启用 MCP 服务器log_levelinfoServer/warningstart_serveruvicorn 日志级别除了上下文管理器你还可以手动管理生命周期先用start_server(...)或Server(...).start()启动用完调用server.stop()hindsight-all/README.md 的 Quick Start 展示了这种写法。HindsightEmbedded自动托管开箱即用HindsightEmbedded是 Hindsight 在 Python 中使用的最简方式。它自动管理后台 daemon首次调用时启动之后跨调用复用同一个 daemon空闲后自动退出你也可以调用close(stop_daemonTrue)显式停止。from hindsight import HindsightEmbedded import os # Server starts automatically on first call client HindsightEmbedded( profilemyapp, # Profile for data isolation llm_provideropenai, llm_modelgpt-4o-mini, llm_api_keyos.environ[OPENAI_API_KEY], ) # Use immediately - no manual server management needed client.retain(bank_idmy-bank, contentAlice works at Google) results client.recall(bank_idmy-bank, queryWhat does Alice do?) # Server continues running (auto-stops after idle timeout) # Or explicitly stop it: client.close(stop_daemonTrue)HindsightEmbedded的构造参数非常灵活见 hindsight-all/hindsight/embedded.py。关键设计是你显式传入的设置才会被转发给 daemon未指定的参数全部交给 daemon 按序解析——先查 Profile 的.env文件再查父进程环境变量最后使用 daemon 自身默认值。这意味着你可以构造一个不带凭据的客户端让它直接复用某个已配置好凭据的 Profile 或 shell 环境而不会被占位符覆盖源码注释中引用了 issue #3253 的设计约束。重要参数说明参数默认值说明profiledefaultProfile 名称用于数据隔离llm_providerNone继承LLM 提供商省略则继承服务器默认openaillm_api_keyNone继承API 密钥省略则继承显式传表示明确运行在无密钥环境如本地免鉴权服务llm_modelNone继承模型名省略则继承服务器按已解析的提供商选默认模型llm_base_urlNone自定义 LLM API base URLdatabase_urlNone数据库 URL 覆盖项默认使用 Profile 专属 pg0idle_timeout已弃用并被忽略daemon 不再因空闲自动退出保留参数仅为兼容旧调用方log_levelNone继承daemon 日志级别daemon 默认infouiFalse是否随 daemon 一同启动控制平面 Web UIui_portNoneUI 端口默认daemon_port 10000ui_hostname0.0.0.0UI 绑定主机名内部实现上HindsightEmbedded通过get_embed_manager()来自hindsight-embed包获得DaemonEmbedManager其配置以HINDSIGHT_API_LLM_PROVIDER、HINDSIGHT_API_LLM_API_KEY、HINDSIGHT_API_LLM_MODEL等环境变量键的形式传给 daemon。什么是 ProfileProfile 是一个隔离的 Hindsight 环境。每个 Profile 拥有自己的嵌入式 PostgreSQL 数据库存储在~/.pg0/instances/hindsight-embed-{profile}/自己的 API 服务器进程。因此可以用不同 Profile 来隔离开发/生产环境、不同应用甚至不同用户的数据。仓库中的集成测试 hindsight-all/tests/test_embedded.py 中的test_embedded_profile_isolation验证了这一点两个不同 Profile 使用相同的bank_id各自写入内容互相看不到对方的数据。HindsightEmbedded与hindsight-embedCLI 共享同一套 daemon 管理接口和 Profile 存储因此可以放心地与 CLI 工具混用同一份 Profile 数据。何时选择哪种使用场景选择测试、短生命周期脚本、需要确定性启停HindsightServer上下文管理器长期运行的应用、首次使用自动启动、不想管理生命周期HindsightEmbedded已有运行中的 Hindsight 服务器直接使用 hindsight-clientAPI 命名空间组织化的银行、心智模型、指令与记忆操作HindsightEmbedded和HindsightClient都暴露了组织化的 API 命名空间用于银行Bank管理、心智模型Mental Models、指令Directives和记忆Memoriesfrom hindsight import HindsightEmbedded import os embedded HindsightEmbedded( profilemyapp, llm_provideropenai, llm_api_keyos.environ[OPENAI_API_KEY], ) # Core operations embedded.retain(bank_idtest, contentHello) results embedded.recall(bank_idtest, queryHello) # Bank management embedded.banks.create(bank_idtest, nameTest Bank, missionHelp users) embedded.banks.set_mission(bank_idtest, missionUpdated mission) embedded.banks.delete(bank_idtest) # Mental models embedded.mental_models.create( bank_idtest, nameUser Preferences, contentUser prefers dark mode ) models embedded.mental_models.list(bank_idtest) # Directives embedded.directives.create( bank_idtest, nameResponse Style, contentBe concise and friendly ) directives embedded.directives.list(bank_idtest) # List memories memories embedded.memories.list(bank_idtest, typeworld, limit50)这些命名空间由 hindsight-all/hindsight/api_namespaces.py 中的四个类实现BanksAPI、MentalModelsAPI、DirectivesAPI、MemoriesAPI在 hindsight-all/hindsight/client_wrapper.py 中还有一套绑定在HindsightClient上的同名实现。每个命名空间的方法签名与底层客户端方法一一对应bankscreate(bank_id, nameNone, missionNone, dispositionNone)、delete(bank_id)、set_mission(bank_id, mission)、set_disposition(bank_id, disposition)HindsightClient版本另有list()。mental_modelscreate(bank_id, name, content, tagsNone)、list(bank_id, tagsNone, detailNone)、get(bank_id, mental_model_id)、refresh(bank_id, mental_model_id)、update(...)、delete(...)。其中list()默认只返回元数据需要正文时传detailcontent。directivescreate(bank_id, name, content, tagsNone)、list(bank_id, tagsNone)、get(bank_id, directive_id)、update(...)、delete(...)。memorieslist(bank_id, typeNone, search_queryNone, limit100, offset0)支持按记忆类型过滤、文本搜索与分页。为什么推荐走命名空间而不是直接访问 client关键原因在于daemon 崩溃的优雅处理。命名空间的每个方法调用都会先执行_ensure_started()见 hindsight-all/hindsight/embedded.py它会检查 daemon 是否仍在运行若已崩溃则自动清理过期客户端并重启 daemon然后才发起真实 API 调用# ✅ GOOD - Uses API namespace (daemon restarts handled) embedded.banks.create(bank_idtest, nameTest) # ❌ BAD - Direct client access (daemon crashes NOT handled) client embedded.client client.create_bank(bank_idtest, nameTest) # Fails if daemon crashed这一点有测试直接背书hindsight-all/tests/test_embedded_namespaces.py 中的test_daemon_restart_handling模拟了“daemon 崩溃→清除客户端→再次调用”的场景验证命名空间方法能透明地重启 daemon 并继续工作test_multiple_calls_ensure_daemon_each_time则确认每次命名空间调用都会执行_ensure_started()。此外 hindsight-all/tests/test_embedded.py 的test_embedded_daemon_crash_recovery通过client._manager.stop(profile)模拟真实崩溃随后下一次retain调用自动重启 daemon 并成功写入数据。需要注意的是HindsightEmbedded的普通方法代理__getattr__同样会在调用前执行_ensure_started()所以直接调用client.retain(...)也具有崩溃恢复能力真正危险的是先通过embedded.client拿到底层Hindsight客户端引用再保存下来使用——该引用在 daemon 崩溃后不会自动刷新。完整工作流示例从建库到反思结合仓库测试 hindsight-all/tests/test_embedded.py 中的test_embedded_complete_workflow一个典型的完整工作流如下client HindsightEmbedded(profilemyapp, llm_provideropenai, llm_api_keyos.environ[OPENAI_API_KEY]) # 1. 创建记忆银行 client.create_bank(bank_idassistant, nameTest Assistant, missionHelp with programming tasks) # 2. 存储单条记忆 client.retain(bank_idassistant, contentUser prefers Python for data analysis., contextProgramming preferences) # 3. 批量存储记忆 client.retain_batch(bank_idassistant, items[ {content: User works with pandas and numpy.}, {content: User likes matplotlib for visualization.}, {content: User is interested in machine learning with scikit-learn.}, ]) # 4. 检索记忆 results client.recall(bank_idassistant, queryWhat tools does the user prefer?, max_tokens2000) # 5. 反思基于记忆生成上下文回答 answer client.reflect(bank_idassistant, queryWhat programming tools should I recommend?, budgetlow) # 6. 列出记忆 client.list_memories(bank_idassistant, limit10) client.close()retain/recall/reflect的完整参数参考无论客户端以何种方式获得行为一致见 Python Client 页面例如retain支持context、timestamp、document_id、metadata、retain_asyncrecall支持types、max_tokens、budgetlow/mid/high、include_chunksreflect支持budget与context所有方法都有以a前缀开头的异步版本aretain、arecall、areflect等。进阶上下文管理器与 UI 控制平面HindsightEmbedded同样支持上下文管理器退出时自动调用close()from hindsight import HindsightEmbedded with HindsightEmbedded(profilemyapp) as client: client.retain(bank_idalice, contentAlice loves AI) # Daemon managed automatically如果你希望记忆服务同时附带可视化控制平面可以设置uiTrue并可选ui_port、ui_hostname。测试 hindsight-all/tests/test_embedded.py 中的test_embedded_ui_flag验证了启用 UI 后首次调用会同时拉起 daemon 和 UI且 UI 的健康检查端点{ui_url}/api/health返回status: ok且dataplane.status: connected说明数据平面已成功连接。最佳实践小结测试与短脚本用HindsightServer上下文管理器确定性的启停让测试互不干扰server.url可直接注入HindsightClient。应用代码用HindsightEmbedded懒启动 跨调用复用 空闲自动退出配合命名空间获得 daemon 崩溃自愈能力。用 Profile 做环境隔离dev/prod、不同应用或不同用户各用一个 Profile数据库与服务器进程完全隔离存储于~/.pg0/instances/hindsight-embed-{profile}/。优先走 API 命名空间embedded.banks、embedded.mental_models等避免长期保存embedded.client裸引用。无密钥本地服务将llm_api_key显式传可清除继承的 API 密钥配合本地 LLM 服务如ollama、lmstudio使用。省略参数即继承构造HindsightEmbedded时未显式给出的配置会按“Profile.env→ 父进程环境变量 → daemon 默认值”的顺序解析适合复用已配置好的环境。从安装到生产级接入hindsight-all用一套依赖覆盖了 API 服务、嵌入式 PostgreSQL 与类型化客户端让“Agent 记忆”真正成为应用里随手可用的本地基础设施。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考