用 Pi 接入 Hindsight：安装配置、记忆检索与实战排查我给 Pi 接入 Hindsight，是想让新 sess

我给 Pi 接入 Hindsight，是想让新 session 能查到之前讨论过的设计决定。项目代码一直在，方案背后的原因却常常得翻旧对话才能找到。

第一次检查时，Pi 已加载 Hindsight 扩展，bank 里却没有记忆。原因是 Hindsight 服务端调用的记忆抽取模型没有通过授权。换成账号已授权的 provider 后，Git 历史、项目结构调查和会话写入才陆续处理完成。Pi 扩展能否调用 Hindsight、服务端能否完成记忆处理，需要分开检查。

这里以 Pi 本地 daemon 接入为例。Hindsight Coding Agents 还支持 Claude Code、Codex CLI、Cursor CLI、GitHub Copilot CLI 和 opencode 等 Agent。各自的安装与 hook 配置见文末官方文档。

Pi 与 Hindsight 之间的数据流

Hindsight Coding Agents 为 Pi 注册扩展和工具，并在会话过程中调用 Hindsight API。首次接入仓库时，默认流程会读取 Git 历史并进行只读项目调查，建立初始记忆。每轮结束后，插件把对话写入对应 bank；服务端再从中提取记忆，供后续 session 检索。

Pi 会话开始  ->  根据当前问题检索已有记忆
Pi 本轮结束  ->  保存当前对话到 Hindsight bank
Hindsight    ->  提取记忆，并逐步更新 observations 和 Knowledge Pages

默认情况下，每个仓库使用独立 bank，名称类似 coding-agent::my-repo。链接 worktree 会沿用主仓库的 bank，因此同一项目的 Pi session 可以共享记忆，其他仓库则各自保存。

安装 Pi 扩展

本机使用 daemon 模式，安装命令：

npx @vectorize-io/hindsight-coding-agents@0.8.0 install pi --server daemon

安装器会把 Hindsight runtime 放到用户目录，并在 ~/.pi/agent/settings.json 中注册 Pi 扩展。Pi 通过原生扩展接入 Hindsight。

本地 daemon 需要 uv，macOS 还需要 Rust toolchain。扩展启动服务前会检查用于记忆抽取的 LLM provider。若 Pi 能启动但 API 未运行，检查这些依赖和 Hindsight 服务日志。

本机的 Hindsight API 地址是 http://127.0.0.1:9077。CLI 和 Control Plane 用的是不同端口：CLI 命令连 API，网页控制台由 hindsight ui 启动，浏览器地址是 http://localhost:9999/dashboard。

先将 CLI 指向本机 API，再检查服务：

hindsight configure
# API URL 填 http://127.0.0.1:9077

hindsight health
hindsight bank list

Hindsight Control Plane 的 Memory banks 页面，项目名称和运行数据已做模糊处理

截图取自本机 http://localhost:9999/dashboard，其中 bank 名称和活动信息已模糊处理。

侧边栏八个菜单，写代码时分别看什么

当前项目 bank 的侧边栏菜单，从上到下依次是 Home、Memories、Knowledge base、Recall、Reflect、Documents、Entities 和 Bank Configuration

示例 URL 中的 coding-agent%3A%3Aclaude-session-viewer 解码后是 bank ID coding-agent::claude-session-viewer。确认顶部选中的 bank 后，下面八个菜单都用于查看或管理它。切换菜单时，URL 的 view 参数也会变化，可用来直接打开对应页面。

菜单	页面和 URL	做编码工作时的用法
Home	`view=home`。查看记忆关系图、Knowledge Pages、最近文档、记忆类型和时间分布。	检查仓库 bank 是否有数据、最近有没有新材料进入。统计能反映处理情况，具体记忆仍需查看来源。
Memories	`view=data`。按 World Facts、Experience、Observations 查看记忆记录。World Facts 是外部来源的客观事实，Experience 记录 bank 的交互经历，Observations 则归纳多条事实中的持久模式。	核对项目约定是否入库。示例 bank 的 World Facts 标签为空，但 Home 仍显示 Experience 和 Observations；要按类型查看，不能据一个空标签判断整个 bank 为空。
Knowledge base	`view=knowledge`。浏览 Pages 和 Mental Models，并搜索、打开或编辑页面。	改模块前先查 Component map、Conventions 或 Key decisions，借此定位相关代码和已有约定。
Recall	`view=recall`。Recall Analyzer 可设置记忆类型和搜索预算，并显示检索结果与 trace。	要确认某个问题能否检索到历史决定时，用它检查 recall 结果。Pi 的自动注入也使用 recall，具体类型、预算和 token 上限由 `~/.hindsight/coding-agent.json` 决定。结果为空时，检查 bank、查询词和筛选条件。
Reflect	`view=reflect`。输入问题后，agentic loop 会从记忆中逐步取证并生成回答；可设置预算和记忆类型。	追问“当时为什么这样设计”时使用。Reflect 会综合多条记忆，通常比 Recall 慢，也会额外调用模型。回答中的旧决定要再与当前源码和测试核对。
Documents	`view=documents`。列出进入 bank 的源文档，可搜索、按时间筛选、添加和管理。	记忆没有出现时，检查原始会话、Git 历史或手动导入的资料是否已进入 bank。Document 是输入材料，Memory 是从材料中提取的内容。
Entities	`view=entities`。用 Relations 图或 List 查看记忆中提取的人、组织、地点等实体及关联。	查找不同记忆记录中反复出现的对象与关系。页面展示记忆里的实体关联，不会生成仓库的代码依赖图。
Bank Configuration	`view=profile`。查看该 bank 的统计、记忆策略、操作状态和管理设置。	调整 Hindsight 服务端的 bank 行为时来这里。Pi 插件使用独立配置 `~/.hindsight/coding-agent.json`。

简单区分：Documents 保存输入材料，Memories 是从材料中提取的事实或经验，Knowledge Pages 按主题整理多条记忆。编码时先查 Knowledge Pages；核对具体记录用 Memories 或 Recall；需要追溯设计原因时再用 Reflect。Recall 用于检查检索结果，Reflect 则会调用模型综合记忆。

以 src/views/ChatView.vue 为例，修改前先从 Knowledge base 查组件职责和已有约定，再用 Recall 核对相关决定。需要了解背景时再用 Reflect。最后回到 Vue 源码和测试确认当前行为，避免把历史记录当成现状。

Bank Configuration 里的子页面

Bank Configuration 下的子页面查看或调整当前 bank 的服务端行为，共享该 bank 的客户端都会受这些设置影响。

子页面	实际用途
General	查看 bank 概览、记忆构成、合并状态和后台操作。排查写入状态时先看这里。
Memory Defense	在 retain 写入前检查敏感内容和安全风险。当前界面将更完整的检测、脱敏和审计能力列为 Hindsight Cloud Enterprise 功能。
Configuration	设置 observations 归纳策略、mission 和 Reflect 回答方式、Knowledge Page 默认刷新值、客户端别名与工具限制、原始文档保存选项，以及 Recall 的 BM25、时间、图关系和 rerank 阶段。
Webhooks	管理接收 bank 事件通知的 endpoint。需要向外部服务推送记忆事件时配置。
Audit Logs	查看 retain、recall、reflect 等操作的审计记录。本机服务端未启用此功能；设置 `HINDSIGHT_API_AUDIT_LOG_ENABLED=true` 后才能使用。
LLM Requests	查看模型调用、token、操作类型和状态，可用于排查 provider 错误、延迟和调用量。

Pi 扩展在 ~/.hindsight/coding-agents/dist/pi.js 中注册 Hindsight 工具。before_agent_start 按配置检索并注入上下文，agent_end 把本轮对话写回 bank。写入和抽取状态可在 Documents、Memories 和 General 中核对。控制台负责查看和管理 bank；Vue 页面代码仍在仓库中修改。Pi 插件配置独立维护，调整 Bank Configuration 不会同步改动插件配置。

Pi 与 Hindsight 的模型分别配置

Pi 的模型负责理解问题、写代码和调用工具。Hindsight 服务端则使用 LLM provider 抽取和整理记忆。Pi 能正常回答时，provider 授权仍可能失败，导致 Hindsight 没有新记忆。

本机的 Hindsight 服务端使用已登录的 Codex OAuth。provider 配置在 daemon 的环境文件中：

# ~/.hindsight/profiles/coding-agent.env
HINDSIGHT_API_LLM_PROVIDER=openai-codex
HINDSIGHT_API_LLM_MODEL=gpt-5.6-luna

模型名要符合当前账号支持范围。我的账号不接受默认尝试的 gpt-5.4-mini，改用 gpt-5.6-luna 后服务端验证通过。修改 provider 或模型后，重启 Hindsight daemon，再运行 hindsight health 检查服务。API key 和 OAuth 凭据不要写入文章、仓库配置或截图。

Claude 的两种 Hindsight provider

HINDSIGHT_API_LLM_PROVIDER 指定 Hindsight 服务端整理记忆时使用的模型 provider，Pi 或 Claude Code 选择的编码模型另行配置。Claude 可使用 Claude Code 登录态或 Anthropic API key，两者授权方式不同。下面的环境变量写入 ~/.hindsight/profiles/coding-agent.env，选择其中一组即可；修改后重启 Hindsight daemon，并运行 hindsight health 检查。

使用 Claude Code 登录态时，选择 claude-code provider。在运行 daemon 的同一用户环境执行 claude auth login，再配置：

HINDSIGHT_API_LLM_PROVIDER=claude-code
HINDSIGHT_API_LLM_MODEL=claude-sonnet-4-5-20250929

这条路径不需要 HINDSIGHT_API_LLM_API_KEY，但要求 Claude Code 登录有效，且账号或组织允许使用 Claude Code。我的账号曾返回 Your organization has disabled Claude subscription access for Claude Code，因此无法使用这条路径。

直接调用 Anthropic API 时，选择 anthropic provider，并从 Anthropic Console 获取 API key。费用按 API 用量计算。配置示例：

HINDSIGHT_API_LLM_PROVIDER=anthropic
HINDSIGHT_API_LLM_API_KEY=<your-anthropic-api-key>
HINDSIGHT_API_LLM_MODEL=claude-haiku-4-5

<your-anthropic-api-key> 是占位符，需在本机替换，勿将真实 key 提交到仓库。claude-haiku-4-5 是本机 Hindsight API 0.10.2 中的 Anthropic 默认模型；模型 ID 可能随版本变化，配置前请查阅 Hindsight 模型文档。如果组织禁用了 Claude Code 登录态，可以申请 Anthropic API key，或改用账号已授权的 provider。

配置 Pi 的自动注入

Hindsight 默认使用 reflect 自动注入，在新 session 开始时综合已有记忆。我的 bank 还在积累，我把 Pi 改为低预算 recall，只注入少量相关观察：

{
  "serverMode": "daemon",
  "harnesses": {
    "pi": {
      "autoInject": "recall",
      "injectTimeoutMs": 2000,
      "recallOptions": {
        "types": ["observation"],
        "budget": "low",
        "max_tokens": 2000,
        "include": {
          "entities": null
        }
      },
      "pageSearchLimit": 3,
      "pageRefreshEveryTurns": 10,
      "pageTriggerType": "cron",
      "pageTriggerCron": "H * * * *"
    }
  }
}

配置文件是 ~/.hindsight/coding-agent.json。autoInject: "recall" 会检索与当前问题相关的记忆；injectTimeoutMs 将等待时间限制在 2 秒；max_tokens 限制注入上下文的长度。这里优先查 observation，它是归纳后的记忆，适合轻量回顾。

pageRefreshEveryTurns 决定插件每隔多少轮重新读取 Knowledge Pages 列表和工具说明。页面内容则由 pageTriggerType 和 pageTriggerCron 控制刷新。cron 表达式里的 H 会把不同页面的刷新时间分散到不同分钟。新写入的记忆不会立即出现在 Knowledge Pages 中，需等刷新任务运行。

常用 Hindsight CLI

将 <bank-id> 替换为 hindsight bank list 显示的名称。CLI 使用 hindsight configure 保存的 API 地址连接服务。

命令	作用
`hindsight health`	检查 API 和数据库状态。
`hindsight bank list`	列出当前 API 下的 memory bank。
`hindsight bank stats <bank-id>`	查看指定 bank 的记忆统计。
`hindsight memory recall <bank-id> "问题" --fact-type observation --budget low --max-tokens 2000`	按语义检索记忆，核对项目约定或历史信息。
`hindsight memory reflect <bank-id> "为什么这样设计？" --budget low`	让服务端综合记忆回答问题。比 recall 慢，适合追问设计背景。
`hindsight knowledge-base tree <bank-id>`	列出 Knowledge Pages 的目录和页面。
`hindsight knowledge-base search <bank-id> "查询内容" --limit 3`	混合搜索 Knowledge Pages。
`hindsight operation list <bank-id>`	查看写入和抽取等异步任务的状态。
`hindsight operation retry <bank-id> <operation-id>`	重试指定的失败任务。
`hindsight ui`	启动网页控制台。

排查空 bank 时，先运行 hindsight health，再查看 hindsight operation list 和服务日志中的 provider 错误。失败任务会留在历史列表里；判断当前状态时看最近任务和 pending 数量，不要只看累计失败数。

Pi 里的 Hindsight 工具怎么用

Pi 扩展注册了以下工具，可在对话中按需调用：

工具	适合的场景
`hindsight_search_knowledge_pages(query)`	搜索项目架构、约定、历史决定和进行中的计划。开始较大改动前先查相关页面。
`hindsight_list_knowledge_pages()` / `hindsight_read_knowledge_page(page_id)`	列出页面，或阅读相关页面全文。
`hindsight_reflect(query)`	页面内容不足以解释原因时，综合更多记忆回答问题。调用较慢，按需使用。
`hindsight_capture_initiative(title, summary)`	确认新功能计划后、开始编码前，创建可持续更新的 initiative 页面。
`hindsight_ingest_document(title, content)`	将外部文档或长期参考资料写入 bank。普通 Pi 对话会在每轮结束时自动写回，无需重复 ingest。
`hindsight_sync_status()` / `hindsight_diagnose()`	查看当前仓库的同步状态和安全诊断信息。

Pi 日常使用低预算 recall 自动注入；需要追查设计原因时再调用 reflect。遇到空 bank 或页面未更新，依次检查 API 状态、异步任务和 provider 日志，判断问题出在插件调用还是服务端处理。

官方文档：Agent 接入和模型配置

安装参数和 provider 配置可能随 Hindsight 版本变化；请对照所用版本的官方文档。

Hindsight Coding Agents 官方文档 · GitHub README：支持的 Agent、安装方式和各自接入说明。
Hindsight 模型与 provider 文档：支持的模型供应商和模型 ID。
Hindsight 服务端配置文档：环境变量和 HINDSIGHT_API_LLM_* 配置。
Hindsight GitHub 仓库。

常见模型供应商的官方资料：

示例环境为 Pi 1.2.0、Hindsight Coding Agents 0.8.0 和 Hindsight API 0.10.2。其他版本的默认值和 provider 支持可能不同，遇到差异时请以本机 --help 和实际配置为准。