dsh-memory-tdai

LIMITATIONS

Known limitations

### 1. 未配置 embedding 时，检索是"关键词模式"，不是"语义模式" **这是什么意思？** 记忆检索有两种引擎，能力差别很大： | 检索方式 | 工作方式 | 例子（记忆内容："用户喜欢喝咖啡"） | |---|---|---| | **关键词检索（默认）** | 按字面词匹配（jieba 中文分词 + SQLite FTS5） | 问"咖啡" ✅ 命中；问"我早上喝什么提神" ❌ 查不到（句子里没有"咖啡"二字） | | **向量检索（需配置）** | 把文字转成向量，按语义距离匹配 | 问"提神的饮品" ✅ 也能命中"咖啡" | **为什么会这样？** 向量化需要一个 embedding API（把文字变成数字向量的服务）。DeepSeek 官方 API 目前**没有** embedding 端点；插件也不会在未配置的情况下偷偷调用第三方服务。所以默认走关键词模式——够用，但"望文生义"。 **怎么升级？** 在插件配置（bundle 行 config）里提供一个 **OpenAI 兼容的 embedding 端点**（OpenAI `text-embedding-3-small`、阿里云百炼 `qwen3-embedding`、硅基流动、vLLM/Ollama 自托管等皆可），插件自动切换为"向量 + 关键词"混合检索（RRF 融合排序），语义匹配能力大幅增强。不配置也不影响使用，只是检索更"字面"。 > jieba 是中文分词器——"我喜欢喝咖啡"入库前会被切成"我/喜欢/喝/咖啡"再建立索引，这正是 FTS5 能匹配中文的关键。关键词模式对中文检索已经可用，只是做不到"同义替换"级别的语义理解。 --- ### 2. L1 记忆抽取是"后台渐进式"，刚装好的头几轮查不到结构化记忆 **这是什么意思？** 记忆分层里，**L0 原始对话**是每轮对话结束就立刻落盘的（纯本地写文件，零成本）；但 **L1 原子记忆**（把对话提炼成"用户喜欢用中文回复"这种颗粒度的结构化记忆）需要**调用一次大模型**来完成抽取，有 token 成本，所以不是每轮都跑。 **节奏机制（warmup 预热）**：插件默认攒够 **5 轮对话**才触发一次 L1 抽取。为了让新用户尽快看到效果，触发阈值是渐进的：**1 → 2 → 4 → 5**（第 1 轮就跑一次让你立刻体验，之后每轮倍增，稳定在每 5 轮）。 **对使用的影响**： - 刚装好、聊了没几轮时，`memory_search`（查结构化记忆）大概率返回空——L1 还没提炼完。 - 但 **`conversation_search` 始终可用**——L0 原始对话每轮都落盘，随时能查原文。 - 正常使用一两天后，L1/L2/L3 各层会自然积累起来。 --- ### 3. 本插件不能用"动态插件"方式加载，必须以 bundle 方式安装 **背景**：DSH 插件有两条安装路径： | 方式 | 说明 | 本插件 | |---|---|---| | **bundle 方式**（推荐）<br>`dsh plugin --profile web add ...` | 插件作为 npm 包被 Loader 加载，运行在真实 Node 进程，可正常使用 `node_modules` 依赖 | ✅ 唯一正确的安装方式 | | **动态插件**<br>会话内 `cordis_define` / `cordis_run` | 代码运行在受限 vm 沙箱：禁止 `require`、无法加载原生模块 | ❌ 不可用 | **为什么？** 本插件依赖两个**原生模块**：`sqlite-vec`（SQLite 向量搜索扩展，`.node` 二进制）和 jieba 中文分词。vm 沙箱没有这些能力，动态加载会直接失败。 **怎么装？** 用安装章节的命令（GitHub tarball / npm / 本地 tarball）走 bundle 通道即可，`dsh plugin` 会自动把本包加进 `dsh.profile.bundles`。 --- ### 4. 其余已知边界 - **记忆数据是本地文件**：所有数据存在 `$DSH_HOME/memory-tdai/`（见"使用"章节），删除目录即清空全部记忆——迁移机器时记得一并拷贝。 - **混合检索依赖可选包**：BM25 稀疏编码依赖 `@tencentdb-agent-memory/tcvdb-text`（约 286MB，含 jieba-wasm 词典），默认**未安装**，缺失时自动降级为纯 FTS5；本地 embedding 依赖 `node-llama-cpp`（GGUF 模型），同样可选。两条都缺依然能完整运行。 - **每会话记忆归属**：记忆按 DSH 会话 key 隔离写入，同一用户的跨会话记忆可被检索到。DSH 版目前未接入上游的 `excludeAgents` 过滤，子代理（subagent）会话也会参与捕获——如需排除可按行配置加白名单（后续版本规划）。 ---