@shadowforge0/aquifer-memory 1.5.9 → 1.6.0

package/README_CN.md

@@ -0,0 +1,659 @@
+<div align="center">
+
+# 🌊 Aquifer
+
+**基于 PostgreSQL 的 AI Agent 长期记忆系统**
+
+*Turn 级 embedding、三路 RRF 混合排序、信任评分、实体交叉查询、知识图谱、实体作用域——全部运行在 PostgreSQL + pgvector 上。*
+
+[![npm version](https://img.shields.io/npm/v/@shadowforge0/aquifer-memory)](https://www.npmjs.com/package/@shadowforge0/aquifer-memory)
+[![PostgreSQL 15+](https://img.shields.io/badge/PostgreSQL-15%2B-336791)](https://www.postgresql.org/)
+[![pgvector](https://img.shields.io/badge/pgvector-0.7%2B-blue)](https://github.com/pgvector/pgvector)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+[English](README.md) | [繁體中文](README_TW.md) | [简体中文](README_CN.md)
+
+</div>
+
+---
+
+## 为什么选 Aquifer？
+
+大多数 AI 记忆系统会在旁边挂一个向量数据库。Aquifer 的做法不同：**PostgreSQL 就是记忆本体**。
+
+Session、摘要、turn 级 embedding、实体图谱——全部存在同一个数据库里，用同一个连接查询。不需要同步层、没有最终一致性问题、不用额外基础设施。
+
+### 跟典型做法的差异
+
+| | Aquifer | 典型向量 DB 做法 |
+|---|---|---|
+| **存储** | PostgreSQL + pgvector | 独立向量 DB + 应用 DB |
+| **粒度** | Turn 级 embedding（不只是 session 摘要） | Session 或文档分片 |
+| **排序** | 三路 RRF：FTS + session embedding + turn embedding | 单一向量相似度 |
+| **知识图谱** | 内建实体提取与共现关系 | 通常是独立系统 |
+| **多租户** | 每张表都有 `tenant_id`，第一天就内建 | 通常是事后补做 |
+| **依赖** | `pg` + MCP SDK | 多个 SDK |
+
+### 有和没有的差别
+
+**没有 turn 级记忆——搜索只能命中模糊的摘要：**
+
+> 查询："我们对 auth middleware 做了什么决定？"
+> → 返回一份 2000 字的 session 摘要，里面某处提到了 auth
+
+**有 Aquifer——搜索直接命中精确的对话片段：**
+
+> 查询："我们对 auth middleware 做了什么决定？"
+> → 返回那句原话："旧的 auth middleware 拆掉吧——法务说 session token 存储方式不合规"
+
+---
+
+## 需求
+
+| 组件 | 必需？ | 用途 | 示例 |
+|------|--------|------|------|
+| Node.js >= 18 | 是 | Runtime | — |
+| PostgreSQL 15+ | 是 | 存储 session、摘要、实体 | 本地、Docker 或 managed |
+| pgvector extension | 是 | 向量相似度搜索 | `CREATE EXTENSION vector;`（`pgvector/pgvector` Docker image 内置） |
+| Embedding 端点 | 是（recall 用） | Turn + session embedding | Ollama `bge-m3`、OpenAI `text-embedding-3-small`、任何 OpenAI 兼容 API |
+| LLM 端点 | 可选 | `enrich` 阶段的内置摘要 | Ollama、OpenRouter、OpenAI——或自己传 `summaryFn` |
+| `@modelcontextprotocol/sdk` + `zod` | 是（MCP server 用） | MCP 协议 runtime | 已列入 dependencies，自动安装 |
+
+---
+
+## 快速开始（MCP 服务器）
+
+两行命令从零到可用的 MCP 记忆服务器——不需要设任何 env。Library API 用法请往下看 [Library API](#library-api)。
+
+### 1. 起 stack
+
+```bash
+docker compose up -d
+# PostgreSQL 16 + pgvector 和 Ollama（bge-m3 自动 pull）。
+# 第一次运行会拉 model——`docker compose logs -f ollama-pull` 看进度。
+```
+
+已经有 PostgreSQL + pgvector 和 embedding 端点在跑？跳过这步——`quickstart` 会从环境变量读 `DATABASE_URL` / `EMBED_PROVIDER`（如果已设置）。
+
+### 2. 验证
+
+```bash
+npx --yes @shadowforge0/aquifer-memory quickstart
+```
+
+就这样。`quickstart` 会自动探测 `localhost:5432` 的 PostgreSQL 和 `localhost:11434` 的 Ollama（步骤 1 起的或你自己的都行），跑 migration、embed 一个测试 session、recall 回来、清干净。看到 `✓ Aquifer is working` 就成功了。
+
+长期使用建议装进项目省掉 `npx` 解析开销：`npm install @shadowforge0/aquifer-memory` 然后 `npx aquifer quickstart`。
+
+要用 OpenAI 不用 Ollama？跑 `quickstart` 前 `export EMBED_PROVIDER=openai` + `OPENAI_API_KEY=sk-...`——model 默认 `text-embedding-3-small`。
+
+### 3. 接到你的 MCP client
+
+Claude Code、Claude Desktop 或任何支持 MCP 的 client——放进 `.mcp.json`（项目级）或 `claude_desktop_config.json`：
+
+```jsonc
+{
+  "mcpServers": {
+    "aquifer": {
+      "command": "npx",
+      "args": ["--yes", "@shadowforge0/aquifer-memory", "mcp"],
+      "env": {
+        "DATABASE_URL": "postgresql://aquifer:aquifer@localhost:5432/aquifer",
+        "EMBED_PROVIDER": "ollama",
+        "AQUIFER_MEMORY_SERVING_MODE": "legacy"
+      }
+    }
+  }
+}
+```
+
+或直接跑：`DATABASE_URL=... EMBED_PROVIDER=ollama npx aquifer mcp`。（MCP server 本身对 env 严格——`quickstart` 的 autodetect 是试用路径，不是 production 路径。）
+
+第一轮 rollout 先保持 `AQUIFER_MEMORY_SERVING_MODE=legacy`。只有在你要让 `session_recall` 和 `session_bootstrap` 提供 active curated memory 时，才切到 `curated`；`evidence_recall` 会保留为显式 audit/debug 路径。要 rollback 只要把 env 或 config 切回 `legacy`。
+
+需要 LLM 摘要、知识图谱、OpenAI embedding 或 reranker？往下看 [环境变量](#环境变量) 和 [docs/setup.md](docs/setup.md)。
+
+---
+
+## Library API
+
+### 初始化
+
+```javascript
+const { createAquifer } = require('@shadowforge0/aquifer-memory');
+
+const aquifer = createAquifer({
+  db: 'postgresql://user:pass@localhost:5432/mydb',  // 连接字符串或 pg.Pool
+  schema: 'memory',                    // PG schema 名称（默认 'aquifer'）
+  tenantId: 'default',                 // 多租户隔离
+  embed: {
+    fn: async (texts) => embeddings,   // 你的 embedding 函数
+    dim: 1024,                         // 可选，维度提示
+  },
+  llm: {
+    fn: async (prompt) => text,        // 你的 LLM 函数（内置摘要用）
+  },
+  entities: {
+    enabled: true,
+    scope: 'my-app',                   // 实体命名空间（默认 'default'）
+  },
+});
+
+// 执行 migration（可重复执行）
+await aquifer.migrate();
+```
+
+### 写入路径：commit + enrich
+
+```javascript
+// 1. 保存 session
+await aquifer.commit('conv-001', [
+  { role: 'user', content: '我来说说新的 auth 做法...' },
+  { role: 'assistant', content: '了解，所以计划是...' },
+], { agentId: 'main' });
+
+// 2. 丰富化：摘要 + turn embedding + 实体提取
+const result = await aquifer.enrich('conv-001', {
+  agentId: 'main',
+  summaryFn: async (msgs) => ({ summaryText, structuredSummary, entityRaw }),
+  entityParseFn: (text) => [{ name, normalizedName, type, aliases }],
+  postProcess: async (ctx) => { /* 后处理 hook */ },
+});
+```
+
+### 查询路径：recall
+
+```javascript
+const results = await aquifer.recall('auth middleware 决定', {
+  agentId: 'main',
+  limit: 5,
+  entities: ['auth-middleware'],       // 可选：实体感知搜索
+  entityMode: 'all',                   // 'any'（加分）或 'all'（硬筛）
+});
+// 返回排序后的 session，使用三路 RRF 融合
+```
+
+---
+
+## 宿主集成
+
+MCP 是主要的集成接口。Agent 宿主连接到 Aquifer MCP server，该 server 暴露八个工具：`session_recall`、`evidence_recall`、`session_feedback`、`memory_feedback`、`feedback_stats`、`session_bootstrap`、`memory_stats`、`memory_pending`。
+
+| 集成方式 | 路径 | 状态 | 使用场景 |
+|----------|------|------|----------|
+| MCP server | `consumers/mcp.js` | 主要 | Claude Code、OpenClaw、Codex 及任何支持 MCP 的宿主 |
+| Library API | `createAquifer()` | 主要 | 后端应用、自定义 pipeline、直接 Node.js 调用 |
+| CLI | `consumers/cli.js` | 辅助 | 运维、调试、手动 recall/backfill |
+| OpenCode 导入 | `consumers/opencode.js` | 辅助 | 从 OpenCode 的 SQLite DB 导入 session |
+| OpenClaw 插件 | `consumers/openclaw-plugin.js` | 仅兼容 | 通过 `before_reset` 捕获 session——不用于工具分发 |
+
+### Claude Code
+
+添加到项目的 `.claude.json` 或用户级 MCP 配置：
+
+```json
+{
+  "mcpServers": {
+    "aquifer": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/aquifer/consumers/mcp.js"],
+      "env": {
+        "DATABASE_URL": "postgresql://...",
+        "AQUIFER_EMBED_BASE_URL": "http://localhost:11434/v1",
+        "AQUIFER_EMBED_MODEL": "bge-m3"
+      }
+    }
+  }
+}
+```
+
+工具在 Claude Code 中显示为 `mcp__aquifer__session_recall`、`mcp__aquifer__evidence_recall`、`mcp__aquifer__session_bootstrap`、`mcp__aquifer__session_feedback`、`mcp__aquifer__memory_feedback`、`mcp__aquifer__feedback_stats`、`mcp__aquifer__memory_stats`、`mcp__aquifer__memory_pending`。
+
+### OpenClaw
+
+添加到 `openclaw.json` 的 `mcp.servers` 下：
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "aquifer": {
+        "command": "node",
+        "args": ["/path/to/aquifer/consumers/mcp.js"],
+        "env": {
+          "DATABASE_URL": "postgresql://...",
+          "AQUIFER_EMBED_BASE_URL": "http://localhost:11434/v1",
+          "AQUIFER_EMBED_MODEL": "bge-m3"
+        }
+      }
+    }
+  }
+}
+```
+
+工具显示为 `aquifer__session_recall`、`aquifer__evidence_recall`、`aquifer__session_feedback`、`aquifer__memory_feedback`、`aquifer__feedback_stats`、`aquifer__session_bootstrap`、`aquifer__memory_stats`、`aquifer__memory_pending`（宿主自动添加 server 名称前缀）。
+
+OpenClaw 插件（`consumers/openclaw-plugin.js`）保留用于通过 `before_reset` 捕获 session，但**不是**推荐的工具分发路径。请使用 MCP。
+
+### 其他支持 MCP 的宿主
+
+任何支持 MCP stdio 的宿主都可以用相同方式连接——将其指向 `node consumers/mcp.js` 并设置所需的环境变量。MCP server 是规范的外部接口。
+
+---
+
+## 环境变量
+
+| 变量 | 是否必需？ | 用途 | 示例 |
+|------|-----------|------|------|
+| `DATABASE_URL` | 是 | PostgreSQL 连接字符串 | `postgresql://user:pass@localhost:5432/mydb` |
+| `AQUIFER_SCHEMA` | 否 | PG schema 名称（默认：`aquifer`） | `memory` |
+| `AQUIFER_TENANT_ID` | 否 | 多租户 key（默认：`default`） | `my-app` |
+| `AQUIFER_EMBED_BASE_URL` | 是（recall 需要） | Embedding API 基础 URL | `http://localhost:11434/v1` |
+| `AQUIFER_EMBED_MODEL` | 是（recall 需要） | Embedding 模型名称 | `bge-m3` |
+| `AQUIFER_EMBED_API_KEY` | 取决于提供商 | 托管 embedding 提供商的 API key | `sk-...` |
+| `AQUIFER_EMBED_DIM` | 否 | Embedding 维度覆盖（自动检测） | `1024` |
+| `AQUIFER_LLM_BASE_URL` | 否 | LLM API 基础 URL（内置摘要用） | `http://localhost:11434/v1` |
+| `AQUIFER_LLM_MODEL` | 否 | LLM 模型名称 | `llama3.1` |
+| `AQUIFER_LLM_API_KEY` | 取决于提供商 | 托管 LLM 提供商的 API key | `sk-...` |
+| `AQUIFER_ENTITIES_ENABLED` | 否 | 启用知识图谱（默认：`false`） | `true` |
+| `AQUIFER_ENTITY_SCOPE` | 否 | 实体命名空间（默认：`default`） | `my-app` |
+| `AQUIFER_RERANK_ENABLED` | 否 | 启用 cross-encoder reranking | `true` |
+| `AQUIFER_RERANK_PROVIDER` | 否 | Reranker 提供商：`tei`、`jina`、`openrouter` | `tei` |
+| `AQUIFER_RERANK_BASE_URL` | 否 | Reranker 端点 | `http://localhost:8080` |
+| `AQUIFER_AGENT_ID` | 否 | 默认 agent ID | `main` |
+| `AQUIFER_MEMORY_SERVING_MODE` | 否 | 对外 serving mode：默认 `legacy`，可 opt-in `curated` | `curated` |
+| `AQUIFER_MEMORY_ACTIVE_SCOPE_KEY` | 否 | recall/bootstrap 默认 active curated scope | `project:aquifer` |
+| `AQUIFER_MEMORY_ACTIVE_SCOPE_PATH` | 否 | curated scope inheritance 的有序路径 | `global,project:aquifer` |
+| `AQUIFER_MIGRATIONS_MODE` | 否 | 启动 handshake 模式：`apply`（默认）、`check`、`off` | `apply` |
+| `AQUIFER_MIGRATION_LOCK_TIMEOUT_MS` | 否 | advisory lock 等待上限，超时抛 `AQ_MIGRATION_LOCK_TIMEOUT`（默认 30000） | `30000` |
+| `AQUIFER_INSIGHTS_DEDUP_MODE` | 否 | insights 语义去重模式：`off`（默认）、`shadow`、`enforce`——此字段 env 盖过代码配置，便于 operator 不重新部署就紧急关停 | `shadow` |
+| `AQUIFER_INSIGHTS_DEDUP_COSINE` | 否 | 语义合并的 cosine 阈值（默认 `0.88`，落在 `[0.75, 0.95]` 外会发出警告） | `0.90` |
+| `AQUIFER_INSIGHTS_DEDUP_CLOSE_BAND_FROM` | 否 | close-band（`dedupNear` metadata）下界，必须严格小于阈值（默认 `0.85`） | `0.82` |
+
+完整的环境变量到配置映射见 [consumers/shared/config.js](consumers/shared/config.js)。
+
+Curated serving 是 opt-in。若 rollout 时需要回到旧路径，设置 `AQUIFER_MEMORY_SERVING_MODE=legacy` 并重启 MCP/CLI process 即可，不需要破坏性 DB rollback。
+
+### Insights 语义去重（1.5.10）
+
+当 cron extractor（`scripts/extract-insights-from-recent-sessions.js`）或其它调用方通过 `commitInsight` 写 insights 时，canonical-key 层（1.5.3+）会对 `canonicalClaim + entities` 散列相同的 row 做去重。但 LLM 多次产出的 `canonicalClaim` 未必稳定，所以 1.5.10 增加第二层：`title + body` 做 embedding，在 `(tenant, agent, type)` 范围内的 active row 做比对，top cosine 超过 `AQUIFER_INSIGHTS_DEDUP_COSINE` 就触发 supersede（enforce 模式）或仅记录 would-merge metadata（shadow 模式）。落在 close band（`closeBandFrom ≤ cos < threshold`）会写 `metadata.dedupNear`，不 supersede，便于 operator 调整阈值前先观察。
+
+推荐部署顺序：`shadow` 跑一个 weekly cycle，检查 `SELECT metadata->>'shadowMatch' FROM insights WHERE metadata ? 'shadowMatch'` 看有无错误合并，确认没问题再切 `enforce`。Kill-switch：`AQUIFER_INSIGHTS_DEDUP_MODE=off` 后重启。
+
+1.5.3 之前的历史 row（`canonical_key_v2 IS NULL`）会被语义层直接捕获，但不进入 canonical 路径；启动警告会提示运行一次性的 backfill：
+
+```bash
+DATABASE_URL=... \
+  node scripts/backfill-canonical-key.js --schema <schema> --agent <id>
+```
+
+Script 是 idempotent 的（`WHERE canonical_key_v2 IS NULL` 保护），重复运行、与 live writer 并发都安全。
+
+---
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    createAquifer（入口）                      │
+│         设定 · Migration · Ingest · Recall · Enrich          │
+└────────┬──────────┬──────────┬──────────┬───────────────────┘
+         │          │          │          │
+    ┌────▼───┐ ┌────▼────┐ ┌──▼───┐ ┌───▼──────────┐
+    │storage │ │hybrid-  │ │entity│ │   pipeline/   │
+    │  .js   │ │rank.js  │ │ .js  │ │summarize.js   │
+    └────────┘ └─────────┘ └──────┘ │embed.js       │
+         │                     │    │extract-ent.js │
+    ┌────▼───────────┐    ┌───▼──┐  │rerank.js      │
+    │  PostgreSQL     │    │ LLM  │  └───────────────┘
+    │  + pgvector     │    │ API  │
+    └────────────────┘    └──────┘
+
+    ┌───────────────────────────────────┐
+    │         schema/                   │
+    │  001-base.sql（sessions、          │
+    │    summaries、turns、FTS）          │
+    │  002-entities.sql（KG）             │
+    │  003-trust-feedback.sql（信任评分） │
+    └───────────────────────────────────┘
+```
+
+### 文件说明
+
+| 文件 | 用途 |
+|------|------|
+| `index.js` | 入口——导出 `createAquifer`、`createEmbedder`、`createReranker` |
+| `core/aquifer.js` | 主 facade：`migrate()`、`commit()`、`recall()`、`enrich()` |
+| `core/storage.js` | Session/摘要/turn 的 CRUD、FTS 搜索、embedding 搜索 |
+| `core/entity.js` | 实体 upsert、mention 追踪、关系图谱、名称规范化 |
+| `core/hybrid-rank.js` | 三路 RRF 融合、时间衰减、信任乘数、实体加分、open-loop 加分 |
+| `pipeline/summarize.js` | LLM 驱动的 session 摘要（结构化输出） |
+| `pipeline/embed.js` | Embedding 客户端（任何 OpenAI 兼容 API） |
+| `pipeline/extract-entities.js` | LLM 驱动的实体提取（12 种类型） |
+| `pipeline/rerank.js` | Cross-encoder reranking（TEI、Jina、OpenRouter） |
+| `pipeline/normalize/` | Session 规范化，过滤 Claude Code / gateway 噪音 |
+| `consumers/opencode.js` | OpenCode SQLite 导入消费者 |
+| `schema/001-base.sql` | DDL：sessions、summaries、turn_embeddings、FTS 索引 |
+| `schema/002-entities.sql` | DDL：entities、mentions、relations、entity_sessions |
+| `schema/003-trust-feedback.sql` | DDL：trust_score 字段、session_feedback 审计表 |
+
+---
+
+## 核心功能
+
+### 三路混合检索（RRF）
+
+```
+查询 ──┬── FTS（BM25）              ──┐
+       ├── Session embedding 搜索   ──├── RRF 融合 → 时间衰减 → 实体加分 → 结果
+       └── Turn embedding 搜索     ──┘
+```
+
+- **全文搜索** — PostgreSQL `tsvector`，支持多语言排序
+- **Session embedding** — 对 session 摘要做 cosine 相似度
+- **Turn embedding** — 对单个 user turn 做 cosine 相似度
+- **Reciprocal Rank Fusion** — 合并三份排名列表（K=60）
+- **时间衰减** — sigmoid 衰减，可配置中点与斜率
+- **实体加分** — 包含查询相关实体的 session 会获得分数提升
+- **信任评分** — 根据明确反馈（helpful/unhelpful）的乘法信任系数
+- **Open-loop 加分** — 有未解决项的 session 获得轻微提升
+- **可选 cross-encoder reranking** — 支持 TEI、Jina、OpenRouter 提供商，对 RRF 结果做二次精排
+
+### 实体交叉查询
+
+明确指定要搜索的实体时，可以做 AND 语义筛选：
+
+```javascript
+const results = await aquifer.recall('auth 决定', {
+  entities: ['auth-middleware', 'legal-compliance'],
+  entityMode: 'all',  // 只返回同时包含两个实体的 session
+});
+```
+
+- `entityMode: 'any'`（默认）— 提升匹配任一实体的 session
+- `entityMode: 'all'` — 硬筛：只返回包含所有指定实体的 session
+
+### 信任评分与反馈
+
+Session 通过明确反馈累积信任分数。低信任的记忆在排序中会被压制，无论相关性多高。
+
+```javascript
+// 返回结果有用
+await aquifer.feedback('session-id', { verdict: 'helpful' });
+
+// 返回结果无关
+await aquifer.feedback('session-id', { verdict: 'unhelpful' });
+```
+
+- 不对称：helpful +0.05，unhelpful −0.10（低质量记忆下沉更快）
+- 排序中用乘法：trust=0.5 中性、trust=0 分数减半、trust=1.0 提升 50%
+- 完整审计记录在 `session_feedback` 表
+
+### Turn 级 Embedding
+
+不只是 session 摘要——Aquifer 对每一条有意义的 user turn 独立 embedding。
+
+- 过滤噪音：短消息、斜杠命令、确认语（"ok""好""收到"）
+- 截断 2000 字符，跳过 5 字符以下的 turn
+- 存储 turn 原文 + embedding + 位置，实现精确检索
+
+### 知识图谱
+
+内建实体提取与关系追踪：
+
+- **12 种实体类型**：person、project、concept、tool、metric、org、place、event、doc、task、topic、other
+- **实体规范化**：NFKC + 同形字映射 + 大小写折叠
+- **共现关系**：无向边，带频率追踪
+- **实体-session 映射**：哪些实体出现在哪些 session
+- **排序加分**：包含相关实体的 session 分数更高
+
+### 多租户
+
+每张表都包含 `tenant_id`（默认：`'default'`）。隔离在查询层强制执行——不会有跨租户数据泄漏。
+
+### Schema 隔离
+
+传入 `schema: 'my_app'` 给 `createAquifer()`，所有表都建在该 PostgreSQL schema 下。同一个数据库可以运行多个 Aquifer 实例互不冲突。
+
+---
+
+## API 参考
+
+### `createAquifer(config)`
+
+返回一个 Aquifer 实例。设定：
+
+```javascript
+{
+  db,          // PG 连接字符串或 Pool 实例（必填）
+  schema,      // PG schema 名称（默认 'aquifer'）
+  tenantId,    // 多租户 key（默认 'default'）
+  embed: { fn, dim },      // embedding 函数（recall 必需）
+  llm: { fn },             // LLM 函数（内置摘要必需）
+  entities: {
+    enabled,               // 启用知识图谱（默认 false）
+    scope,                 // 实体命名空间（默认 'default'）
+    mergeCall,             // 合并实体提取到摘要 LLM 调用（默认 true）
+  },
+  rank: { rrf, timeDecay, access, entityBoost },  // 权重覆盖
+}
+```
+
+#### `aquifer.init()`
+
+启动 handshake——把所有 pending migration 收敛干净并返回 StartupEnvelope。Host 在接客前应该 `await` 它。`apply` 模式拿到 `ready=false` 就是叫上层中止 startup 的信号。
+
+```javascript
+const envelope = await aquifer.init();
+// { ready, memoryMode: 'rw'|'ro'|'off', migrationMode, pendingMigrations,
+//   appliedMigrations, error, durationMs }
+```
+
+MCP consumer（`consumers/mcp.js`）已经在 `server.connect()` 前接好 `aquifer.init()`，`apply` 模式下 `ready=false` 直接 non-zero exit。
+
+#### `aquifer.listPendingMigrations()` / `aquifer.getMigrationStatus()`
+
+通过 table / column signature probe 返回 `{ required, applied, pending, lastRunAt }`；table 走 `pg_tables`，alter-only migration 会用 `information_schema.columns` 判断字段是否存在，不执行任何 DDL。适合 health check 或者 consumer 在 `init()` 前先了解 drift 状态。
+
+#### `aquifer.migrate()`
+
+执行 SQL migration（幂等）。创建表、索引、trigger 和扩展。底层：advisory lock 从 blocking 改成 `pg_try_advisory_lock` + 250ms poll + `lockTimeoutMs`（默认 30s），超时抛 `AQ_MIGRATION_LOCK_TIMEOUT`。成功返回 `{ ok: true, durationMs, notices, ddlExecuted }`；失败抛 error 带 `err.notices` / `err.failedAt`。大部分 caller 应该走 `aquifer.init()`。
+
+#### `aquifer.ensureMigrated()`
+
+Lazy idempotent wrapper——第一次调用触发 `migrate()`，之后 no-op。尊重 `migrations.mode`：`check` 只 probe、`off` 直接标 migrated 不动 DB。
+
+#### `aquifer.commit(sessionId, messages, opts)`
+
+保存 session。返回 `{ id, sessionId, isNew }`。
+
+#### `aquifer.enrich(sessionId, opts)`
+
+丰富化已 commit 的 session：摘要、turn embedding、实体提取。支持自定义 pipeline（`summaryFn`、`entityParseFn`）和 `postProcess` 后处理 hook。使用乐观锁，卡住超过 10 分钟的 processing session 可被回收。
+
+#### `aquifer.recall(query, opts)`
+
+三路混合搜索。支持 `entities` + `entityMode` 做实体感知查询。
+
+```javascript
+const results = await aquifer.recall('搜索关键字', {
+  agentId: 'main',
+  limit: 10,
+  entities: ['postgres', 'migration'],
+  entityMode: 'all',
+  weights: { rrf, timeDecay, access, entityBoost },
+});
+```
+
+#### `aquifer.feedback(sessionId, opts)`
+
+记录信任反馈。返回 `{ trustBefore, trustAfter, verdict }`。
+
+#### `aquifer.bootstrap(opts)`
+
+基于时间的 session 上下文加载器，用于新对话启动时获取近期记忆。
+
+```javascript
+const context = await aquifer.bootstrap({
+  agentId: 'main',
+  limit: 5,              // 返回 session 数量（默认 5）
+  lookbackDays: 14,      // 回溯天数（默认 14）
+  maxChars: 4000,        // 最大字符数截断（默认 4000）
+  format: 'text',        // 'text' | 'structured' | 'both'
+});
+```
+
+- 跨 session 去重，避免重复内容
+- Sentinel 过滤，排除系统噪音
+- `maxChars` 截断，确保不超出上下文预算
+
+#### `aquifer.insights.commitInsight(opts)` / `recallInsights(query, opts)` / `markStale(id)` / `supersede(oldId, newId)`
+
+从 session 窗口蒸馏出来的高阶观察（preference / pattern / frustration / workflow）。用两层 identity 拆身份：**canonical key** 描述这个观察是关于什么（claim identity，LLM 用词飘动不影响它），**idempotency key** 描述 canonical claim 的哪个 revision（body + evidenceWindow）。
+
+```javascript
+await aquifer.insights.commitInsight({
+  agentId:        'main',
+  type:           'preference',
+  canonicalClaim: 'mk 写 code 前先看 context',    // 必填，短、稳定、不带修辞与例子
+  title:          '先看 context 再动手',
+  body:           '…',
+  entities:       ['mk', 'claude code'],
+  sourceSessionIds: ['sess-a', 'sess-b'],
+  evidenceWindow:  { from: isoString, to: isoString },
+  importance:     0.9,
+});
+```
+
+写入规则：idempotency 命中返回 existing；同 canonical + 更新 evidence → INSERT + 内联 UPDATE supersede 前一 active；同 canonical + 旧/同 window → INSERT 但不 supersede（back-fill revision）；同 canonical + 同 body → stale replay 返回 existing。1.5.6 之前的旧 rows `canonical_key_v2` 保持 NULL 不 retrofit，自然淘汰。
+
+#### `aquifer.close()`
+
+关闭 PostgreSQL 连接池（仅限 Aquifer 自行创建的 pool）。
+
+---
+
+## 设定
+
+Aquifer 接受 `db` 连接（字符串或 `pg.Pool`），加上可选的 `embed` 和 `llm` 函数：
+
+```javascript
+createAquifer({
+  db: 'postgresql://user:pass@localhost/mydb',  // 或既有 pg.Pool
+  schema: 'aquifer',
+  tenantId: 'default',
+  embed: {
+    fn: myEmbedFn,             // async (texts: string[]) => number[][]
+    dim: 1024,
+  },
+  llm: {
+    fn: myLlmFn,               // async (prompt: string) => string
+  },
+  entities: {
+    enabled: true,
+    scope: 'my-app',           // 实体命名空间——与 agentId 解耦
+    mergeCall: true,
+  },
+  rank: { rrf: 0.65, timeDecay: 0.25, access: 0.10, entityBoost: 0.18 },
+  migrations: {
+    mode: 'apply',             // 'apply' | 'check' | 'off'
+    lockTimeoutMs: 30000,      // advisory lock 等待上限，超时抛 AQ_MIGRATION_LOCK_TIMEOUT
+    startupTimeoutMs: 60000,   // init() 整体 deadline
+    onEvent: null,             // (e) => void — lifecycle 观察 hook
+  },
+});
+```
+
+### 启动可观察性
+
+挂 `migrations.onEvent` 就能不解析 log 拿到 lifecycle。事件名：`init_started`、`check_completed`、`apply_started`、`apply_succeeded`、`apply_failed`。payload 带 `schema` / `mode` / 计划 / `ddlExecuted` / `durationMs`，失败时多 `error` / `failedAt` / `notices`。不挂 listener 就是零成本。
+
+### 实体作用域（Entity Scope）
+
+`entities.scope` 定义实体身份的命名空间。唯一约束是 `(tenant_id, normalized_name, entity_scope)`——不同 scope 中的同名实体会创建独立的实体。这让实体身份与 `agentId` 解耦，允许多个 agent 共享同一个实体命名空间。
+
+---
+
+## 数据库 Schema
+
+### 001-base.sql
+
+| 表 | 用途 |
+|----|------|
+| `sessions` | 原始对话数据，含 messages（JSONB）、token 数、时间戳 |
+| `session_summaries` | LLM 生成的结构化摘要，含 embedding |
+| `turn_embeddings` | 逐 turn 的 user 消息 embedding，实现精确检索 |
+
+重要索引：messages GIN、`tsvector` GiST、embedding ivfflat、tenant/agent/timestamp B-tree。
+
+### 002-entities.sql
+
+| 表 | 用途 |
+|----|------|
+| `entities` | 规范化命名实体，含类型、别名、频率、entity_scope、可选 embedding |
+| `entity_mentions` | 实体 × session 关联，含 mention 次数与上下文 |
+| `entity_relations` | 共现边（无向，`CHECK src < dst`） |
+| `entity_sessions` | 实体-session 关联，用于加分计算 |
+
+重要索引：实体名称 trigram、embedding GiST、`(tenant_id, normalized_name, entity_scope)` 唯一索引。
+
+### 003-trust-feedback.sql
+
+| 表 | 用途 |
+|----|------|
+| `session_feedback` | 明确反馈审计记录（helpful/unhelpful 判定、信任分数变动） |
+
+另在 `session_summaries` 新增 `trust_score` 字段（默认 0.5，范围 0–1）。
+
+### 005-entity-state-history.sql *(entities 启用时)*
+
+| 表 | 用途 |
+|----|------|
+| `entity_state_history` | 时序 state-change 追踪，partial `UNIQUE (tenant, agent, entity, attribute) WHERE valid_to IS NULL` 强制 at-most-one-current。out-of-order backfill 通过 predecessor/successor overlap 检查 |
+
+opt-in pipeline（`createAquifer({stateChanges: {enabled, whitelist, confidenceThreshold, timeoutMs, ...}})`）在 `enrich()` 里跑 LLM 抽取 temporal state 变化；默认 OFF 控 LLM 成本。
+
+### 006-insights.sql
+
+| 表 | 用途 |
+|----|------|
+| `insights` | 高阶反思：TSTZRANGE evidence window、importance、GIN on source_session_ids、HNSW on 1024-dim embedding，以及 `canonical_key_v2` 非 unique partial index 支撑 canonical/revision dedup contract |
+
+重要索引：`idx_insights_canonical_v2_active`（active rows + canonical key 非 null）、`idx_insights_idempotency_key`（revision key unique）。
+
+---
+
+## 故障排除
+
+**`error: type "vector" does not exist`** — pgvector 扩展未安装。以 superuser 身份执行 `CREATE EXTENSION IF NOT EXISTS vector;`，或使用自带该扩展的 `pgvector/pgvector` Docker 镜像。
+
+**`aquifer mcp requires @modelcontextprotocol/sdk and zod`** — 这些现在是常规依赖，应该会自动安装。如果看到此错误，重新执行 `npm install` 确保所有依赖就位。
+
+**Recall 没有返回结果** — 确保在 `commit` 之后执行了 `enrich`。原始 session 在丰富化（摘要 + embedding）之前不可搜索。运行 `aquifer stats` 检查摘要和 turn embedding 是否存在。
+
+**OpenClaw 工具不可见** — 在 `openclaw.json` 中使用 `mcp.servers.aquifer`，不要用插件。工具显示为 `aquifer__session_recall` 等。插件（`consumers/openclaw-plugin.js`）仅用于 session 捕获。
+
+**Embedding 提供商连接被拒** — 检查 `AQUIFER_EMBED_BASE_URL` 是否可达。本地 Ollama 需确保服务正在运行且模型已拉取（`ollama pull bge-m3`）。
+
+**启动抛 `AQ_MIGRATION_LOCK_TIMEOUT`** — 有其他 process 持有 `aquifer:<schema>` 的 migration advisory lock。可能是另一个 `aquifer.init()` 在竞争（正常；赢家跑完输家下一次会拿到 `pending=[]`），也可能是某个 crash 掉的 worker 把 lock 留着。调高 `migrations.lockTimeoutMs`，或在确认是哪个 pid 死了之后用 `SELECT pg_terminate_backend(pid) FROM pg_locks WHERE locktype='advisory'` 踢掉。
+
+**MCP process 启动就 non-zero exit** — 预期行为：`migrations.mode=apply` 且 `aquifer.init()` 回 `ready=false` 时会 abort。看 stderr 那行 `[aquifer-mcp] startup aborted` 拿 `error.code` / `failedAt`。如果需要回到旧的「lazy migrate 等第一个 tool call」行为，设 `AQUIFER_MIGRATIONS_MODE=check`（自己跑 `migrate()`）或 `=off`。
+
+---
+
+## 依赖
+
+| 包 | 用途 |
+|----|------|
+| `pg` ≥ 8.13 | PostgreSQL 客户端 |
+| `@modelcontextprotocol/sdk` ≥ 1.29 | MCP server 协议 |
+| `zod` ≥ 3.25 | Schema 验证（MCP 工具） |
+
+LLM 和 embedding 调用使用原生 HTTP——不需要额外 SDK。
+
+---
+
+## 许可证
+
+MIT