opcode-pg-memory 2.3.3 → 2.4.1

package/README.md

@@ -73,11 +73,18 @@ git clone https://github.com/Vbs313/opcode-pg-memory.git && cd opcode-pg-memory
 recall_memory({
   "query": "数据库连接池配置",
   "caller_context": { "type": "omo_agent", "current_goal": "性能调优" },
+  "scope": "task",
+  "aggregate_similar": true,
   "retrieval_strategies": ["semantic", "graph"],
   "filters": { "tier": "project" }
 })
 ```
 
+| 参数 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `scope` | `session` / `task` / `project` | `session` | 检索范围：当前会话 / 同任务所有会话 / 同项目所有会话 |
+| `aggregate_similar` | `boolean` | `false` | 合并连续同名工具调用（如 `read ×47 最近读取了...`），仅在查询层聚合，不丢失明细 |
+
 ### hindsight_reflect
 
 ```json
@@ -85,6 +92,37 @@ recall_memory({
 hindsight_reflect({ "omo_task_id": "task_123", "aggregate": true })
 ```
 
+### sync_health
+
+```json
+// 检查同步健康状态（无参数）
+sync_health()
+
+// 返回示例
+{
+  "status": "healthy",
+  "observations": { "total": 9922, "with_embedding": 9922, "embedding_pct": 100, "sessions_with_obs": 272 },
+  "embedder": { "queue_length": 0, "cooldown_remaining_s": null },
+  "warnings": []
+}
+```
+
+Agent 自愈模式：`sync_health` 发现 coverage < 95% → `backfill_embeddings` → `sync_health` 确认恢复。
+
+### backfill_embeddings
+
+```json
+// 回填缺失的 embedding
+backfill_embeddings({ "limit": 100 })
+backfill_embeddings({})  // 全量
+```
+
+| 参数 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `limit` | `number` | `0`（全量） | 限制处理条数 |
+
+使用 AsyncEmbedder 队列执行，支持 Ollama 不可用时 5 分钟冷却自动续传。已覆盖的 observation（`embedding IS NOT NULL`）不会重复处理。
+
 ## 架构
 
 ```
@@ -111,6 +149,54 @@ src/
 mcp-server.ts       # MCP 服务入口
 ```
 
+## 运维
+
+### 同步对账
+
+```bash
+# 查看同步健康度
+node scripts/verify-sync.js
+
+# JSON 输出（用于自动化/监控）
+node scripts/verify-sync.js --json
+```
+
+健康状态标志：
+
+| 指标 | 健康 | 告警 |
+|------|------|------|
+| 同步率 | ≥ 99.5% | < 99% |
+| tool_status = 'failed' 占比 | < 5% | > 10% |
+| 缺失会话数 | 0 | > 0 |
+| 含 tool_call_id 比例 | 100% | < 99% |
+| embedding 覆盖度 | ≥ 95% | < 95% |
+
+首次部署后执行一次全量同步：
+
+```bash
+node scripts/verify-sync.js
+# 确认同步率 >= 99.5%
+```
+
+`verify-sync.js` 是只读脚本，不修改数据库。同步由 EventSynchronizer 自动通过 OpenCode 事件总线或 SQLite 轮询完成。
+
+Agent 可直接调用 `sync_health()` 获取相同信息（`status`、`embedding_pct`、`warnings`）。
+
+### 批量 embedding 回填
+
+首次部署或新增 embedding 模型后，对历史观察生成向量：
+
+```bash
+# 查看待回填数量
+node scripts/backfill-embeddings.js --dry-run
+
+# 全量回填（按 created_at 顺序，支持断点续传）
+node scripts/backfill-embeddings.js
+
+# 限制处理条数（快速验证）
+node scripts/backfill-embeddings.js --limit 100
+```
+
 ## 文档
 
 | 文档 | 内容 |