Hindsight Node.js 内嵌守护进程指南用 vectorize-io/hindsight-all 在 Node 应用中启动本地 Hindsight【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightvectorize-io/hindsight-all是 Hindsight 官方提供的 Node.js 程序化生命周期管理包它让你无需部署任何服务器基础设施就能在 Node 应用中拉起并监管一个本地 Hindsight 守护进程daemon再配合vectorize-io/hindsight-client完成记忆的写入、检索与整理。读完本文你将掌握守护进程的启动/停止生命周期、全部HindsightServerOptions配置项的含义与默认值、以及如何把任意新的HINDSIGHT_API_*/HINDSIGHT_EMBED_*环境变量透传给守护进程而不等待包装包发版。核心定位进程管家而非 HTTP 客户端vectorize-io/hindsight-all是 Pythonhindsight-all包的 Node.js 等价物。两者职责一致只负责守护进程的生命周期不内置任何 HTTP 客户端。守护进程以独立的 OS 进程运行在127.0.0.1上不在你的 Node 进程内你的代码通过 HTTP 与它通信一旦守护进程就绪请用vectorize-io/hindsight-client指向server.getBaseUrl()执行 retain、recall、reflect 以及 bank 管理等记忆操作两个包天然组合一个包拥有进程另一个包拥有 API 表面。在 package.json 中本包被描述为嵌入式服务器embedded-server类库main指向dist/index.jsengines要求node 22。从包导出见 index.ts可以清晰看到它的全部公开面HindsightServer类、getEmbedCommand低层命令解析函数、silentLogger/consoleLogger两个日志助手以及Logger、EmbedCommandOptions、HindsightServerOptions三个类型。工作原理五步生命周期HindsightServer.start()在 server.ts 中的执行流程与文档描述完全一致解析底层命令通过getEmbedCommand()解析出hindsight-embed的调用方式——默认走uvx hindsight-embedversion从 PyPI 下载运行若设置了embedPackagePath则走uv run --directory path hindsight-embed针对本地 checkout配置 profile执行profile create name --merge --port port [--env KEYVALUE ...]把options.env中每一条都转发为--env见 configureProfile启动守护进程执行daemon --profile name start见 startDaemon健康探测轮询http://host:port/health直到返回200或耗尽readyTimeoutMs预算见 waitForReady每次探测使用AbortSignal.timeout(readyPollIntervalMs)超时停止server.stop()执行daemon --profile name stop即使失败也永不抛出异常仅在超时 5 秒后记录警告并 resolve见 stop。需要特别强调的是透明设计守护进程新增的任何环境变量或 CLI 参数都不需要等包装包发版。通过env、extraProfileCreateArgs、extraDaemonStartArgs三个入口即可原样透传详见下文。这一点在 types.ts 的注释中被称为intentionally thin and pass-through。命令解析细节uvx 与 uv run 的选择getEmbedCommand 的逻辑非常直白command.test.ts 逐条验证了场景生成命令无任何参数[uvx, hindsight-embedlatest]embedVersion: 0.5.0[uvx, hindsight-embed0.5.0]embedVersion: 空串视为 latest[uvx, hindsight-embedlatest]embedPackagePath: /abs/path[uv, run, --directory, /abs/path, hindsight-embed]本地路径与版本同时给出本地路径优先仍走uv run返回值是可直接交给spawn()/execFile()的 argv 数组[command, ...baseArgs]绝不经过 shell 插值因此无需担心命令注入。环境要求Node.js ≥ 22需要全局fetch和AbortSignal.timeoutengines字段同样声明22参见 package.jsonuv/uvx在PATH中首次使用时用于下载并运行 Hindsight 守护进程。安装npm install vectorize-io/hindsight-all vectorize-io/hindsight-client完整示例从启动到记忆操作import { HindsightServer, consoleLogger } from vectorize-io/hindsight-all; import { HindsightClient } from vectorize-io/hindsight-client; const server new HindsightServer({ profile: my-app, port: 9077, env: { HINDSIGHT_API_LLM_PROVIDER: anthropic, HINDSIGHT_API_LLM_API_KEY: process.env.ANTHROPIC_API_KEY, HINDSIGHT_API_LLM_MODEL: claude-sonnet-4-20250514, }, logger: consoleLogger, }); await server.start(); const client new HindsightClient({ baseUrl: server.getBaseUrl() }); await client.retain(user-123, User prefers dark mode.); const recall await client.recall(user-123, what are the user preferences?); await server.stop();上述代码做了四件事声明配置 → 启动守护进程含 profile 配置与健康等待→ 通过HindsightClient写入一条记忆并召回 → 优雅停止。如果面对的是远程 Hindsight API则完全跳过HindsightServer直接把HindsightClient指向远程 URL 即可。HindsightServerOptions 全参数详解下表完整继承自 hindsight-all-npm.md并补充了 types.ts 中确认的细节Option类型默认值说明profilestringdefault每个子命令中--profile使用的 profile 名。portnumber8888守护进程监听的 TCP 端口。hoststring127.0.0.1守护进程绑定的主机名用于健康检查。embedVersionstringlatest通过uvx运行的底层hindsight-embed包版本。embedPackagePathstring—本地 checkout 路径优先于embedVersion改用uv run --directory而非uvx。envRecordstring, string \| undefined{}传给守护进程进程的并写入 profile 配置通过--env KEYVALUE的环境变量是透传任何HINDSIGHT_API_*/HINDSIGHT_EMBED_*配置的首选方式值为undefined的键会被丢弃方便条件展开。extraProfileCreateArgsstring[][]原样追加到profile create后的额外参数。extraDaemonStartArgsstring[][]原样追加到daemon start后的额外参数。platformCpuWorkaroundbooleanmacOS 上为true自动设置HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU1与HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU1规避 Metal/MPS 崩溃调用方显式传入的env值优先于自动值。readyTimeoutMsnumber30000等待/health返回 200 的最大时间毫秒。readyPollIntervalMsnumber1000等待/health期间的轮询间隔毫秒。loggerLogger静默可插拔日志器debug/info/warn/error包内导出了consoleLogger与silentLogger两个助手。env 透传与 CPU 兜底的合并策略buildEnv 展示了环境变量的三层合并逻辑先拷贝process.env完整继承宿主进程环境若platformCpuWorkaround为真且运行在 macOSprocess.platform darwin自动注入两个FORCE_CPU变量最后覆盖调用方env中显式设置的值——调用方的值始终优先。注意 collectProfileEnv 的一个关键细节写入 profile 文件--env的只包含调用方显式传入的键与 CPU 兜底键并不会把整个process.env灌进 profile避免把宿主机随机状态泄漏进配置。这个取舍在源码注释中被明确说明。前向兼容的开放性设计env接受任意Recordstring, string | undefined。测试用例 server.test.ts 特意验证了即使传入了当下尚不存在的HINDSIGHT_FUTURE_FLAG键也不会报错——这正是守护进程新增环境变量永远不需要包装包升级的保证。同理extraProfileCreateArgs与extraDaemonStartArgs把原始 CLI 参数的门也完全打开。服务端方法Server methods方法返回说明start()Promisevoid配置 profile、拉起守护进程、等待/health。幂等可安全重复调用底层profile create --merge与daemon start都容忍重复执行。stop()Promisevoid停止守护进程。永不抛异常失败时记录日志并正常 resolve。checkHealth()Promiseboolean一次性/health探测2 秒超时未启动时返回false对应测试见 server.test.ts。getBaseUrl()string返回http://host:port可直接交给HindsightClient。getProfile()string当前 server 操作的 profile 名。默认构造参数在 server.test.ts 中有明确断言new HindsightServer()的getBaseUrl()为http://127.0.0.1:8888getProfile()为default自定义profile/port/host会如实反映到 Base URL见 server.test.ts。面向本地开发的 embedPackagePath如果你与 Pythonhindsight-embed包在同一 monorepo 中开发可以把embedPackagePath指向本地目录服务会改用uv run --directory path而非uvxnew HindsightServer({ embedPackagePath: /path/to/hindsight-embed, // ...其余配置 });命令解析测试 command.test.ts 验证了该分支的精确 argv。日志与底层辅助Logger接口debug/info/warn/error四个方法见 logger.ts。包本身不持有任何日志基础设施消费者可注入 console、pino、OpenClaw 的 logger 或 no-op默认silentLogger保证嵌入任何应用都不产生噪音。getEmbedCommand(opts)低层辅助函数返回用于调用底层 Python CLI 的[cmd, ...args]元组见 command.ts。小结vectorize-io/hindsight-all用极薄的 API 解决了在 Node 应用中内嵌本地 Hindsight 记忆服务这一实际问题HindsightServer负责 profile 配置、守护进程拉起、健康探测与优雅关闭env与两个extra*参数保证了与守护进程新特性的前向兼容HindsightClient则补齐记忆操作retain、recall、reflect、bank 管理。整个包的设计哲学是进程与 API 分离、包装层透明这也是它能够保持小而稳定、无需频繁发版的根本原因。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
