Doramagic.ai
English

Doramagic 项目包 · 项目说明书

memory-lancedb-pro 项目

OpenClaw 的增强版 LanceDB 记忆插件，支持混合检索（向量 + BM25）、Cross-Encoder 重排序、多作用域隔离与管理 CLI。

Plugin Overview and Architecture

memory-lancedb-pro 是 OpenClaw 平台下的增强型长期记忆插件，使用 LanceDB 作为底层向量存储。当前版本为 1.1.0-beta.11，自我描述为："OpenClaw enhanced LanceDB memory plugin with hybrid retrieval (Vector + BM25), cross-encoder rera...

章节 相关页面

继续阅读本节完整说明和来源证据。

插件概览与架构

插件定位与核心能力

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。

插件以 ESM 模块形式发布（"type": "module"），主入口为 dist/index.js，同时通过 package.json 中的 openclaw.extensions 字段向宿主注册。资料来源：package.json。其核心能力可归纳为以下五个维度：

  • 混合检索：向量召回（Vector）与 BM25 全文召回并行，再经交叉编码器（Rerank）精排。
  • 多作用域隔离：在 agent / session / scope 维度隔离记忆，避免不同主体间的串扰。
  • 长上下文切片：对超长输入进行分块处理，避免嵌入模型的输入长度上限。
  • 管理 CLI：随包附带 memory-pro 系列命令（如 stats、search、import），通过 commander 构建。
  • 可插拔后端：嵌入与 LLM 通道统一走 OpenAI 兼容接口，便于替换为本地或第三方模型。

系统架构与依赖

flowchart TB
    Host[OpenClaw Host] -->|加载 dist/index.js| Plugin[memory-lancedb-pro]
    Plugin --> Cap[openclaw-memory-capability]
    Plugin --> Retriever[Hybrid Retriever<br/>Vector + BM25]
    Plugin --> Rerank[Cross-Encoder Rerank]
    Plugin --> Store[(LanceDB<br/>memories.lance)]
    Plugin --> Lock{并发锁}
    Lock -->|本地| FsLock[proper-lockfile]
    Lock -->|分布式| Redis[(ioredis)]
    Plugin --> LLM[LLM Client<br/>OpenAI 兼容]
    LLM -->|直连 baseURL| Provider[Embedding / Completion Provider]
    CLI[memory-pro CLI<br/>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。为覆盖多平台原生二进制，声明了一组 optionalDependencies：@lancedb/lancedb-{darwin-arm64,darwin-x64,linux-arm64-gnu,linux-x64-gnu,win32-x64-msvc}，并附带 ioredis ^5.11.1 作为可选的分布式锁后端。资料来源：package.json。

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。

关键工作流：以 `/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。该模式的核心思想是把昂贵的 LLM 摘要操作从交互主循环剥离，避免阻塞用户体验——这与仓库 issues 中反馈的"agent_end 钩子在某些路径下不触发导致数据仅停留在内存"形成对照。资料来源：issue #435、issue #850。

已知问题与限制

社区反馈集中暴露了几类与架构强耦合的痛点，应在评估时一并考虑：

问题影响面参考
ESM 中混用 CommonJS requiremacOS/Linux 下 memory-pro stats、search、memory_recall/store/forget 工具链路中断issue #900
发布版 dist/ 与 src/ 不一致用户拿到的构建缺失 process.report.excludeNetwork 防挂起保护与 rerank top_n 上限issue #890
LLM 通道绕过宿主模型目录无法遵循 OpenRouter 等提供方路由或宿主级模型策略issue #901
agent_end 在外部安装下不发火数据仅存于内存，重启即丢失issue #850、issue #435
高并发下文件锁竞争captureAssistant + sessionMemory 组合下多 agent 抢占issue #659
反射条目无解析机制仅 extract → store → decay → inject，缺失 resolve → invalidate → suppress 路径issue #447
反射自触发循环同一会话生成多条近重复反思issue #382
不支持"Dreaming"设置宿主开启梦境功能时本插件未实现对应路径issue #565
CI 回归PR #669 引入的 bulkStore 重构后 smart-extractor-branches.mjs 用例失败issue #679
备份链路断裂OpenClaw 2026.4.29 上 api.resolvePath 二次调用返回 undefinedissue #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。

See Also

资料来源：examples/new-session-distill/README.md。该模式的核心思想是把昂贵的 LLM 摘要操作从交互主循环剥离，避免阻塞用户体验——这与仓库 issues 中反馈的"agent_end 钩子在某些路径下不触发导致数据仅停留在内存"形成对照。资料来源：issue #435、issue #850。

Memory Engine, Hybrid Retrieval, and Lifecycle

memory-lancedb-pro 是 OpenClaw 的增强型长期记忆插件，核心围绕 LanceDB 向量数据库 构建了一套完整的"写入—存储—检索—衰减—注入"闭环。本页聚焦内存引擎的三大支柱：基于分块的存储抽象、向量与 BM25 的混合检索流水线，以及由衰减引擎与反射管线驱动的生命周期管理。

章节 相关页面

继续阅读本节完整说明和来源证据。

内存引擎、混合检索与生命周期

memory-lancedb-pro 是 OpenClaw 的增强型长期记忆插件，核心围绕 LanceDB 向量数据库 构建了一套完整的"写入—存储—检索—衰减—注入"闭环。本页聚焦内存引擎的三大支柱：基于分块的存储抽象、向量与 BM25 的混合检索流水线，以及由衰减引擎与反射管线驱动的生命周期管理。

引擎总览与存储抽象

插件入口 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 是存储层的中心：它在 memories.lance 表中维护字段 id / scope / text / vector / source / createdAt / updatedAt / importance / tier / tags，并通过 bulkStore() 暴露批量写入接口，规避 PR #669 之前反复触发的递归路径问题。资料来源：src/store.ts

写入前，长上下文会被 src/chunker.ts 切分为受 embedding.maxInputChars 约束的片段，避免 Embedding Provider 拒绝长文本（这是 embedder-max-input-chars 测试守护的不变量）。资料来源：src/chunker.ts

混合检索与重排序

检索层由 src/embedder.ts 与 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 之间互不可见。
flowchart LR
    Q[查询] --> E[embedder.ts<br/>生成向量]
    E --> V[(LanceDB<br/>向量召回)]
    Q --> B[BM25<br/>词法召回]
    V --> R[retriever.ts<br/>候选合并]
    B --> R
    R --> K[Cross-Encoder<br/>Rerank]
    K --> S[scope 过滤<br/>top_n 截断]
    S --> Out[注入 Prompt]

资料来源：src/retriever.ts

写入路径与智能抽取

自动捕获链路由 agent_end 钩子触发，把整段会话交给 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 与 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（若存在）

资料来源：src/retriever.ts

Configuration, CLI Commands, and Provider Integration

本页聚焦 memory-lancedb-pro 的三类对外接触面：插件配置 schema、运维 CLI、以及 LLM / Embedding Provider 的接入方式。这三者是部署和日常使用该插件最常打交道的部分，也是社区问题的高发区（参见 Issue 565、901、731）。

章节 相关页面

继续阅读本节完整说明和来源证据。

配置、CLI 命令与 Provider 集成

本页聚焦 memory-lancedb-pro 的三类对外接触面：插件配置 schema、运维 CLI、以及 LLM / Embedding Provider 的接入方式。这三者是部署和日常使用该插件最常打交道的部分，也是社区问题的高发区（参见 Issue #565、#901、#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）启用。

配置变更完成后必须重新构建：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 "<q>"混合检索（Vector + BM25），可指定 topK 与 scope调试召回质量
memory-pro import <file>从 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）。

三、LLM 与 Embedding Provider 集成

src/llm-client.ts 提供 createApiKeyClient，它构造最小化 OpenAI Chat Completions 请求并直接 POST 到 llm.baseURL，因此不会经过宿主网关的模型目录（Issue #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 <token>。

Embedding Provider 默认通过 embedding.apiKey 或 OPENAI_API_KEY 环境变量接入；若任一为空则会抛错 embedding.apiKey is required（参见 Issue #39，早期版本曾因多余的大括号导致误报）。

四、迁移、升级与备份

src/migrate.ts 处理 schema 迁移，新增字段（如 metadata.v2、tier1 计数器）会自动以默认回填。src/memory-upgrader.ts 提供启动期自检——检查 process.report.excludeNetwork 是否被设、以及 rerank top_n 是否超过上限；这两项若缺失则会触发构建产物与源码不一致告警（Issue #890）。

src/memory-compactor.ts 配合 backup.runBackup() 执行目录归档。需要注意：api.resolvePath 在 OpenClaw 2026.4.29 中必须只调用一次，重复调用会返回 undefined 并导致 mkdir 抛出 ERR_INVALID_ARG_TYPE（Issue #731）。建议备份目录使用绝对路径，或显式拼装 ${base}/${date}。

五、典型数据流

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）。
  2. OpenRouter 路由失效：因为 LLM 通道绕过了宿主模型目录，需手动指定 llm.baseURL 与 model（Issue #901）。
  3. 备份任务崩溃：检查 runBackup() 中 api.resolvePath 是否被双调用（Issue #731）。
  4. 外部安装下 agent_end 不触发：agent_end 在 ~/.openclaw/workspace/plugins/memory-lancedb-pro 模式下未注册，导致数据滞留内存（Issue #850）。
  5. dreaming 设置无响应：插件自身不实现 dreaming，需在宿主侧确认（Issue #565）。

参见

来源：https://github.com/CortexReach/memory-lancedb-pro / 项目说明书

Known Issues, Failure Modes, and Operations

本页汇总 memory-lancedb-pro 在生产环境中已知的故障模式、运行陷阱以及运维建议，主要面向负责部署、监控和排障的 OpenClaw 集成方与 SRE。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 1. 生命周期与钩子（Hook）问题

继续阅读本节完整说明和来源证据。

章节 2. LLM / 嵌入链路问题

继续阅读本节完整说明和来源证据。

章节 3. 并发与文件锁

继续阅读本节完整说明和来源证据。

目的与范围

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 上限或禁用反思
备份 TypeErrorOpenClaw ≥ 2026.4.29回退宿主版本或应用补丁

运维建议

  1. 升级前对照发布清单：参照 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
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
  • Configuration Reference
  • Lock Management
  • Release Checklist

来源：https://github.com/CortexReach/memory-lancedb-pro / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Memory lost on gateway restart: agent_end hook never fires

可能阻塞安装或首次运行。

high 来源证据：[Feature Request] Dreaming support — implement OpenClaw dreaming protocol when available

可能增加新用户试用和生产接入成本。

high 来源证据：ci: smart-extractor-branches.mjs test failing since PR #669 bulkStore refactor

可能影响升级、迁移或版本选择。

high 来源证据：v1.1.0-beta.10 release regressed LanceDB loading on macOS/Linux (Dynamic require not supported)

可能阻塞安装或首次运行。

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录