hindsight-embed 完全指南零配置的 Hindsight 本地记忆守护进程Daemon CLI【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读本文讲解 Hindsight 项目的hindsight-embed又名 Daemon CLI一个把 Hindsight API 服务与 PostgreSQL 数据库封装进单个自动托管本地守护进程的零配置 SDK。它面向开发调试、原型验证和单用户应用让你像使用 SQLite 一样使用长期记忆——无需自己安装 PostgreSQL、无需手动启动服务一条configure命令即可开始 retain / recall / reflect。读完本文你将掌握它的安装方式、配置流程、守护进程与本地控制中心的完整生命周期管理命令以及故障排查方法并能理解它背后的自动托管原理源码级证据见 hindsight-embed 包 与 daemon_embed_manager.py。概述SQLite 式的长期记忆体验hindsight-embed的核心价值在于零配置 自动生命周期。它的工作流程可以概括为五步首次命令触发启动执行任意hindsight-embed命令时它会先检查本地守护进程是否已在运行守护进程自动托管如果守护进程不存在它会自动在后台拉起hindsight-api --daemon嵌入式数据库守护进程使用pg0嵌入式 PostgreSQL作为存储无需单独安装数据库命令转发你的命令通过 HTTPlocalhost:8888转发给本地守护进程执行自动关机空闲超过 5 分钟可配置后守护进程会优雅退出以释放资源。注意版本差异当前仓库中 daemon_embed_manager.py 的DEFAULT_DAEMON_IDLE_TIMEOUT 0禁用自动退出即当前源码实现下守护进程不会自行退出——长 retain / reflect / consolidation 任务不会被中途打断。文档中5 分钟空闲自动退出是早期行为描述实际行为以当前源码为准。关键特性零安装成本——一条configure命令即可就绪自动生命周期——守护进程按需启动并被所有客户端共享存储隔离——每个 bank记忆库拥有独立的嵌入式 PostgreSQL 数据库实例仅本机可访问——守护进程只绑定127.0.0.1:8888不对外网开放生产级引擎——底层复用与完整 API 服务完全相同的记忆引擎retain / recall / reflect / consolidation 全链路。用一句话概括拥有 Hindsight 的全部能力却不需要你管理任何服务器。安装推荐通过uvx安装始终使用最新版本无需预先安装# 直接运行无需安装 uvx hindsight-embedlatest configure # 或使用 pipx 进行持久化安装 pipx install hindsight-embed从源码看pyproject.toml 中hindsight-embed的包版本为0.9.2Python 要求3.11运行时依赖仅aiohttp与rich两个轻量库控制台脚本入口为hindsight_embed.cli:main。快速开始1. 配置configure# 交互式配置 hindsight-embed configure # 或通过环境变量进行非交互式配置 export HINDSIGHT_API_LLM_PROVIDERopenai export HINDSIGHT_API_LLM_API_KEYsk-xxxxxxxxxxxx export HINDSIGHT_API_LLM_MODELgpt-4o-mini hindsight-embed configure配置会保存到~/.hindsight/embedHINDSIGHT_API_LLM_PROVIDERopenai HINDSIGHT_API_LLM_MODELgpt-4o-mini HINDSIGHT_API_LLM_API_KEYsk-xxxxxxxxxxxx # 守护进程设置macOS强制 CPU 以避免 MPS/XPC 问题 HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU1 HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU1源码级说明配置文件的渲染并非简单写死四个键。根据 env_template.pyhindsight-embed configure会从包内自带的 env.example 模板生成配置文件用户显式设置的键保持激活其余模板中的完整可选项全部以注释形式保留Everything is commented out by default: only the keys the user explicitly set are active写盘后还会chmod 0o600收紧权限。这意味着你随时可以打开~/.hindsight/embed查阅全部可配置项并手动放开注释。此外cli.py 中的_has_non_interactive_env()会检测环境中是否已有 API Key 或无需 Key 的 provider如ollama从而自动跳过交互式提示进入非交互模式方便 CI 场景使用。2. 使用记忆操作# 存储一条记忆 hindsight-embed memory retain default User prefers dark mode # 查询记忆 hindsight-embed memory recall default user preferences # 带记忆进行推理作答 hindsight-embed memory reflect default What color scheme should I use?守护进程会在首次使用时自动启动调用链解析这些memory子命令并非由 embed 包自身实现而是通过 daemon_client.py 的run_cli()转发给 Rust 编写的hindsightCLI。转发前会执行ensure_cli_installed()自动安装缺失的 CLI、ensure_daemon_running()确保守护进程已启动并把守护进程 URL 注入HINDSIGHT_API_URL环境变量。若你设置了HINDSIGHT_EMBED_API_URL则会跳过守护进程启动直接连接外部 API。3. 打开本地控制中心可选当需要浏览器端的配置向导与守护进程监视器时可以使用本地控制中心# 启动控制中心并自动打开浏览器 hindsight-embed control start # 或用浏览器向导替代终端交互完成配置 hindsight-embed configure --ui控制中心默认只监听本机http://localhost:7878并会打印一个带令牌的 URL。访问令牌保存在~/.hindsight/control.token日志写入~/.hindsight/control.log。# 为本次启动指定不同的控制中心端口 hindsight-embed control start --port 7879 # 启动但不自动打开浏览器 hindsight-embed control start --no-open # 检查、查看日志或停止控制中心 hindsight-embed control status hindsight-embed control logs -f hindsight-embed control stop注意控制中心与记忆守护进程是两个独立进程。停止或重启控制中心不会影响正在运行的守护进程源码见 cli.py 的do_control注释控制中心是persistent, localhost-only web app以独立分离进程运行可跨守护进程重启存活。控制中心的静态 SPA 资源随 wheel 打包分发见 pyproject.toml 的artifacts配置。环境变量变量说明默认值HINDSIGHT_API_LLM_API_KEY必需。LLM 提供商的 API Key-HINDSIGHT_API_LLM_PROVIDERLLM 提供商openai、anthropic、gemini、groq、minimax、ollama等openaiHINDSIGHT_API_LLM_MODEL模型名称gpt-4o-miniHINDSIGHT_EMBED_DAEMON_LOG_MAX_BYTES守护进程日志达到该大小时在启动时轮转0表示禁用轮转1048576010 MiBHINDSIGHT_EMBED_DAEMON_LOG_BACKUP_COUNT保留的备份数量0表示启动时直接截断满日志3日志轮转的边界行为大小只在守护进程启动时检查因此一次不间断的运行绝不会被截断可以增长超过MAX_BYTES——下一次启动时整个文件会被保留为第一个备份。因此保留的总大小约为MAX_BYTES × (BACKUP_COUNT 1)默认约 40 MiB且仅对定期重启的守护进程有效连续运行数周的守护进程会保留其写入的全部日志。想要维持有意义的边界请重启守护进程。实现细节见 daemon_embed_manager.py 的_rotate_daemon_log它仅在启动时、且在 profile 锁内执行轮转避免子进程写入被重命名的 inode。Provider 配置示例# OpenAI export HINDSIGHT_API_LLM_PROVIDERopenai export HINDSIGHT_API_LLM_API_KEYsk-xxxxxxxxxxxx export HINDSIGHT_API_LLM_MODELgpt-4o # Groq快速推理 export HINDSIGHT_API_LLM_PROVIDERgroq export HINDSIGHT_API_LLM_API_KEYgsk_xxxxxxxxxxxx export HINDSIGHT_API_LLM_MODELllama-3.3-70b-versatile # Anthropic export HINDSIGHT_API_LLM_PROVIDERanthropic export HINDSIGHT_API_LLM_API_KEYsk-ant-xxxxxxxxxxxx export HINDSIGHT_API_LLM_MODELclaude-sonnet-4-20250514从源码看更多的 provider 与细节env.example 列出完整支持列表openai, openai-responses, groq, ollama, gemini, anthropic, lmstudio, vertexai, minimax, deepseek, zai, atlas, meta, volcano, openai-codex, claude-code, github-copilotcli.py 中定义了交互菜单的 provider 与 API Key 环境变量映射openai→OPENAI_API_KEY、groq→GROQ_API_KEY、gemini→GEMINI_API_KEY而ollama、vertexai、github-copilot无需 API Key此外get_config()cli.py会原样转发所有HINDSIGHT_*环境变量给守护进程不做白名单过滤——这是为了避免出现白名单漏掉新配置项导致设置被静默忽略如历史上HINDSIGHT_API_LLM_BASE_URL被丢弃的问题OPENAI_API_KEY是唯一被额外尊重的非HINDSIGHT_变量名。守护进程管理守护进程会一直运行直到你手动停止——它不会自行退出因此长时间的 retain、reflect 或 consolidation 任务永远不会被中途切断这正是当前源码DEFAULT_DAEMON_IDLE_TIMEOUT 0的设计意图见 daemon_embed_manager.py。守护进程命令# 查看守护进程状态 hindsight-embed daemon status # 实时查看守护进程日志 hindsight-embed daemon logs -f # 手动停止守护进程 hindsight-embed daemon stop守护进程日志默认位于~/.hindsight/daemon.log。daemon status会显示运行 URL、日志路径并在使用 pg0 时给出数据库实例路径形如~/.pg0/instances/name见 cli.py。源码级健壮性细节daemon stop并非简单杀进程。根据 daemon_embed_manager.py停止逻辑严格基于端口占用而非健康探测一个活着但繁忙的守护进程会通不过响应性探测导致误报已停止且只会向命令行中带有hindsight-api/hindsight_api标记的进程发送 SIGTERM拒绝信号任何仅占用端口但无法识别为 Hindsight 的进程避免误杀同端口上的无关服务。并发启动则由 profile 锁文件flock串行化第二个并发调用者会等待锁并复用第一个调用者已启动的守护进程。回收磁盘空间当守护进程通过uvx启动时npm 包和编辑器插件的默认方式Hindsight 每运行过一个版本都会缓存一份独立的 Python 环境——每个约1.5 GB且不会被自动清理。磁盘紧张时请先停止守护进程再清理缓存未使用的缓存条目只有在没有守护进程运行时才能被回收。hindsight-embed daemon stop uv cache prune hindsight-embed daemon status # 以当前版本重新启动全新环境控制中心命令# 启动或复用本地浏览器控制中心 hindsight-embed control start # 检查它是否在运行 hindsight-embed control status # 查看控制中心日志 hindsight-embed control logs -f # 停止控制中心进程 hindsight-embed control stop命令参考所有记忆操作与 CLI 保持同一套接口即最终转发给hindsightRust CLI 执行。Retain存储记忆hindsight-embed memory retain bank_id content # 携带上下文 hindsight-embed memory retain bank_id content --context source information # 后台异步处理 hindsight-embed memory retain bank_id content --asyncRecall搜索hindsight-embed memory recall bank_id query # 预算控制 hindsight-embed memory recall bank_id query --budget high # 显示检索链路追踪 hindsight-embed memory recall bank_id query --traceReflect生成回答hindsight-embed memory reflect bank_id prompt # 携带额外上下文 hindsight-embed memory reflect bank_id prompt --context additional infoBank 管理# 列出所有 bank hindsight-embed bank list # 查看 bank 统计 hindsight-embed bank stats bank_id # 设置 bank 名称 hindsight-embed bank name bank_id My Assistant # 设置 bank 使命mission hindsight-embed bank mission bank_id I am a helpful AI assistant配置 Profiles多环境隔离除了默认的~/.hindsight/embed配置外hindsight-embed还支持命名 profile让每个 profile 拥有独立的配置、独立的守护进程与独立端口8889-9888适合为不同项目、不同 API 端点或不同 LLM provider 维护多套环境# 用一条命令创建命名 profile hindsight-embed configure --profile my-app \ --env HINDSIGHT_API_LLM_PROVIDERopenai \ --env HINDSIGHT_API_LLM_API_KEYsk-xxx \ --env HINDSIGHT_API_LLM_MODELgpt-4o-mini # 或交互式创建 hindsight-embed configure --profile staging # 三种使用方式环境变量 / CLI 标志 / 持久化激活 HINDSIGHT_EMBED_PROFILEmy-app hindsight-embed memory retain default text hindsight-embed --profile my-app memory recall default query hindsight-embed profile set-active my-app # 管理 hindsight-embed profile list hindsight-embed profile show hindsight-embed profile delete my-appProfile 解析优先级①HINDSIGHT_EMBED_PROFILE环境变量 ②--profileCLI 标志 ③~/.hindsight/active_profile文件中的激活 profile ④ 默认 profile。指定的 profile 若不存在命令会直接报错必须先用configure --profile name显式创建。连接外部 API / 外部数据库若不想启动本地守护进程可以直连已有的 Hindsight API 服务export HINDSIGHT_EMBED_API_URLhttp://your-server:8000 export HINDSIGHT_EMBED_API_TOKENyour-api-token # 可选API 需要鉴权时使用 hindsight-embed memory recall default query在 root 用户或容器化环境下pg0 嵌入式数据库不可用可以改用外部 PostgreSQLexport HINDSIGHT_EMBED_API_DATABASE_URLpostgresql://user:passwordlocalhost:5432/dbname hindsight-embed daemon start注意所有 bank 共享同一个数据库bank 之间的隔离发生在数据库内部通过传给 CLI 命令的bank_id参数实现。故障排查守护进程无法启动先查看守护进程日志hindsight-embed daemon logs # 或实时跟踪 hindsight-embed daemon logs -f常见问题缺少 API Key设置HINDSIGHT_API_LLM_API_KEY端口冲突有其他服务占用了 8888 端口权限问题检查~/.hindsight/目录权限。源码级提示daemon status中的日志路径与 pg0 数据库路径可以直接定位问题。若端口被占用启动逻辑会先等待健康宽限期默认 30 秒见 daemon_embed_manager.py 的HINDSIGHT_EMBED_PORT_HEALTH_GRACE_TIMEOUT确认监听者确实不是 Hindsight 守护进程后才拒绝启动不会误伤其他服务。守护进程立即退出守护进程从不自行停止因此退出必然意味着崩溃或启动失败。检查日志hindsight-embed daemon status tail -n 100 ~/.hindsight/daemon.log首次命令很慢这是预期行为首次命令需要下载依赖、启动守护进程并加载 ML 模型视网络速度约需1-3 分钟后续命令因守护进程已就绪会非常快约 1-2 秒。这一首启慢、后续快的机制在 hindsight-embed/README.md 中有明确说明并对应源码中DAEMON_STARTUP_TIMEOUT默认 180 秒可通过HINDSIGHT_EMBED_DAEMON_STARTUP_TIMEOUT调整见 daemon_embed_manager.py的启动等待上限。重置配置# 删除配置文件后重新配置 rm ~/.hindsight/embed hindsight-embed configure何时使用 hindsight-embed适合开发与原型验证单用户应用本地优先local-first工具快速体验 Hindsight 的实验不适合生产环境的多用户部署需要对外网开放的服务高可用性要求多租户应用生产部署请改用 API 服务 外部 PostgreSQLAPI 服务是核心记忆引擎retain 摄取内容并抽取事实、构建知识图谱recall 进行跨记忆语义搜索reflect 进行基于 disposition 的答案生成支持水平扩展与独立 worker 进程而 embed 的守护进程形态天然限定在单机单用户场景。小结hindsight-embed把 Hindsight 完整的记忆引擎retain / recall / reflect / consolidation压缩进了一个随用随启、自动托管、本机私有的守护进程形态一条命令起步uvx hindsight-embedlatest configure即可完成 LLM 配置零基础设施pg0 嵌入式数据库 自动启动的hindsight-api --daemon全部落在本机与生产同源底层是同一个记忆引擎只是运行形态不同可平滑过渡到 API 服务 部署方案可观测可治理daemon/control/profile三套子命令覆盖了守护进程、浏览器控制中心与多环境 profile 的完整生命周期。它最适合作为开发期的记忆后端——无论是为 AI 编码助手、原型应用还是本地工具快速接入长期记忆都能在几分钟内跑通全流程且不会向网络暴露任何端口。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
hindsight-embed 完全指南：零配置的 Hindsight 本地记忆守护进程（Daemon CLI）
hindsight-embed 完全指南零配置的 Hindsight 本地记忆守护进程Daemon CLI【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读本文讲解 Hindsight 项目的hindsight-embed又名 Daemon CLI一个把 Hindsight API 服务与 PostgreSQL 数据库封装进单个自动托管本地守护进程的零配置 SDK。它面向开发调试、原型验证和单用户应用让你像使用 SQLite 一样使用长期记忆——无需自己安装 PostgreSQL、无需手动启动服务一条configure命令即可开始 retain / recall / reflect。读完本文你将掌握它的安装方式、配置流程、守护进程与本地控制中心的完整生命周期管理命令以及故障排查方法并能理解它背后的自动托管原理源码级证据见 hindsight-embed 包 与 daemon_embed_manager.py。概述SQLite 式的长期记忆体验hindsight-embed的核心价值在于零配置 自动生命周期。它的工作流程可以概括为五步首次命令触发启动执行任意hindsight-embed命令时它会先检查本地守护进程是否已在运行守护进程自动托管如果守护进程不存在它会自动在后台拉起hindsight-api --daemon嵌入式数据库守护进程使用pg0嵌入式 PostgreSQL作为存储无需单独安装数据库命令转发你的命令通过 HTTPlocalhost:8888转发给本地守护进程执行自动关机空闲超过 5 分钟可配置后守护进程会优雅退出以释放资源。注意版本差异当前仓库中 daemon_embed_manager.py 的DEFAULT_DAEMON_IDLE_TIMEOUT 0禁用自动退出即当前源码实现下守护进程不会自行退出——长 retain / reflect / consolidation 任务不会被中途打断。文档中5 分钟空闲自动退出是早期行为描述实际行为以当前源码为准。关键特性零安装成本——一条configure命令即可就绪自动生命周期——守护进程按需启动并被所有客户端共享存储隔离——每个 bank记忆库拥有独立的嵌入式 PostgreSQL 数据库实例仅本机可访问——守护进程只绑定127.0.0.1:8888不对外网开放生产级引擎——底层复用与完整 API 服务完全相同的记忆引擎retain / recall / reflect / consolidation 全链路。用一句话概括拥有 Hindsight 的全部能力却不需要你管理任何服务器。安装推荐通过uvx安装始终使用最新版本无需预先安装# 直接运行无需安装 uvx hindsight-embedlatest configure # 或使用 pipx 进行持久化安装 pipx install hindsight-embed从源码看pyproject.toml 中hindsight-embed的包版本为0.9.2Python 要求3.11运行时依赖仅aiohttp与rich两个轻量库控制台脚本入口为hindsight_embed.cli:main。快速开始1. 配置configure# 交互式配置 hindsight-embed configure # 或通过环境变量进行非交互式配置 export HINDSIGHT_API_LLM_PROVIDERopenai export HINDSIGHT_API_LLM_API_KEYsk-xxxxxxxxxxxx export HINDSIGHT_API_LLM_MODELgpt-4o-mini hindsight-embed configure配置会保存到~/.hindsight/embedHINDSIGHT_API_LLM_PROVIDERopenai HINDSIGHT_API_LLM_MODELgpt-4o-mini HINDSIGHT_API_LLM_API_KEYsk-xxxxxxxxxxxx # 守护进程设置macOS强制 CPU 以避免 MPS/XPC 问题 HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU1 HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU1源码级说明配置文件的渲染并非简单写死四个键。根据 env_template.pyhindsight-embed configure会从包内自带的 env.example 模板生成配置文件用户显式设置的键保持激活其余模板中的完整可选项全部以注释形式保留Everything is commented out by default: only the keys the user explicitly set are active写盘后还会chmod 0o600收紧权限。这意味着你随时可以打开~/.hindsight/embed查阅全部可配置项并手动放开注释。此外cli.py 中的_has_non_interactive_env()会检测环境中是否已有 API Key 或无需 Key 的 provider如ollama从而自动跳过交互式提示进入非交互模式方便 CI 场景使用。2. 使用记忆操作# 存储一条记忆 hindsight-embed memory retain default User prefers dark mode # 查询记忆 hindsight-embed memory recall default user preferences # 带记忆进行推理作答 hindsight-embed memory reflect default What color scheme should I use?守护进程会在首次使用时自动启动调用链解析这些memory子命令并非由 embed 包自身实现而是通过 daemon_client.py 的run_cli()转发给 Rust 编写的hindsightCLI。转发前会执行ensure_cli_installed()自动安装缺失的 CLI、ensure_daemon_running()确保守护进程已启动并把守护进程 URL 注入HINDSIGHT_API_URL环境变量。若你设置了HINDSIGHT_EMBED_API_URL则会跳过守护进程启动直接连接外部 API。3. 打开本地控制中心可选当需要浏览器端的配置向导与守护进程监视器时可以使用本地控制中心# 启动控制中心并自动打开浏览器 hindsight-embed control start # 或用浏览器向导替代终端交互完成配置 hindsight-embed configure --ui控制中心默认只监听本机http://localhost:7878并会打印一个带令牌的 URL。访问令牌保存在~/.hindsight/control.token日志写入~/.hindsight/control.log。# 为本次启动指定不同的控制中心端口 hindsight-embed control start --port 7879 # 启动但不自动打开浏览器 hindsight-embed control start --no-open # 检查、查看日志或停止控制中心 hindsight-embed control status hindsight-embed control logs -f hindsight-embed control stop注意控制中心与记忆守护进程是两个独立进程。停止或重启控制中心不会影响正在运行的守护进程源码见 cli.py 的do_control注释控制中心是persistent, localhost-only web app以独立分离进程运行可跨守护进程重启存活。控制中心的静态 SPA 资源随 wheel 打包分发见 pyproject.toml 的artifacts配置。环境变量变量说明默认值HINDSIGHT_API_LLM_API_KEY必需。LLM 提供商的 API Key-HINDSIGHT_API_LLM_PROVIDERLLM 提供商openai、anthropic、gemini、groq、minimax、ollama等openaiHINDSIGHT_API_LLM_MODEL模型名称gpt-4o-miniHINDSIGHT_EMBED_DAEMON_LOG_MAX_BYTES守护进程日志达到该大小时在启动时轮转0表示禁用轮转1048576010 MiBHINDSIGHT_EMBED_DAEMON_LOG_BACKUP_COUNT保留的备份数量0表示启动时直接截断满日志3日志轮转的边界行为大小只在守护进程启动时检查因此一次不间断的运行绝不会被截断可以增长超过MAX_BYTES——下一次启动时整个文件会被保留为第一个备份。因此保留的总大小约为MAX_BYTES × (BACKUP_COUNT 1)默认约 40 MiB且仅对定期重启的守护进程有效连续运行数周的守护进程会保留其写入的全部日志。想要维持有意义的边界请重启守护进程。实现细节见 daemon_embed_manager.py 的_rotate_daemon_log它仅在启动时、且在 profile 锁内执行轮转避免子进程写入被重命名的 inode。Provider 配置示例# OpenAI export HINDSIGHT_API_LLM_PROVIDERopenai export HINDSIGHT_API_LLM_API_KEYsk-xxxxxxxxxxxx export HINDSIGHT_API_LLM_MODELgpt-4o # Groq快速推理 export HINDSIGHT_API_LLM_PROVIDERgroq export HINDSIGHT_API_LLM_API_KEYgsk_xxxxxxxxxxxx export HINDSIGHT_API_LLM_MODELllama-3.3-70b-versatile # Anthropic export HINDSIGHT_API_LLM_PROVIDERanthropic export HINDSIGHT_API_LLM_API_KEYsk-ant-xxxxxxxxxxxx export HINDSIGHT_API_LLM_MODELclaude-sonnet-4-20250514从源码看更多的 provider 与细节env.example 列出完整支持列表openai, openai-responses, groq, ollama, gemini, anthropic, lmstudio, vertexai, minimax, deepseek, zai, atlas, meta, volcano, openai-codex, claude-code, github-copilotcli.py 中定义了交互菜单的 provider 与 API Key 环境变量映射openai→OPENAI_API_KEY、groq→GROQ_API_KEY、gemini→GEMINI_API_KEY而ollama、vertexai、github-copilot无需 API Key此外get_config()cli.py会原样转发所有HINDSIGHT_*环境变量给守护进程不做白名单过滤——这是为了避免出现白名单漏掉新配置项导致设置被静默忽略如历史上HINDSIGHT_API_LLM_BASE_URL被丢弃的问题OPENAI_API_KEY是唯一被额外尊重的非HINDSIGHT_变量名。守护进程管理守护进程会一直运行直到你手动停止——它不会自行退出因此长时间的 retain、reflect 或 consolidation 任务永远不会被中途切断这正是当前源码DEFAULT_DAEMON_IDLE_TIMEOUT 0的设计意图见 daemon_embed_manager.py。守护进程命令# 查看守护进程状态 hindsight-embed daemon status # 实时查看守护进程日志 hindsight-embed daemon logs -f # 手动停止守护进程 hindsight-embed daemon stop守护进程日志默认位于~/.hindsight/daemon.log。daemon status会显示运行 URL、日志路径并在使用 pg0 时给出数据库实例路径形如~/.pg0/instances/name见 cli.py。源码级健壮性细节daemon stop并非简单杀进程。根据 daemon_embed_manager.py停止逻辑严格基于端口占用而非健康探测一个活着但繁忙的守护进程会通不过响应性探测导致误报已停止且只会向命令行中带有hindsight-api/hindsight_api标记的进程发送 SIGTERM拒绝信号任何仅占用端口但无法识别为 Hindsight 的进程避免误杀同端口上的无关服务。并发启动则由 profile 锁文件flock串行化第二个并发调用者会等待锁并复用第一个调用者已启动的守护进程。回收磁盘空间当守护进程通过uvx启动时npm 包和编辑器插件的默认方式Hindsight 每运行过一个版本都会缓存一份独立的 Python 环境——每个约1.5 GB且不会被自动清理。磁盘紧张时请先停止守护进程再清理缓存未使用的缓存条目只有在没有守护进程运行时才能被回收。hindsight-embed daemon stop uv cache prune hindsight-embed daemon status # 以当前版本重新启动全新环境控制中心命令# 启动或复用本地浏览器控制中心 hindsight-embed control start # 检查它是否在运行 hindsight-embed control status # 查看控制中心日志 hindsight-embed control logs -f # 停止控制中心进程 hindsight-embed control stop命令参考所有记忆操作与 CLI 保持同一套接口即最终转发给hindsightRust CLI 执行。Retain存储记忆hindsight-embed memory retain bank_id content # 携带上下文 hindsight-embed memory retain bank_id content --context source information # 后台异步处理 hindsight-embed memory retain bank_id content --asyncRecall搜索hindsight-embed memory recall bank_id query # 预算控制 hindsight-embed memory recall bank_id query --budget high # 显示检索链路追踪 hindsight-embed memory recall bank_id query --traceReflect生成回答hindsight-embed memory reflect bank_id prompt # 携带额外上下文 hindsight-embed memory reflect bank_id prompt --context additional infoBank 管理# 列出所有 bank hindsight-embed bank list # 查看 bank 统计 hindsight-embed bank stats bank_id # 设置 bank 名称 hindsight-embed bank name bank_id My Assistant # 设置 bank 使命mission hindsight-embed bank mission bank_id I am a helpful AI assistant配置 Profiles多环境隔离除了默认的~/.hindsight/embed配置外hindsight-embed还支持命名 profile让每个 profile 拥有独立的配置、独立的守护进程与独立端口8889-9888适合为不同项目、不同 API 端点或不同 LLM provider 维护多套环境# 用一条命令创建命名 profile hindsight-embed configure --profile my-app \ --env HINDSIGHT_API_LLM_PROVIDERopenai \ --env HINDSIGHT_API_LLM_API_KEYsk-xxx \ --env HINDSIGHT_API_LLM_MODELgpt-4o-mini # 或交互式创建 hindsight-embed configure --profile staging # 三种使用方式环境变量 / CLI 标志 / 持久化激活 HINDSIGHT_EMBED_PROFILEmy-app hindsight-embed memory retain default text hindsight-embed --profile my-app memory recall default query hindsight-embed profile set-active my-app # 管理 hindsight-embed profile list hindsight-embed profile show hindsight-embed profile delete my-appProfile 解析优先级①HINDSIGHT_EMBED_PROFILE环境变量 ②--profileCLI 标志 ③~/.hindsight/active_profile文件中的激活 profile ④ 默认 profile。指定的 profile 若不存在命令会直接报错必须先用configure --profile name显式创建。连接外部 API / 外部数据库若不想启动本地守护进程可以直连已有的 Hindsight API 服务export HINDSIGHT_EMBED_API_URLhttp://your-server:8000 export HINDSIGHT_EMBED_API_TOKENyour-api-token # 可选API 需要鉴权时使用 hindsight-embed memory recall default query在 root 用户或容器化环境下pg0 嵌入式数据库不可用可以改用外部 PostgreSQLexport HINDSIGHT_EMBED_API_DATABASE_URLpostgresql://user:passwordlocalhost:5432/dbname hindsight-embed daemon start注意所有 bank 共享同一个数据库bank 之间的隔离发生在数据库内部通过传给 CLI 命令的bank_id参数实现。故障排查守护进程无法启动先查看守护进程日志hindsight-embed daemon logs # 或实时跟踪 hindsight-embed daemon logs -f常见问题缺少 API Key设置HINDSIGHT_API_LLM_API_KEY端口冲突有其他服务占用了 8888 端口权限问题检查~/.hindsight/目录权限。源码级提示daemon status中的日志路径与 pg0 数据库路径可以直接定位问题。若端口被占用启动逻辑会先等待健康宽限期默认 30 秒见 daemon_embed_manager.py 的HINDSIGHT_EMBED_PORT_HEALTH_GRACE_TIMEOUT确认监听者确实不是 Hindsight 守护进程后才拒绝启动不会误伤其他服务。守护进程立即退出守护进程从不自行停止因此退出必然意味着崩溃或启动失败。检查日志hindsight-embed daemon status tail -n 100 ~/.hindsight/daemon.log首次命令很慢这是预期行为首次命令需要下载依赖、启动守护进程并加载 ML 模型视网络速度约需1-3 分钟后续命令因守护进程已就绪会非常快约 1-2 秒。这一首启慢、后续快的机制在 hindsight-embed/README.md 中有明确说明并对应源码中DAEMON_STARTUP_TIMEOUT默认 180 秒可通过HINDSIGHT_EMBED_DAEMON_STARTUP_TIMEOUT调整见 daemon_embed_manager.py的启动等待上限。重置配置# 删除配置文件后重新配置 rm ~/.hindsight/embed hindsight-embed configure何时使用 hindsight-embed适合开发与原型验证单用户应用本地优先local-first工具快速体验 Hindsight 的实验不适合生产环境的多用户部署需要对外网开放的服务高可用性要求多租户应用生产部署请改用 API 服务 外部 PostgreSQLAPI 服务是核心记忆引擎retain 摄取内容并抽取事实、构建知识图谱recall 进行跨记忆语义搜索reflect 进行基于 disposition 的答案生成支持水平扩展与独立 worker 进程而 embed 的守护进程形态天然限定在单机单用户场景。小结hindsight-embed把 Hindsight 完整的记忆引擎retain / recall / reflect / consolidation压缩进了一个随用随启、自动托管、本机私有的守护进程形态一条命令起步uvx hindsight-embedlatest configure即可完成 LLM 配置零基础设施pg0 嵌入式数据库 自动启动的hindsight-api --daemon全部落在本机与生产同源底层是同一个记忆引擎只是运行形态不同可平滑过渡到 API 服务 部署方案可观测可治理daemon/control/profile三套子命令覆盖了守护进程、浏览器控制中心与多环境 profile 的完整生命周期。它最适合作为开发期的记忆后端——无论是为 AI 编码助手、原型应用还是本地工具快速接入长期记忆都能在几分钟内跑通全流程且不会向网络暴露任何端口。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考