pi-hindsight

Hindsight 长期记忆集成扩展，为 Pi 编码助手提供持久化记忆能力。

基于 opencode-hindsight 实现，可共享同一 Hindsight 服务和记忆库。

功能特性

• 自动 Recall：每次用户输入时，自动从记忆库召回相关上下文注入 LLM
• 自动 Retain：每 N 轮对话后，自动存储对话到记忆库
• 手动工具：LLM 可主动调用 retain/recall/reflect 工具
• 配置灵活：支持配置文件和环境变量

前置要求

1. Pi >= 0.83.0
2. Hindsight Server 运行中（默认 http://localhost:8888）

安装

方式 1：Git 克隆（推荐）

# 1. 备份已有扩展（如果存在）
mv ~/.pi/agent/extensions/hindsight ~/.pi/agent/extensions/hindsight.bak 2>/dev/null

# 2. 克隆仓库
git clone https://github.com/chenjim/pi-hindsight.git ~/.pi/agent/extensions/hindsight

# 3. 安装依赖
cd ~/.pi/agent/extensions/hindsight
npm install

# 4. 重启 Pi 或在 Pi session 中执行 /reload

方式 2：手动复制

# 1. 下载并解压，或直接复制文件
# 确保 ~/.pi/agent/extensions/hindsight/ 包含：
#   - index.ts
#   - package.json
#   - README.md

# 2. 安装依赖
cd ~/.pi/agent/extensions/hindsight
npm install

# 3. 重启 Pi 或在 Pi session 中执行 /reload

验证安装

在 Pi session 中输入：

你是谁

如果看到自动召回了你的相关信息，说明扩展已生效。

配置

第一步：创建配置文件

mkdir -p ~/.hindsight
cat > ~/.hindsight/pi.json << 'EOF'
{
  "apiUrl": "http://localhost:8888",
  "apiToken": "your-api-token",
  "bankId": "hermes"
}
EOF

第二步：修改配置

编辑 ~/.hindsight/pi.json，填入你的实际配置：

参数	说明	示例
apiUrl	Hindsight API 地址	http://localhost:8888
apiToken	API 认证 token	14ef3679...
bankId	记忆库 ID	hermes
agentName	Agent 名称（无 bankId 时用于动态生成）	pi
autoRecall	每次输入自动召回记忆	true
autoRetain	每 N 轮自动存储对话	true
recallBudget	召回预算：low / mid / high	mid
recallMaxTokens	召回结果最大 token 数	1024
recallTypes	召回的记忆类型	["world", "experience"]
recallContextTurns	自动存储间隔（轮数）	3
recallMaxQueryChars	召回查询最大字符数	800
retainContext	存储时附加的上下文标记	pi
debug	调试日志开关	false

环境变量（可选）

环境变量优先级高于配置文件：

export HINDSIGHT_API_URL=http://localhost:8888
export HINDSIGHT_API_TOKEN=your-api-token
export HINDSIGHT_BANK_ID=hermes

完整配置选项

{
  "apiUrl": "http://localhost:8888",
  "apiToken": null,
  "bankId": null,
  "agentName": "pi",
  "autoRecall": true,
  "autoRetain": true,
  "recallBudget": "mid",
  "recallMaxTokens": 1024,
  "recallTypes": ["world", "experience"],
  "recallContextTurns": 3,
  "recallMaxQueryChars": 800,
  "retainContext": "pi",
  "debug": false
}

使用方式

自动模式

扩展加载后自动工作：

1. 自动 Recall：每次你输入问题时，自动从记忆库搜索相关记忆注入上下文
2. 自动 Retain：每 3 轮对话后，自动存储对话到记忆库

手动工具

LLM 可以主动调用以下工具：

• hindsight_retain - 存储重要信息到记忆库
• hindsight_recall - 搜索长期记忆
• hindsight_reflect - 基于记忆生成综合回答

与 OpenCode 共享记忆

如果同时使用 OpenCode 和 Pi，配置相同的 bankId 即可共享记忆库：

{
  "bankId": "hermes"
}

架构

┌─────────────────────────────────────────────────┐
│                  Pi Session                      │
│                                                  │
│  before_agent_start ──► 自动 recall (每次输入)    │
│  agent_settled ──────► 自动 retain (每 N 轮)     │
│  LLM ────────────────► 手动调用工具               │
│       ├── hindsight_retain                        │
│       ├── hindsight_recall                        │
│       └── hindsight_reflect                       │
└─────────────────┬───────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────┐
│            Hindsight Server                       │
│         (localhost:8888 / Docker)                 │
└─────────────────────────────────────────────────┘

故障排除

扩展未加载

# 检查扩展目录是否存在
ls ~/.pi/agent/extensions/hindsight/index.ts

# 检查依赖是否安装
ls ~/.pi/agent/extensions/hindsight/node_modules/@vectorize-io/hindsight-client

# 在 Pi session 中执行
/reload

API 连接失败

# 检查 Hindsight 服务是否运行
curl http://localhost:8888/health

# 检查配置文件
cat ~/.hindsight/pi.json

无记忆返回

# 检查 bank 是否有数据
curl -s http://localhost:8888/v1/default/banks/hermes/memories/count \
  -H "Authorization: Bearer your-api-token"

License

MIT

相关项目

• Pi Coding Agent
• Hindsight
• opencode-hindsight