# https://github.com/CortexReach/memory-lancedb-pro 项目说明书生成时间：2026-06-26 22:02:18 UTC ## 目录 - [Plugin Overview and Architecture](#page-1) - [Memory Engine, Hybrid Retrieval, and Lifecycle](#page-2) - [Configuration, CLI Commands, and Provider Integration](#page-3) - [Known Issues, Failure Modes, and Operations](#page-4) ## Plugin Overview and Architecture ### 相关页面相关主题：[Memory Engine, Hybrid Retrieval, and Lifecycle](#page-2), [Configuration, CLI Commands, and Provider Integration](#page-3)

相关源码文件

以下源码文件用于生成本页说明： - [package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json) - [examples/new-session-distill/README.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/examples/new-session-distill/README.md) - [openclaw.plugin.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/openclaw.plugin.json) - [CHANGELOG-v1.1.0.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/CHANGELOG-v1.1.0.md) - [docs/memory_architecture_analysis.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/docs/memory_architecture_analysis.md) - [src/openclaw-memory-capability.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/openclaw-memory-capability.ts) - [index.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/index.ts)

# 插件概览与架构 ## 插件定位与核心能力 `memory-lancedb-pro` 是 OpenClaw 平台下的增强型长期记忆插件，使用 LanceDB 作为底层向量存储。当前版本为 `1.1.0-beta.11`，自我描述为："OpenClaw enhanced LanceDB memory plugin with hybrid retrieval (Vector + BM25), cross-encoder rerank, multi-scope isolation, long-context chunking, and management CLI"。资料来源：[package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json:1-50)。插件以 ESM 模块形式发布（`"type": "module"`），主入口为 `dist/index.js`，同时通过 `package.json` 中的 `openclaw.extensions` 字段向宿主注册。资料来源：[package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json:30-35)。其核心能力可归纳为以下五个维度： - **混合检索**：向量召回（Vector）与 BM25 全文召回并行，再经交叉编码器（Rerank）精排。 - **多作用域隔离**：在 agent / session / scope 维度隔离记忆，避免不同主体间的串扰。 - **长上下文切片**：对超长输入进行分块处理，避免嵌入模型的输入长度上限。 - **管理 CLI**：随包附带 `memory-pro` 系列命令（如 `stats`、`search`、`import`），通过 `commander` 构建。 - **可插拔后端**：嵌入与 LLM 通道统一走 OpenAI 兼容接口，便于替换为本地或第三方模型。 ## 系统架构与依赖 ```mermaid flowchart TB Host[OpenClaw Host] -->|加载 dist/index.js| Plugin[memory-lancedb-pro] Plugin --> Cap[openclaw-memory-capability] Plugin --> Retriever[Hybrid Retriever
Vector + BM25] Plugin --> Rerank[Cross-Encoder Rerank] Plugin --> Store[(LanceDB
memories.lance)] Plugin --> Lock{并发锁} Lock -->|本地| FsLock[proper-lockfile] Lock -->|分布式| Redis[(ioredis)] Plugin --> LLM[LLM Client
OpenAI 兼容] LLM -->|直连 baseURL| Provider[Embedding / Completion Provider] CLI[memory-pro CLI
commander] --> Plugin ``` 依赖层面，运行时强依赖 `@lancedb/lancedb ^0.26.2`、`apache-arrow 18.1.0`、`openai ^6.21.0`、`proper-lockfile ^4.1.2` 以及用于配置解析的 `json5` 与 `@sinclair/typebox`。资料来源：[package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json:25-32)。为覆盖多平台原生二进制，声明了一组 `optionalDependencies`：`@lancedb/lancedb-{darwin-arm64,darwin-x64,linux-arm64-gnu,linux-x64-gnu,win32-x64-msvc}`，并附带 `ioredis ^5.11.1` 作为可选的分布式锁后端。资料来源：[package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json:36-43)。 `scripts` 字段暴露了多组测试入口，按职责切分为 `cli-smoke`、`core-regression`、`storage-and-schema`、`llm-clients-and-auth`、`packaging-and-workflow` 等；构建使用纯 `tsc -p tsconfig.json`，并在 `prepack` 钩子中执行 `verify-package-runtime` 以保证发布前可运行。资料来源：[package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json:44-65)。 ## 关键工作流：以 `/new` 蒸馏管线为例仓库提供了一个推荐的"非阻塞蒸馏"示例，展示典型的会话级长记忆写入链路。该管线由 `command:new` 钩子（即用户输入 `/new`）触发： 1. **入队**：钩子写入一个轻量 JSON 任务文件，避免在交互路径中直接调用 LLM。 2. **消费**：用户态 systemd 服务监听收件箱，执行 Gemini Map-Reduce 对会话 JSONL 转写本进行摘要。 3. **落库**：将高信号、原子化的"经验"通过 `openclaw memory-pro import` 写入 LanceDB Pro。 4. **通知**：可选地推送一条提示消息给用户。资料来源：[examples/new-session-distill/README.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/examples/new-session-distill/README.md:1-20)。该模式的核心思想是把昂贵的 LLM 摘要操作从交互主循环剥离，避免阻塞用户体验——这与仓库 issues 中反馈的"agent_end 钩子在某些路径下不触发导致数据仅停留在内存"形成对照。资料来源：[issue #435](https://github.com/CortexReach/memory-lancedb-pro/issues/435)、[issue #850](https://github.com/CortexReach/memory-lancedb-pro/issues/850)。 ## 已知问题与限制社区反馈集中暴露了几类与架构强耦合的痛点，应在评估时一并考虑： | 问题 | 影响面 | 参考 | |------|--------|------| | ESM 中混用 CommonJS `require` | macOS/Linux 下 `memory-pro stats`、`search`、`memory_recall/store/forget` 工具链路中断 | [issue #900](https://github.com/CortexReach/memory-lancedb-pro/issues/900) | | 发布版 `dist/` 与 `src/` 不一致 | 用户拿到的构建缺失 `process.report.excludeNetwork` 防挂起保护与 rerank `top_n` 上限 | [issue #890](https://github.com/CortexReach/memory-lancedb-pro/issues/890) | | LLM 通道绕过宿主模型目录 | 无法遵循 OpenRouter 等提供方路由或宿主级模型策略 | [issue #901](https://github.com/CortexReach/memory-lancedb-pro/issues/901) | | `agent_end` 在外部安装下不发火 | 数据仅存于内存，重启即丢失 | [issue #850](https://github.com/CortexReach/memory-lancedb-pro/issues/850)、[issue #435](https://github.com/CortexReach/memory-lancedb-pro/issues/435) | | 高并发下文件锁竞争 | `captureAssistant + sessionMemory` 组合下多 agent 抢占 | [issue #659](https://github.com/CortexReach/memory-lancedb-pro/issues/659) | | 反射条目无解析机制 | 仅 `extract → store → decay → inject`，缺失 `resolve → invalidate → suppress` 路径 | [issue #447](https://github.com/CortexReach/memory-lancedb-pro/issues/447) | | 反射自触发循环 | 同一会话生成多条近重复反思 | [issue #382](https://github.com/CortexReach/memory-lancedb-pro/issues/382) | | 不支持"Dreaming"设置 | 宿主开启梦境功能时本插件未实现对应路径 | [issue #565](https://github.com/CortexReach/memory-lancedb-pro/issues/565) | | CI 回归 | PR #669 引入的 `bulkStore` 重构后 `smart-extractor-branches.mjs` 用例失败 | [issue #679](https://github.com/CortexReach/memory-lancedb-pro/issues/679) | | 备份链路断裂 | OpenClaw 2026.4.29 上 `api.resolvePath` 二次调用返回 `undefined` | [issue #731](https://github.com/CortexReach/memory-lancedb-pro/issues/731) | 另外，最新发布说明（v1.1.0-beta.10）记录了一次针对 OpenClaw 2026.3+ 的破坏性钩子迁移：`before_agent_start` 被替换为 `before_prompt_build`，并按优先级（auto-recall=10、invariants=12、derived=15）显式排序；低于 2026.3.22 的宿主会出现兼容性问题。资料来源：[CHANGELOG-v1.1.0.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/CHANGELOG-v1.1.0.md)。 ## See Also - [Hybrid Retrieval and Rerank Pipeline](#) - [Memory Lifecycle: Capture, Reflection, Decay](#) - [CLI Reference: `memory-pro` Commands](#) - [Configuration and Scope Isolation](#) - [Concurrency: File Lock vs Redis Lock](#) --- ## Memory Engine, Hybrid Retrieval, and Lifecycle ### 相关页面相关主题：[Plugin Overview and Architecture](#page-1), [Known Issues, Failure Modes, and Operations](#page-4)

相关源码文件

以下源码文件用于生成本页说明： - [src/store.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/store.ts) - [src/retriever.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/retriever.ts) - [src/embedder.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/embedder.ts) - [src/smart-extractor.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/smart-extractor.ts) - [src/decay-engine.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/decay-engine.ts) - [src/tier-manager.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/tier-manager.ts) - [src/chunker.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/chunker.ts) - [src/index.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/index.ts)

# 内存引擎、混合检索与生命周期 `memory-lancedb-pro` 是 OpenClaw 的增强型长期记忆插件，核心围绕 **LanceDB 向量数据库** 构建了一套完整的"写入—存储—检索—衰减—注入"闭环。本页聚焦内存引擎的三大支柱：基于分块的存储抽象、向量与 BM25 的混合检索流水线，以及由衰减引擎与反射管线驱动的生命周期管理。 ## 引擎总览与存储抽象插件入口 [src/index.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/index.ts) 在启动时按 `openclaw.plugin.json` 注册扩展，并按 `package.json` 中声明的 `"main": "dist/index.js"` 加载编译产物。运行时依赖的核心组件包括 `@lancedb/lancedb`、`apache-arrow`、`@sinclair/typebox`、`openai` 与 `proper-lockfile`，分别承担向量库、列式序列化、JSON Schema 校验、LLM/Embedding 客户端以及跨进程文件锁职责。资料来源：[package.json:35-50]() [src/store.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/store.ts) 是存储层的中心：它在 `memories.lance` 表中维护字段 `id / scope / text / vector / source / createdAt / updatedAt / importance / tier / tags`，并通过 `bulkStore()` 暴露批量写入接口，规避 PR #669 之前反复触发的递归路径问题。资料来源：[src/store.ts]() 写入前，长上下文会被 [src/chunker.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/chunker.ts) 切分为受 `embedding.maxInputChars` 约束的片段，避免 Embedding Provider 拒绝长文本（这是 `embedder-max-input-chars` 测试守护的不变量）。资料来源：[src/chunker.ts]() ## 混合检索与重排序检索层由 [src/embedder.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/embedder.ts) 与 [src/retriever.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/retriever.ts) 协作完成。`embedder.ts` 在缺省配置下回退到 `OPENAI_API_KEY` 并自动选择兼容的嵌入端点，当用户输入存在结构性噪声时会触发 `extraction-prompt-structural-noise` 测试所防护的清洗路径。资料来源：[src/embedder.ts]() `retriever.ts` 暴露的 `recall()` 走的是典型的 **稠密 + 稀疏融合** 流水线： 1. **向量召回**：调用 Embedding 模型生成查询向量后在 LanceDB 中执行 cosine 相似度搜索； 2. **BM25 召回**：对同一查询在倒排索引上执行词法召回，覆盖专有名词与代码片段等向量相似度难以区分的命中； 3. **Cross-Encoder Rerank**：将两个通道的候选集合并后交给重排序模型，按相关性分数重排并截断到 `top_n`（受到 issue #890 提到的 `rerank top_n cap` 守护）； 4. **作用域过滤**：依据 `scope` 字段做多作用域隔离，使不同 Agent 与 ClawTeam 之间互不可见。 ```mermaid flowchart LR Q[查询] --> E[embedder.ts
生成向量] E --> V[(LanceDB
向量召回)] Q --> B[BM25
词法召回] V --> R[retriever.ts
候选合并] B --> R R --> K[Cross-Encoder
Rerank] K --> S[scope 过滤
top_n 截断] S --> Out[注入 Prompt] ``` 资料来源：[src/retriever.ts]() ## 写入路径与智能抽取自动捕获链路由 `agent_end` 钩子触发，把整段会话交给 [src/smart-extractor.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/smart-extractor.ts) 处理。该模块按 i18n 触发器（`i18n-memory-triggers` 测试守护）判定是否进入 LLM 抽取分支，并在正则回退路径上提供 `regex-fallback-bulk-store` 测试所验证的快速通道。资料来源：[src/smart-extractor.ts]() 抽取结果经去重（社区长期诉求，参考 issue #30）、规范化后通过 `store.bulkStore()` 写入。**注意：v1.1.0-beta.10 在外部（非捆绑）安装下曾出现 `agent_end` typed hook 阻塞问题**，导致数据滞留内存而未刷盘；社区在 issue #850 与 #435 中报告了这一回归。资料来源：[src/index.ts]() ## 生命周期、衰减与反射闭环记忆的生命周期由 [src/tier-manager.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/tier-manager.ts) 与 [src/decay-engine.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/decay-engine.ts) 协同管理。Tier 将记忆按时间/重要性划分为 `invariants / derived / ephemeral` 三档，分别配置不同的 `maxAgeDays`（默认 invariant 为 45 天）。`decay-engine.ts` 周期性扫描并按策略降级或淘汰过期项。资料来源：[src/tier-manager.ts]()、[src/decay-engine.ts]() 反射管线呈现 **extract → store → decay → inject** 的单向流水线。社区在 issue #447 中指出该流水线缺乏 `resolve → invalidate → suppress` 的反向解析路径，导致过期反射项只能等到自然到期才退出；同时 issue #382 报告了反射自触发循环，同一会话内可能产生 4 条近重复反射项。这些都是生命周期管理上的已知痛点。资料来源：[src/smart-extractor.ts]() ## 钩子优先级与并发保护为兼容 OpenClaw 2026.3+，插件已将 `before_agent_start` 迁移至 `before_prompt_build`，并显式声明优先级：**auto-recall=10、invariants=12、derived=15**，以消除"Legacy before_agent_start"弃用警告。资料来源：[src/index.ts]() 并发写入由 `proper-lockfile` 保护本地文件锁，社区在 issue #659 中提议以 Redis 分布式锁扩展以应对多 Agent 高并发场景，目前仍属可选增强（`ioredis` 仅为 `optionalDependencies`）。资料来源：[package.json:51-58]() ## 故障模式与运维提示 - **ESM/CJS 混用**：v1.1.0-beta.10 在 macOS/Linux 下因残留 CommonJS `require()` 导致 LanceDB 加载失败（issue #900），升级前请确认 `dist/` 已重建。 - **dist 陈旧**：master 分支的 `dist/` 可能落后于 `src/`（issue #890），建议在升级后执行 `npm run build && npm run verify-package-runtime`。 - **备份异常**：`runBackup()` 在 OpenClaw 2026.4.29 上因 `api.resolvePath` 双调用返回 undefined 而抛 `TypeError`（issue #731），需等待 host 修复或绕过备份任务。 - **配置漂移**：`memory-pro` CLI 与 plugin 注册时会重复打印双重记忆提示与 rerank 成本提醒（issue #888），可通过 CLI 感知日志约定降级为 `debug`。 ## See Also - 配置与作用域隔离：参见 `docs/scope-and-multi-tenant.md`（若存在） - CLI 工具链：参见 `docs/cli-reference.md`（若存在） - 反射与衰减策略：参见 `docs/lifecycle-tuning.md`（若存在） --- ## Configuration, CLI Commands, and Provider Integration ### 相关页面相关主题：[Plugin Overview and Architecture](#page-1), [Known Issues, Failure Modes, and Operations](#page-4)

相关源码文件

以下源码文件用于生成本页说明： - [package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json) - [cli.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/cli.ts) - [src/llm-client.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/llm-client.ts) - [src/llm-oauth.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/llm-oauth.ts) - [src/migrate.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/migrate.ts) - [src/memory-upgrader.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/memory-upgrader.ts) - [src/memory-compactor.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/memory-compactor.ts) - [examples/new-session-distill/README.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/examples/new-session-distill/README.md)

# 配置、CLI 命令与 Provider 集成本页聚焦 `memory-lancedb-pro` 的三类对外接触面：插件配置 schema、运维 CLI、以及 LLM / Embedding Provider 的接入方式。这三者是部署和日常使用该插件最常打交道的部分，也是社区问题的高发区（参见 [Issue #565](https://github.com/CortexReach/memory-lancedb-pro/issues/565)、[#901](https://github.com/CortexReach/memory-lancedb-pro/issues/901)、[#731](https://github.com/CortexReach/memory-lancedb-pro/issues/731)）。 ## 一、插件配置结构 `memory-lancedb-pro` 在 `package.json` 中以 `openclaw.extensions` 字段声明入口，并通过 `openclaw.plugin.json` 注册元数据。插件核心入口位于 `dist/index.js`（由 `npm run build` 即 `tsc -p tsconfig.json` 编译生成）[package.json]()。运行时的配置涵盖：嵌入模型（`embedding`）、LLM 客户端（`llm`）、会话存储（`sessionMemory`）、自动召回（`captureAssistant`、`autoRecall`）、反思（`memory-reflection`）、备份（`backup`）以及多作用域隔离（`scope`）。依赖层面，核心依赖锁定 `@lancedb/lancedb ^0.26.2`、`apache-arrow 18.1.0`、`openai ^6.21.0`、`proper-lockfile ^4.1.2`；平台原生绑定按 `darwin-arm64`、`darwin-x64`、`linux-arm64-gnu`、`linux-x64-gnu`、`win32-x64-msvc` 通过 `optionalDependencies` 懒加载 [package.json]()。`ioredis` 同样为可选依赖，仅在高并发分布式锁场景（[Issue #659](https://github.com/CortexReach/memory-lancedb-pro/issues/659)）启用。配置变更完成后必须重新构建：`npm run build`，随后可通过 `npm run verify-package-runtime` 进行打包前自检 [package.json]()。 ## 二、CLI 命令参考 CLI 由 `cli.ts` 装配，依赖 `commander ^14.0.0` 解析子命令，运行时通过 `jiti` 加载 TypeScript 模块 [package.json]()。社区最常用的命令包括： | 命令 | 用途 | 典型上下文 | | --- | --- | --- | | `memory-pro stats` | 输出 LanceDB 表行数、向量维度、容量 | 启动健康检查 | | `memory-pro search ""` | 混合检索（Vector + BM25），可指定 `topK` 与 `scope` | 调试召回质量 | | `memory-pro import ` | 从 JSONL/JSON 批量导入 lessons | `/new` 蒸馏流水线 | | `memory-pro backup` / `restore` | 备份目录到 `backup.dir` 指定路径 | 每日 cron | | `memory-pro migrate` | 旧 schema → 新 schema 升级 | 跨大版本升级 | | `memory-pro oauth-login` | 触发 OAuth 设备码登录流程 | 首次接入 OAuth Provider | 测试入口被拆分为多组：`test:cli-smoke`、`test:core-regression`、`test:storage-and-schema`、`test:llm-clients-and-auth`、`test:packaging-and-workflow`，通过 `scripts/run-ci-tests.mjs` 执行 [package.json]()。`v1.1.0-beta.10` 曾因 CommonJS `require()` 在 ESM 中被引入，导致 macOS / Linux 下 `memory-pro stats` 等命令直接崩溃（[Issue #900](https://github.com/CortexReach/memory-lancedb-pro/issues/900)）。 ## 三、LLM 与 Embedding Provider 集成 `src/llm-client.ts` 提供 `createApiKeyClient`，它构造最小化 OpenAI Chat Completions 请求并直接 POST 到 `llm.baseURL`，因此**不会**经过宿主网关的模型目录（[Issue #901](https://github.com/CortexReach/memory-lancedb-pro/issues/901)）。若依赖 OpenRouter 或其它路由器进行模型路由，必须显式将 `llm.baseURL` 指向该 Provider，并在请求体中携带 `model` 字段，否则会绕过 catalog 命中默认模型。 `src/llm-oauth.ts` 负责 OAuth 设备码流程，CLI 中通过 `memory-pro oauth-login` 触发（[package.json]() 中 `cli-oauth-login` 测试覆盖该路径）。OAuth 客户端的鉴权信息缓存在本地，后续 LLM 请求会自动附加 `Authorization: Bearer `。 Embedding Provider 默认通过 `embedding.apiKey` 或 `OPENAI_API_KEY` 环境变量接入；若任一为空则会抛错 `embedding.apiKey is required`（参见 [Issue #39](https://github.com/CortexReach/memory-lancedb-pro/issues/39)，早期版本曾因多余的大括号导致误报）。 ## 四、迁移、升级与备份 `src/migrate.ts` 处理 schema 迁移，新增字段（如 `metadata.v2`、`tier1` 计数器）会自动以默认回填。`src/memory-upgrader.ts` 提供启动期自检——检查 `process.report.excludeNetwork` 是否被设、以及 rerank `top_n` 是否超过上限；这两项若缺失则会触发构建产物与源码不一致告警（[Issue #890](https://github.com/CortexReach/memory-lancedb-pro/issues/890)）。 `src/memory-compactor.ts` 配合 `backup.runBackup()` 执行目录归档。需要注意：`api.resolvePath` 在 OpenClaw 2026.4.29 中必须**只调用一次**，重复调用会返回 `undefined` 并导致 `mkdir` 抛出 `ERR_INVALID_ARG_TYPE`（[Issue #731](https://github.com/CortexReach/memory-lancedb-pro/issues/731)）。建议备份目录使用绝对路径，或显式拼装 `${base}/${date}`。 ## 五、典型数据流 ```mermaid flowchart LR A[用户配置] --> B[plugin manifest] B --> C[index.ts 注册] C --> D{Provider 类型} D -- API Key --> E[llm-client.createApiKeyClient] D -- OAuth --> F[llm-oauth.ts 设备码] E --> G[OpenAI 兼容 baseURL] F --> G C --> H[CLI cli.ts] H --> I[stats / search / import] C --> J[migrate + upgrader] J --> K[memories.lance] ``` ## 六、常见故障速查 1. **`memory-pro stats` 报 `Dynamic require not supported`**：通常是 `dist/` 与 `src/` 不同步，需 `npm run build` 后重新加载（[Issue #900](https://github.com/CortexReach/memory-lancedb-pro/issues/900)）。 2. **OpenRouter 路由失效**：因为 LLM 通道绕过了宿主模型目录，需手动指定 `llm.baseURL` 与 `model`（[Issue #901](https://github.com/CortexReach/memory-lancedb-pro/issues/901)）。 3. **备份任务崩溃**：检查 `runBackup()` 中 `api.resolvePath` 是否被双调用（[Issue #731](https://github.com/CortexReach/memory-lancedb-pro/issues/731)）。 4. **外部安装下 `agent_end` 不触发**：`agent_end` 在 `~/.openclaw/workspace/plugins/memory-lancedb-pro` 模式下未注册，导致数据滞留内存（[Issue #850](https://github.com/CortexReach/memory-lancedb-pro/issues/850)）。 5. **dreaming 设置无响应**：插件自身不实现 dreaming，需在宿主侧确认（[Issue #565](https://github.com/CortexReach/memory-lancedb-pro/issues/565)）。 ## 参见 - Hook 迁移与 `before_prompt_build` 优先级：[`index.ts`](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/index.ts) - 反思管线与 resolve 缺失：[Issue #447](https://github.com/CortexReach/memory-lancedb-pro/issues/447) - 蒸馏 Worker 集成示例：[examples/new-session-distill/README.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/examples/new-session-distill/README.md) --- ## Known Issues, Failure Modes, and Operations ### 相关页面相关主题：[Memory Engine, Hybrid Retrieval, and Lifecycle](#page-2), [Configuration, CLI Commands, and Provider Integration](#page-3)

相关源码文件

以下源码文件用于生成本页说明： - [src/index.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/index.ts) - [src/llm-client.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/llm-client.ts) - [src/redis-lock.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/redis-lock.ts) - [docs/lock-management.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/docs/lock-management.md) - [docs/openclaw-integration-playbook.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/docs/openclaw-integration-playbook.md) - [docs/release-checklist.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/docs/release-checklist.md) - [test/smart-extractor-branches.mjs](https://github.com/CortexReach/memory-lancedb-pro/blob/main/test/smart-extractor-branches.mjs) - [package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)

# Known Issues, Failure Modes, and Operations 本页汇总 `memory-lancedb-pro` 在生产环境中已知的故障模式、运行陷阱以及运维建议，主要面向负责部署、监控和排障的 OpenClaw 集成方与 SRE。 ## 目的与范围 `memory-lancedb-pro` 作为 OpenClaw 的外挂记忆插件，其稳定性高度依赖外部组件（宿主 OpenClaw 网关、嵌入/LLM API、文件系统锁、Redis、平台原生 LanceDB 绑定等）。当任意一环异常时，可能表现为：会话内容未持久化、检索结果缺失、备份失败、CI 红屏等。本页整理社区与源码中暴露出的典型失败模式，帮助运维人员快速定位。 ## 常见失败模式 ### 1. 生命周期与钩子（Hook）问题 - **`agent_end` 未触发导致记忆丢失**：当 OpenClaw 网关通过 `SIGTERM` 重启时，处于活跃状态的会话不会触发 `agent_end`，因此仅在钩子内落盘的自动捕获内容将永久丢失。资料来源：[docs/openclaw-integration-playbook.md:1-1]() - **外部安装下钩子被屏蔽**：`v1.1.0-beta.10` 之后，在 `~/.openclaw/workspace/plugins/memory-lancedb-pro` 外部安装模式下，`agent_end` typed hook 被屏蔽，数据只停留在内存中，从不刷盘至 `memories.lance`。资料来源：[src/index.ts:1-1]() - **钩子迁移破坏旧版本兼容**：`v1.1.0-beta.10` 将 `before_agent_start` 迁移为 `before_prompt_build` 并设置显式优先级（auto-recall=10, invariants=12, derived=15），OpenClaw < 2026.3.22 的宿主将无法加载该插件。资料来源：[package.json:1-1]() ### 2. LLM / 嵌入链路问题 - **LLM 直连绕过宿主模型目录**：`src/llm-client.ts` 中的 `createApiKeyClient` 直接以最小化 `chat-completions` 请求 POST 至 `llm.baseURL`，因此 OpenRouter 等提供商路由、自定义模型配置无法生效。资料来源：[src/llm-client.ts:1-1]() - **嵌入 API Key 缺失**：若 `embedding.apiKey` 未直接配置且 `OPENAI_API_KEY` 环境变量也未设置，启动时会抛出 "embedding.apiKey is required" 错误。资料来源：[src/index.ts:1-1]() ### 3. 并发与文件锁 - **`captureAssistant` + `sessionMemory.enabled` 高并发竞争**：多个 Agent 并行写入时，本地文件锁成为瓶颈。社区在 #643 提出并已在 #659 中提议使用 Redis 分布式锁替代。资料来源：[src/redis-lock.ts:1-1]() - **锁选型决策**：在多进程场景下默认走 `proper-lockfile`，可选 `ioredis`（`optionalDependencies`）作为分布式锁后端；启用 Redis 锁需在配置中显式声明。资料来源：[docs/lock-management.md:1-1](), [package.json:1-1]() ### 4. 构建与发布 - **v1.1.0-beta.10 在 macOS/Linux 加载回归**：ESM 模块内残留 `require()`，使 `memory-pro stats/search` 与 `memory_recall/store/forget` 工具调用崩溃。资料来源：[package.json:1-1]() - **dist 与 src 不同步**：在 master 干净 checkout 上执行 `npm run build` 会改写两个已提交的 dist 文件——`process.report.excludeNetwork` 挂起防护与 `rerank top_n` 上限缺失。资料来源：[docs/release-checklist.md:1-1]() - **CI 红屏**：`smart-extractor-branches.mjs` 自 PR #669 `bulkStore` 重构后于 `test/smart-extractor-branches.mjs:497` 持续失败，导致 `core-regression` 任务挂红。资料来源：[test/smart-extractor-branches.mjs:1-1]() ### 5. 反思（Reflection）管道 - **无 resolve / invalidate 路径**：反思条目只能自然 `decay`，一旦写入便每次新会话都会被注入，直至 `maxAgeDays`（默认 45 天）到期。资料来源：[docs/openclaw-integration-playbook.md:1-1]() - **反思自触发循环**：同一会话可生成 4 条近似反思，导致存储污染；可结合 `#357` 中的 `OPENCLAW_EXTENSION_API_PATH` 变通方案缓解。资料来源：[src/index.ts:1-1]() ### 6. 备份与杂项 - **每日备份失败**：`runBackup()` 在 OpenClaw 2026.4.29 上因 `api.resolvePath` 被重复调用返回 `undefined`，导致 `mkdir` 抛出 `ERR_INVALID_ARG_TYPE`。资料来源：[src/index.ts:1-1]() - **Dreaming 设置无对应实现**：宿主 UI 暴露的 "Dreaming" 开关在 `memory-lancedb-pro` 中并无对应实现，开启后无效果。资料来源：[package.json:1-1]() - **重复日志噪音**：dual-memory 提示与 rerank 成本告警绕过 `isCliMode()` 抑制约定，每次注册与 CLI 命令都会重复打印。资料来源：[src/index.ts:1-1]() ## 失败模式速查表 | 类别 | 触发条件 | 首选排障动作 | |------|---------|------------| | 钩子丢失 | 网关 SIGTERM / 外部安装 | 验证钩子签名、检查安装路径 | | LLM 路由失效 | 使用 OpenRouter 或自定义网关 | 暂用直连或调整 `llm.baseURL` | | 文件锁竞争 | 高并发 + `captureAssistant` | 切换 Redis 分布式锁 | | dist 漂移 | 提交后未 `npm run build` | 发布前重新构建并复核 diff | | 反思污染 | 长会话 + 启用反思 | 提高 `maxAgeDays` 上限或禁用反思 | | 备份 TypeError | OpenClaw ≥ 2026.4.29 | 回退宿主版本或应用补丁 | ## 运维建议 1. **升级前对照发布清单**：参照 [docs/release-checklist.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/docs/release-checklist.md) 校验宿主版本、平台原生依赖（`@lancedb/lancedb-{platform}-{arch}-{abi}`）与 Node 22/24 兼容性。 2. **启用 CLI 感知日志**：将 `api.logger` 替换为 CLI 模式下的 `debug` 级别，避免双重打印影响日志聚合。资料来源：[src/index.ts:1-1]() 3. **高并发场景预先切换 Redis 锁**：将 `ioredis` 作为运行时依赖、配置分布式锁端点，并监控锁等待时长。资料来源：[src/redis-lock.ts:1-1]() 4. **CI 失败立即隔离**：在 `core-regression` 任务通过前禁止合并 PR；可通过 `npm run test:core-regression` 单独复跑。资料来源：[package.json:1-1]() 5. **构建后强制重建 dist**：发布前执行 `npm run verify-package-runtime` 以确保 `dist` 与 `src` 一致。资料来源：[package.json:1-1]() ```mermaid flowchart LR A[OpenClaw 网关] --> B[agent_end / before_prompt_build 钩子] B --> C{数据落地路径} C -->|正常| D[memories.lance] C -->|钩子被屏蔽| E[内存丢失] B --> F{并发写入} F -->|单进程| G[proper-lockfile] F -->|多进程| H[Redis 分布式锁] B --> I{反思管道} I -->|写入| J[自动注入直至过期] I -->|无 resolve| K[需手动清理] ``` ## See Also - [Architecture Overview](architecture-overview.md) - [Configuration Reference](configuration-reference.md) - [Lock Management](lock-management.md) - [Release Checklist](release-checklist.md) --- --- ## Doramagic 踩坑日志项目：CortexReach/memory-lancedb-pro 摘要：发现 18 个潜在踩坑项，其中 9 个为 high/blocking；最高优先级：安装坑 - 来源证据：Memory lost on gateway restart: agent_end hook never fires。 ## 1. 安装坑 · 来源证据：Memory lost on gateway restart: agent_end hook never fires - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Memory lost on gateway restart: agent_end hook never fires - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/435 | 来源类型 github_issue 暴露的待验证使用条件。 ## 2. 安装坑 · 来源证据：[Feature Request] Dreaming support — implement OpenClaw dreaming protocol when available - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Dreaming support — implement OpenClaw dreaming protocol when available - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/813 | 来源类型 github_issue 暴露的待验证使用条件。 ## 3. 安装坑 · 来源证据：ci: smart-extractor-branches.mjs test failing since PR #669 bulkStore refactor - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ci: smart-extractor-branches.mjs test failing since PR #669 bulkStore refactor - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/679 | 来源类型 github_issue 暴露的待验证使用条件。 ## 4. 安装坑 · 来源证据：v1.1.0-beta.10 release regressed LanceDB loading on macOS/Linux (Dynamic require not supported) - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.1.0-beta.10 release regressed LanceDB loading on macOS/Linux (Dynamic require not supported) - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/900 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 5. 配置坑 · 来源证据："memory-lancedb-pro" does not support dreaming settings - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题："memory-lancedb-pro" does not support dreaming settings - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/565 | 来源类型 github_issue 暴露的待验证使用条件。 ## 6. 安全/权限坑 · 来源证据：#395 — Reflection Items Lack Resolution Mechanism - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：#395 — Reflection Items Lack Resolution Mechanism - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/447 | 来源类型 github_issue 暴露的待验证使用条件。 ## 7. 安全/权限坑 · 来源证据：Bug: Reflection self-triggers in a loop — same session generates 4 near-identical reflections - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Bug: Reflection self-triggers in a loop — same session generates 4 near-identical reflections - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/382 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 8. 安全/权限坑 · 来源证据：Memory LLM completion lane bypasses the host model catalog (cannot honor OpenRouter provider routing or other model con… - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Memory LLM completion lane bypasses the host model catalog (cannot honor OpenRouter provider routing or other model config) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/901 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 9. 安全/权限坑 · 来源证据：memory-lancedb-pro @ master (post v1.1.0-beta.10): agent_end hook blocked under external (non-bundled) install — data s… - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：memory-lancedb-pro @ master (post v1.1.0-beta.10): agent_end hook blocked under external (non-bundled) install — data stays in-memory, never flushes to memorie… - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/850 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 10. 安装坑 · 来源证据：Committed dist is stale relative to src: shipped builds miss the process.report.excludeNetwork hang guard and the reran… - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Committed dist is stale relative to src: shipped builds miss the process.report.excludeNetwork hang guard and the rerank top_n cap - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/890 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 11. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/CortexReach/memory-lancedb-pro | README/documentation is current enough for a first validation pass. ## 12. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/CortexReach/memory-lancedb-pro | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/CortexReach/memory-lancedb-pro | no_demo; severity=medium ## 14. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/CortexReach/memory-lancedb-pro | no_demo; severity=medium ## 15. 安全/权限坑 · 来源证据：Dual-memory hint and rerank cost advisory bypass the CLI-aware logging convention, repeating on every registration and… - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Dual-memory hint and rerank cost advisory bypass the CLI-aware logging convention, repeating on every registration and every CLI command - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/888 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 16. 安全/权限坑 · 来源证据：Solution: Redis Distributed Lock for High Concurrency (extends #643) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Solution: Redis Distributed Lock for High Concurrency (extends #643) - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/659 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。 ## 17. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/CortexReach/memory-lancedb-pro | issue_or_pr_quality=unknown ## 18. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/CortexReach/memory-lancedb-pro | release_recency=unknown