Skip to content
Back to search

memory-eternal

记忆核心(Memory Eternal):对话结束后自动沉淀知识卡到本地记忆库(~/.dsh/memory-vault),支持检索 / 召回 / 审核中心。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/EternalNight996/memory-eternal with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/EternalNight996/memory-eternal'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/eternalnight996--memory-eternal/badge.svg)](/listings/eternalnight996--memory-eternal)

HTML

<a href="/listings/eternalnight996--memory-eternal"><img src="/api/listings/eternalnight996--memory-eternal/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 27 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
  3. "name": "memory-eternal",
  4. "version": "0.49.14",
  5. "description": "记忆核心(Memory Eternal):对话结束后自动沉淀知识卡到本地记忆库(~/.dsh/memory-vault),支持检索 / 召回 / 审核中心。",
  6. "author": {
  7. "name": "EternalNight996",
  8. "url": "https://github.com/EternalNight996"
  9. },
  10. "license": "MIT",
  11. "hooks": {
  12. "source": "./hooks/hooks.claude.json"
  13. },
  14. "skills": [
  15. "./skills/"
  16. ],
  17. "mcp_servers": [
  18. {
  19. "name": "memory",
  20. "command": "node",
  21. "args": [
  22. "${CLAUDE_PLUGIN_ROOT}/bin/dsh-memory.mjs",
  23. "mcp"
  24. ]
  25. }
  26. ]
  27. }
README.md · README · 638 lines
  1. # 🧠 memory-eternal —— 给 AI 装一个可信的第二大脑
  2. <p align="center"><img src="assets/icon-400.png" width="92" height="92" alt="memory-eternal icon" /></p>
  3. <p align="center"><img src="assets/screen/hero.png" width="100%" alt="memory-eternal 蜘蛛侠皮肤:本地、可审核、可同步云端的 AI 长期记忆" /></p>
  4. <p align="center">
  5. <img src="https://img.shields.io/github/stars/EternalNight996/memory-eternal?style=flat" alt="stars" />
  6. <img src="https://img.shields.io/npm/v/memory-eternal" alt="npm" />
  7. <img src="https://img.shields.io/badge/license-MIT-blue" alt="license" />
  8. </p>
  9. [English](README.en.md) · **简体中文(默认)**
  10. ## ☁️ 云端记忆(v0.49.10 主打)
  11. **记忆库跟着人走,不跟着机器走。** 本机库照旧离线可用;登录云端后,同一套知识卡在你的每台设备、每个
  12. Agent 上都能读到 —— 换电脑不用搬家,换客户端不用重新喂上下文。
  13. | 能力 | 你能得到 |
  14. |---|---|
  15. | **一次登录** | MengBot 账号扫码 / 邮箱登录,或在任意实例上签发的访问密钥(`me_…`) |
  16. | **一人一库** | 云端按 owner 分目录,**每个用户一个独立 SQLite**(`cloud-vaults/{owner}/memory-eternal.db`),物理隔离 |
  17. | **换库不重启** | 本地库 ↔ 云端库**热切换**(`POST /vaults/switch`):知识卡、星图、待审、回收站一次性换源,不刷新页面 |
  18. | **上传 / 下载** | 整库复制(本机 → 云端、云端 → 本机),分片传输 + **断点续传** + 中途取消 + 失败重试 3 次,重复内容自动跳过 |
  19. | **离线优先** | 云端不可达自动熔断、回退本地库,首屏最多等 3 秒;本地记忆一分不丢 |
  20. | **自有实例** | 自己的服务器跑 `memory-eternal-cloud`(systemd / Docker + HTTPS 反代),密钥可签发、可吊销、只存 sha256 |
  21. | **发密钥三处入口** | **CLI**(`dsh-memory cloud keys issue`,本地台账模式免令牌)· **面板**「🔑 服务端密钥管理」· curl;管理令牌首次启动自动生成 |
  22. ```bash
  23. # ① 起一个云端实例(默认关闭,不开就是纯本地)
  24. MEMORY_CLOUD=1 node lib/web.js --port 7999 # Docker / systemd 部署见 docs/CLOUD.md
  25. # 首次启动会自动生成管理令牌 → $DSH_HOME/cloud-admin-token(0600,日志打印一次)
  26. # ② 签发访问密钥(三选一)
  27. dsh-memory cloud keys issue --owner alice --note 笔记本 # CLI:能在这台机跑命令就是管理员,免令牌、立即生效
  28. # 或:面板 → 设置 → 🧪 实验性 → 云端连接 → 「🔑 服务端密钥管理」→ 粘贴管理令牌 → 新建
  29. curl -X POST http://127.0.0.1:7999/memory-eternal/api/cloud/keys \
  30. -H "Authorization: Bearer $MEMORY_CLOUD_ADMIN_TOKEN" \
  31. -H 'Content-Type: application/json' -d '{"owner":"alice"}'
  32. # ③ 面板:设置 → 🧪 实验性 → 云端连接 → 填地址 + 密钥 → [测试连接] → [保存并切换]
  33. ```
  34. > 反代 / 容器部署记两个变量:`MEMORY_CLOUD_ADMIN_TOKEN`(不配就用自动生成的那把;配了以它为准)、`MEMORY_PUBLIC_HOST`(写请求的 Host 白名单,填你的域名)。
  35. > 边界说明:云端服务端(多租户 + 鉴权 + 计费对接)是**独立私有组件**,不随本开源包发布;
  36. > 相关接口仍在快速迭代、可能微调。不用云端时,本地功能与之前完全一致 —— 见 [docs/CLOUD.md](docs/CLOUD.md)、[docs/PRIVATE.md](docs/PRIVATE.md)。
  37. ## 📊 与同类产品的实测对比
  38. > 数据日期 **2026-11-18**:Stars 取自 GitHub API(整数实值);公开成绩按各自 README / 论文**原文口径**转录,
  39. > 不同指标的分数绝不混排。可视化版见 [bench/comparison.html](bench/comparison.html),口径与复跑脚本见 [bench/COMPARISON.md](bench/COMPARISON.md)。
  40. **表 1 · 记忆类:综合判断(10 维加权,我们自己的评分口径)**
  41. | 排名 | 项目 | 召回 | 语义 | 隐私 | 治理 | 成本 | 总分 |
  42. |---|---|---|---|---|---|---|---|
  43. | 🥇 1 | **memory-eternal(Ollama)** | 8.6 | 8.6 | 9.5 | 9.0 | 8.0 | **8.54** |
  44. | 🥈 2 | **memory-eternal(内置语义)** | 7.1 | 6.8 | 9.5 | 9.0 | 9.5 | **8.48** |
  45. | 🥉 3 | Mem0(69.1k★) | 9.3 | 9.0 | 6.0 | 6.0 | 6.5 | 7.49 |
  46. | 4 | MemOS(12.4k★) | 8.5 | 8.5 | 7.0 | 6.0 | 7.0 | 7.38 |
  47. | 5 | graphiti(32.9k★) | 7.8 | 8.5 | 8.0 | 6.0 | 7.0 | 7.26 |
  48. | 6 | basic-memory(4.6k★) | 6.5 | 6.5 | 9.0 | 6.0 | 9.0 | 7.26 |
  49. | 7 | Letta(25.5k★) | 8.0 | 8.5 | 8.0 | 6.0 | 6.5 | 7.22 |
  50. | 8 | mcp-memory-service(2.1k★) | 6.0 | 6.0 | 9.0 | 5.0 | 9.5 | 7.17 |
  51. | 9 | memobase(3.0k★) | 7.2 | 7.0 | 8.0 | 6.0 | 8.0 | 7.15 |
  52. | 10 | cognee(33.4k★) | 8.0 | 8.5 | 8.0 | 5.5 | 7.0 | 7.14 |
  53. | 11 | supermemory(31.6k★) | 8.0 | 8.0 | 6.5 | 5.5 | 6.5 | 7.14 |
  54. | 12 | Zep(5.0k★,产品闭源) | 7.0 | 7.5 | 6.5 | 6.5 | 6.0 | 6.88 |
  55. **表 2 · 记忆类:公开基准与部署硬指标**
  56. | 项目 | Stars | 公开成绩(原文口径) | 本地 / 零 API | 人工审核闸门 |
  57. |---|---|---|---|---|
  58. | **memory-eternal(bge-m3)** | 196 | 自建 500 题 **R@5 97.2%**(检索口径) | 需 Ollama | ✅ |
  59. | **memory-eternal(内置)** | 196 | 自建 500 题 **R@5 95.4%**(检索口径) | ✅ / ✅ | ✅ |
  60. | Mem0 | 69,120 | LongMemEval 94.4(**托管平台**口径,非开源版) | 部分 | 弱 |
  61. | cognee | 33,371 | BEAM 100K 0.79 / BEAM 10M 0.67(0–1) | 部分 | 中 |
  62. | graphiti | 32,889 | 仓库无 LongMemEval / LoCoMo 数字 | 部分 | 中 |
  63. | supermemory | 31,644 | LongMemEval **R@15 95%**(约 720 token) | 部分 | 弱 |
  64. | Letta ※ | 25,471 | 仓库无 LongMemEval / LoCoMo 数字 | 部分 | 中 |
  65. | MemOS | 12,435 | LongMemEval 89.20(OmniMemEval) | 部分 | 中 |
  66. | Zep ※ | 5,007 | 论文:LongMemEval 准确率比 MemGPT **+18.5%**、延迟 −90% | ❌ | 中 |
  67. | basic-memory | 4,612 | 仓库无公开记忆基准数字 | ✅ / ✅ | 弱 |
  68. | memobase | 2,960 | LoCoMo 75.78(第三方复现,LLM-Judge Overall) | 部分 | 中 |
  69. | mcp-memory-service | 2,135 | LongMemEval-S **R@5 86.0%**(零 LLM 调用) | ✅ / ✅ | 弱 |
  70. > ※ **必须标注的状态**:`getzep/zep` 仓库是 Zep Cloud 的示例 / 集成目录,产品本体闭源(开源图引擎是 graphiti);
  71. > `letta-ai/letta` 主仓已归档,活跃源码迁到 `letta-code`。这两家不能当"开源版 star"读。
  72. ## 🏷 命令名与别名
  73. 包名从一开始就是中性的 **memory-eternal**;只有命令行工具早期叫 `dsh-memory`(那时它只服务 DSH)。
  74. 现在三种写法是同一个入口:
  75. | 命令 | 用在哪 |
  76. |---|---|
  77. | `memory` | 主名。任何宿主、纯 CLI、脚本里都推荐用它 |
  78. | `mem` | 简短别名,终端里敲得少 |
  79. | `dsh-memory` | 兼容入口。老文档、老脚本、DSH 插件内部仍用它,不会被移除 |
  80. ```bash
  81. memory status --port 7999 # 等价于 dsh-memory status --port 7999
  82. mem peer code # 等价于 dsh-memory peer code
  83. ```
  84. 数据目录同理不受限:`MEMORY_VAULT_DIR`(库目录)、`MEMORY_DB_FILE`(库文件名)、`MEMORY_WEB_PORT`(端口)
  85. 都可以改,所以库不一定要待在 `~/.dsh` 下面。
  86. ## ⚡ 快速开始
  87. ```bash
  88. # DSH 桌面版 / Web
  89. dsh plugin --profile desktop add memory-eternal # 重开 DSH → 左栏「记忆」
  90. # 同一套库接 Claude Code / Codex / Cursor(MCP)
  91. npm i -g memory-eternal && dsh-memory connect claude
  92. # 任意 MCP 客户端(MengBot / OpenClaw / Hermes 见 docs/INTEGRATIONS.md)
  93. npx -y -p memory-eternal dsh-memory mcp
  94. # 云端 bot / 远程 agent:直接走 HTTP,不用装进程
  95. curl -s http://127.0.0.1:7999/memory-eternal/api/mcp \
  96. -H 'content-type: application/json' \
  97. -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
  98. # 浏览器 / 终端
  99. dsh-memory open # http://127.0.0.1:7999
  100. npx -y -p memory-eternal dsh-memory tui # 终端里的实时待审队列
  101. ```
  102. <p align="center"><strong>⭐ 如果它帮你少解释了一遍上下文,点个 Star 就是最大的支持</strong></p>
  103. ## 🧾 真的省 token 吗?
  104. 大多数记忆产品都说自己省 token。我们认为你应该自己验证。插件内置**记忆账本**(运行状态 → 记忆账本):
  105. | 记录项 | 含义 |
  106. |---|---|
  107. | 召回:命中数 + 注入字符 | 到底有多少记忆进入了上下文 |
  108. | 沉淀:LLM 调用次数 + 输入/输出字符 | 蒸馏花了你多少成本 |
  109. | 有用率:有用 / 没用 反馈 | 召回的记忆是否真的帮上了忙 |
  110. ```text
  111. 净收益 ≈ 被避免的上下文开销 −(注入字符 + 蒸馏调用 × 单价)
  112. ```
  113. | 场景 | 你要付 | 你能省 |
  114. |---|---|---|
  115. | 有决策与踩坑记录的多会话项目 | 每次召回约 0.6–0.9k token | 重新解释上下文(约 1.5–3k)或重读文件(3–6k) |
  116. | 一次性问题、低命中率 | 召回注入 | 通常什么也省不到 |
  117. > 以上是示意数字,不是 benchmark —— 用账本测你自己的。如果召回有用率长期低于约 60%,就调小(更少条数、更短摘要)或直接关掉记忆。
  118. > 上了云端之后,账本按库独立记账:本地库、云端库各算各的,跨设备看同一份统计。
  119. ## 🛡️ 先审核,再入库
  120. 一个「什么都自动吞进去」的记忆系统,迟早会把错误事实当成真相召回。memory-eternal 默认**先审后入**:
  121. - 新卡先进入**待审队列**,人工批准后才进主库;
  122. - 在 Web、终端 TUI 或 CLI 里批准 / 驳回 / 批量处理;
  123. - 每次状态变更追加到**不可篡改的审计日志**(谁 / 什么 / 何时 / 为什么)—— 由 SQLite 层强制,而不是靠约定;
  124. - Agent 可以读取和提议,但**不能批准自己写的卡**;
  125. - Agent 也可以提交**修改**:已批准卡的副本进待审队列并标注「✏️ 修改原卡:…」;批准 = 用副本覆盖原卡,驳回 = 原卡一字不动;
  126. - 删除的卡进回收站(默认保留 30 天)。
  127. > 云端同样是这条闸门:换到云端库只换了**数据源**,没换规则 —— 云端库里的待审卡一样要人批准。
  128. ## ⭐ 核心记忆
  129. 不是所有内容都该每次注入上下文。核心记忆是一组**必须每次遵守**的偏好与硬约束:
  130. - 任意已批准卡片都可以在阅读器或卡片列表里提升为核心记忆;
  131. - 自动沉淀只会在用户明确要求长期偏好 / 硬约束时**建议**核心,且 core 候选**一律待审**;
  132. - 已批准的核心卡每次会话直接注入 systemPrompt,不依赖 `memory_recall` 调用;
  133. - 在「设置 → 记忆 → 核心记忆」里可配置条数上限和字符预算;
  134. - 知识星图里核心节点显示为橙色菱形 + ★;
  135. - **不要把密钥 / Token 的值写进核心卡**,只保存凭证目录的引用。
  136. ## 🧩 宿主支持(一份库,谁都能用)
  137. 同一份 SQLite 库,下面这些宿主都能读写;写入一律进**待审队列**,审核在 DSH / Web 面板里做(与宿主是谁无关)。
  138. **15 个宿主,一张表看全** · `✅` 一键挂载 · `⚠️` 有条件 · `➖` 手填一条 · `❌` 不提供 MCP 配置
  139. ### 🌍 国际主流
  140. | 宿主 | 类型 | 配置位置 | 挂载 |
  141. |---|---|---|---|
  142. | **DeepSeek Harness** | 插件(内嵌面板) | `~/.dsh/mcp-servers.json` | ✅ 装插件即挂 |
  143. | **Claude Code** | CLI / IDE 插件 | `~/.claude.json` | ✅ `connect claude` |
  144. | **Codex CLI / Desktop** | CLI | `~/.codex/config.toml` | ✅ `connect codex` |
  145. | **Cursor** | IDE | `~/.cursor/mcp.json` | ✅ `connect cursor` |
  146. | **Windsurf** | IDE | `~/.codeium/windsurf/mcp_config.json` | ✅ 面板点一下 |
  147. | **Cline** | VS Code 插件 | `~/.cline/data/settings/cline_mcp_settings.json` | ✅ 面板点一下 |
  148. | **Gemini CLI** | CLI(Google) | `~/.gemini/settings.json` → `mcpServers` | ✅ 面板点一下 |
  149. | **Antigravity** | **桌面 IDE**(Google) | `~/.gemini/config/mcp_config.json` → `mcpServers` | ✅ 面板点一下 |
  150. | **OpenClaw** | 网关(JSON5) | `~/.openclaw/openclaw.json` → `mcp.servers` | ✅ 含注释时拒绝改写 |
  151. | **Hermes Agent** | CLI(YAML) | `~/.hermes/config.yaml` → `mcp_servers` | ✅ 只换自己那块 |
  152. | **VS Code Copilot** | IDE | portable 的 `mcpServers` | ➖ 手填 |
  153. | **Gemini 桌面应用 / 网页版** | 聊天客户端 | 不提供 MCP 配置 | ❌ 接不了(Google 侧桌面形态用 Antigravity) |
  154. ### 🇨🇳 国内主流
  155. | 宿主 | 类型 | 配置位置 | 挂载 |
  156. |---|---|---|---|
  157. | **MengBot** | 机器人平台 | 应用内「设置 → MCP 服务器」/项目 `.mcp.json` | ⚠️ 给了 `MEMORY_HOST_MENGBOT_PROJECT` 才写项目文件 |
  158. | **Qwen Code** | CLI(阿里,Gemini CLI 同源) | `~/.qwen/settings.json` → `mcpServers` | ✅ 面板点一下 |
  159. | **Kimi CLI** | CLI(月之暗面) | `~/.kimi/mcp.json` | ✅ 面板点一下 |
  160. | **GrokBot** | 桌面客户端 | `~/.grokbot/mcp.json` / `%APPDATA%\GrokBot\mcp.json` | ✅ 面板点一下(官方未公开格式,按约定探测) |
  161. | **智谱清言 / ZhipuAI** | 桌面 / Web | 应用内添加 | ➖ 只探测,手填 |
  162. | **WorkBuddy** | 桌面客户端 | 应用内添加 | ➖ 只探测,手填 |
  163. | **Cherry Studio** | 桌面客户端 | 应用内「设置 → MCP 服务器」 | ➖ 无外部配置文件 |
  164. ### ☁️ 不用装进程
  165. | 通道 | 用法 |
  166. |---|---|
  167. | **云端 bot / 远程 agent** | `POST /memory-eternal/api/mcp`(Streamable HTTP,云端带 `Bearer me_…`) |
  168. | **终端 TUI** | `npx -y -p memory-eternal dsh-memory tui` —— 实时队列、全选、批量批/驳、长文读卡 |
  169. | **Web 面板** | `dsh-memory open` → http://127.0.0.1:7999:独立部署,审核 / 检索 / 备份 |
  170. 一次投影多处:`dsh-memory mcp mount --host gemini,qwen,kimi`(`--host all` 全挂)。字段名、示例与坑见 [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md);Orca 启动器见 [orca-plugin](orca-plugin/README.md),编辑器扩展见 [cursor-extension](cursor-extension/README.md)。
  171. > MCP 对外就是标准 stdio server,5 个工具:`memory_recall` / `memory_capture` / `memory_stats` / `memory_audit_list` / `memory_revise`。没列到的客户端按上面那行 stdio 配置写即可。
  172. **我们不是这里最大的。** Mem0 有 6.9 万星和成熟团队,我们做的不一样的是**写入路径**:
  173. 人审闸门、物理三库分离、可指认的审计链,外加一本能自己核对"召回到底值不值"的记忆账本 —— 这些在表 1 的「治理」列里体现,而不是靠宣传。
  174. 在**你自己的库**上复跑:
  175. ```bash
  176. node scripts/bench-search.mjs --rebuild # 重建耗时 + p50/p95/max 延迟
  177. node scripts/bench-recall.mjs # 自建金标题 R@5 / Top1
  178. dsh-memory ledger --days 30 --json # 召回注入 / 沉淀调用 / 有用率
  179. ```
  180. | 我们实测的基线(2026-11-12,2,943 张卡) | 数值 |
  181. |---|---|
  182. | 金标 109 题 R@5(内置 / bge-m3) | 96.3% / **99.1%** |
  183. | 金标 109 题 Top1(内置 / bge-m3) | 86.2% / **89.9%** |
  184. | 改写题 10 条 R@5(内置 / bge-m3) | 40% / **70%** |
  185. | LongMemEval-S 500 题 R@5(内置 / bge-m3) | 95.4% / **97.2%** |
  186. | 召回延迟(词法 / 语义) | 约 7 ms / 81 ms |
  187. | 召回模型调用(内置语义) | 0 |
  188. > 检索分 ≠ QA 分。表 2 我们两行是 **检索 R@5**;Mem0 的 94.4 是它自报的 **LongMemEval QA**(且是托管平台口径),两列不混比。
  189. ## 🔍 语义召回(默认内置,无需装模型)
  190. **新装默认就是内置语义**:零安装、零网络、零费用,同义扩展兜底,开箱即用。三种部署方式:
  191. | 方式 | 说明 |
  192. |---|---|
  193. | 内置语义(默认) | 零依赖;自建集 R@5 96.3%,改写题 40% |
  194. | 本地 Ollama(推荐升级) | bge-m3 向量;R@5 99.1%,改写题 70%,延迟约 100ms(含冷启动;热态查询嵌入实测 28–35 ms) |
  195. | 在线 API | OpenAI 兼容端点,按量计费 |
  196. 首次打开记忆库会走三步引导,并默认全开:记忆核心 / 自动沉淀 / 自动召回 / 核心记忆注入 / 工作记忆 / 内置语义。
  197. 设置页「语义召回」右上角可「🧭 引导」重新查看。细节见 [docs/EMBEDDINGS.md](docs/EMBEDDINGS.md)。
  198. ## 🎨 皮肤与界面
  199. 五套皮肤,设置 → 通用 → 主题皮肤一键切换;选择会本地保存,刷新后保持。
  200. <p align="center">
  201. <img src="assets/screen/skins-gallery.png" width="900" alt="五种主题皮肤:默认暗色、波普、明亮、生化危机、蜘蛛侠" />
  202. </p>
  203. | 皮肤 | 风格 |
  204. |---|---|
  205. | **默认暗色** | 深色底 + 琥珀强调,长时间阅读不刺眼 |
  206. | **波普 Pop** | 黄底黑框、硬阴影、半调与粗黑标题 |
  207. | **明亮 Light** | 暖纸面 + 衬线标题,适合白天 |
  208. | **生化危机** | Umbrella 实验室、毒绿扫描线、B.O.W. 头图与巨爪 |
  209. | **蜘蛛侠** | 红蓝漫画、蛛网、半调、横版动作头图与悬吊挂件 |
  210. <p align="center">
  211. <img src="assets/screen/spider-cards.png" width="49.5%" alt="知识卡:蜘蛛侠皮肤" />
  212. <img src="assets/screen/spider-graph.png" width="49.5%" alt="知识星图:蜘蛛侠皮肤" />
  213. </p>
  214. <p align="center"><sub>▲ 知识卡 · 知识星图 —— <a href="https://eternalnight996.github.io/memory-eternal/demo/">在线 Demo</a></sub></p>
  215. ## 🏗 架构:一个库、一道闸门、两条读取路径
  216. ```mermaid
  217. flowchart TB
  218. subgraph IF["接入层"]
  219. UI["DSH Web UI<br/>记忆库 · 星图 · 审核中心 · 设置"]
  220. MCPC["MCP 客户端<br/>Claude Code · Codex · Cursor · OpenClaw"]
  221. CLI["CLI / TUI<br/>dsh-memory"]
  222. CLOUDC["云端客户端<br/>换库 / 上传 / 下载"]
  223. end
  224. subgraph RT["插件运行时(宿主 Node 进程)"]
  225. HOST["index.js<br/>事件订阅 · 配置 · systemPrompt 注入"]
  226. API["lib/api.js<br/>HTTP API · SSE · CSRF · 审核接口"]
  227. CAP["capture.js<br/>采集 → 蒸馏 → 降级原文卡"]
  228. IDX["search-index.js<br/>清洗 · 同义扩展 · FTS5 BM25"]
  229. EMB["embeddings.js<br/>向量 · 覆盖率门控 · 融合"]
  230. VAULT["vault.js<br/>读写 · 审核 · 审计 · 回收站"]
  231. MCPL["mcp.js + hooks<br/>工具注册 · 会话事件"]
  232. end
  233. subgraph DB["本地存储(SQLite WAL + 文件)"]
  234. CARDS[("cards<br/>仅 approved")]
  235. QUAR[("quarantine<br/>pending / rejected")]
  236. FTS[("cards_fts<br/>FTS5 索引")]
  237. VEC[("card_vec<br/>可选向量")]
  238. LOG[("audit_log · ledger · revisions")]
  239. MD["Markdown 镜像 + 每日备份"]
  240. end
  241. subgraph EX["可选外部服务"]
  242. LLM["蒸馏 LLM<br/>宿主 provider"]
  243. OLL["Ollama :7997<br/>或任意 OpenAI 兼容 embedding"]
  244. end
  245. subgraph SV["云端实例(memory-eternal-cloud,可选)"]
  246. TENANT["resolveTenant()<br/>一个 owner 一个独立库"]
  247. CV[("cloud-vaults/owner/<br/>memory-eternal.db")]
  248. end
  249. UI --> API
  250. MCPC --> MCPL
  251. CLI --> VAULT
  252. CLOUDC --> API
  253. HOST --> CAP
  254. CAP --> LLM
  255. CAP --> VAULT
  256. VAULT --> CARDS
  257. VAULT --> QUAR
  258. VAULT --> LOG
  259. QUAR -->|人工批准| CARDS
  260. CARDS --> FTS
  261. CARDS --> VEC
  262. IDX --> FTS
  263. EMB --> VEC
  264. EMB --> OLL
  265. HOST -->|systemPrompt / memory_recall| UI
  266. VAULT --> MD
  267. API -->|Bearer 令牌| TENANT
  268. TENANT --> CV
  269. ```
  270. 这张图之所以成立,是因为三条不变量**写在代码里**,不是写在文档里:
  271. | 不变量 | 由什么保证 |
  272. |---|---|
  273. | 主库**物理上只存 approved** | 两张物理表;所有读取路径只查主库 |
  274. | Agent **永远不能批准自己的记忆** | Agent 只能写进隔离区;批准 / 驳回是 UI / TUI / CLI 里的人工动作 |
  275. | 召回**零模型调用** | FTS5 + BM25;LLM 只在沉淀时运行 |
  276. > 云端只加了一条边:`API → resolveTenant() → 该 owner 自己的库`。租户之间没有共享表,串不了数据。
  277. ### 🔁 一次会话里,到底发生了什么
  278. 宿主的 agent 不是「读写一个文件夹」,而是走一条有预算、有闸门、可降级的链路:
  279. | # | 时刻 | 谁在动 | 具体动作 | 阻塞对话吗 |
  280. |---|---|---|---|---|
  281. | 1 | 会话建立 | `index.js` | 往 systemPrompt 装配若干段:**核心记忆**(`order 120`,≤6 张 / ≤2000 字)、当前会话草稿、**自动召回规则段**(`order 600`)、新闻摘要(可选)。核心记忆每 5 秒重算一次,内容没变就不重建 | 否 |
  282. | 2 | 你提问 | 宿主 agent | 正常推理。用不用记忆由它自己决定 —— 规则段只是告诉它「什么时候该查」 | — |
  283. | 3 | agent 主动召回 | `memory_recall` 工具 | **进程内直调** `vault.search()`,不经过 HTTP 端口;默认 5 条、每条摘要 130 字,工具超时 20s | 是(仅这一步) |
  284. | 4 | 作答 | 宿主 agent | 召回结果就是一段普通工具输出,和读文件没区别 | — |
  285. | 5 | 轮次结束 | `agent/turn-stopping` | 会话事件入队 → 按字符上限截尾 → **连续轮合并**(几轮攒一次 LLM 调用,而不是每轮一次) | 否(serial 事件里刻意不 await LLM,避免拖慢收尾) |
  286. | 6 | 蒸馏成卡 | 宿主 LLM(`ctx.get('llm')`) | 一段对话 → 一张卡;不足 `captureMinChars=120` 字跳过;同会话 60s 冷却;输出上限 `max_tokens=4000` | 否(后台任务) |
  287. | 7 | 去重判定 | `pickNeighbors()` | 只取最相关 **8 张**已有卡(`DEDUP_NEIGHBORS`)喂给模型,让它选「新建」还是 `append_to` 追加(近重阈值 `0.62`) | 否 |
  288. | 8 | 落库 | `vault.js` | 写进 `quarantine`(`status=pending`),**主库一动不动** | 否 |
  289. | 9 | 人工审核 | 你 | 审核中心批准 → 进 `cards` → 建 FTS5 索引(5 分钟对账)+ 需要时补向量(`batch 16`) | — |
  290. 一句话概括分工:**agent 负责「提议」和「按需取用」,永远不决定什么能进主库。**
  291. ### 📥📤 两条读取路径
  292. 「两条」指的是上下文成本完全不同的两种读法,别混为一谈:
  293. | | 推送(push):systemPrompt 注入 | 拉取(pull):`memory_recall` 工具 |
  294. |---|---|---|
  295. | 谁触发 | 插件自动,每轮都带 | agent 自己决定 |
  296. | 带什么 | 核心记忆(≤6 张 / ≤2000 字)+ 规则段 + 会话草稿 | 命中 Top-N 卡片的标题 / 路径 / 摘要 |
  297. | 预算 | `coreMemoryLimit` / `coreMemoryMaxChars` 硬上限 | `recallLimit`(默认 5,上限 20)× `recallSummaryLen`(默认 130 字) |
  298. | 随卡片数增长吗 | 不增长(上限写死) | 不增长(条数与字数写死) |
  299. | 典型用途 | 「不要做的事」「我的偏好」这类每次都必须遵守的约束 | 查历史决策、踩坑记录、项目背景 |
  300. > 需要看正文时才有第三条路:`recallIncludeBody=true` 会给每条命中追加 ≤800 字正文摘录 —— 默认关闭,就是怕把上下文撑大。
  301. ### 💰 谁在什么时候调用模型
  302. | 时机 | 调谁 | 同步/异步 | 失败会怎样 |
  303. |---|---|---|---|
  304. | 召回(默认) | **不调模型**:FTS5 + BM25 全在 SQLite 里 | 同步 | 索引异常 → 全表兜底扫描 |
  305. | 召回(开了语义) | Ollama `bge-m3` 算 **1 次**查询向量 | 同步,超时 15s | 60s 失败冷却 → 自动退回纯词法 |
  306. | 召回(开了 rerank) | 你配的重排模型,只看 Top-30 候选 | 同步,超时 20s | 保留原排序 |
  307. | 每轮沉淀 | 宿主 LLM 蒸馏(喂 8 张近邻卡) | **异步** | 存原文卡(零蒸馏成本),仍要人审 |
  308. | 建向量缓存 | Ollama,`batch 16` | **异步** backfill | 覆盖率不到 30% 就不启用语义路 |
  309. ### 🚀 卡片变多了,会变慢 / 变蠢吗?
  310. 这是最该被量化的担心,所以给数字,不给形容词。下面这张表由仓库自带脚本在**临时合成库**上跑出来(Windows / node v24.19.0 / 2026-11-18;每卡正文约 1600 字,dim=768):
  311. | 卡片数 | FTS/BM25 | 向量打分 | 端到端 `search()` | 向量读入 | **单次召回注入字符** | 全库正文 |
  312. |---|---|---|---|---|---|---|
  313. | 200 | 0.31 ms | 1.2 ms | 28 ms | 0.6 MB | 283 字 | 0.32 M 字 |
  314. | 1 000 | 0.90 ms | 11.4 ms | 38 ms | 2.9 MB | 286 字 | 1.60 M 字 |
  315. | 2 000 | 1.61 ms | 25.8 ms | 43 ms | 5.9 MB | 304 字 | 3.21 M 字 |
  316. | 5 000 | 3.55 ms | 55.5 ms | 71 ms | 14.6 MB | 307 字 | 8.01 M 字 |
  317. (同一台机器上多跑几次,耗时会有 ±20% 左右的抖动 —— 量级与曲线形状才是有意义的部分,绝对值不必抠。)
  318. 自己复现(只写系统临时目录,不碰你的库):
  319. ```bash
  320. node scripts/bench-capacity.mjs # 默认 200,1000,2000,5000
  321. node scripts/bench-capacity.mjs 500,5000,20000 # 自定义规模
  322. ```
  323. > 容量用 `bench-capacity.mjs`(自带合成库,测耗时与注入量);质量另用 `bench-recall.mjs`(读 `--vault` 快照 + 金标集,测 R@5 / MRR / Top1)。两个脚本故意分开,别拿容量数字冒充质量结论。
  324. **结论一:上下文成本与卡片数无关。** 卡片从 50 张涨到 5 000 张,单次召回注入仍是 300 字上下 —— 因为 `limit=5` 与每条 130 字是硬截断。作为对照,把全库正文直接塞进去是 8.1 **百万**字,差 4 个数量级。agent 看到的永远是「5 条摘要」,不是「一座图书馆」。
  325. **结论二:检索耗时增长远慢于直觉。** 5 000 张卡时词法召回 3.6 ms、端到端 71 ms。词法是倒排索引 + **候选池固定 80 条**(`max(limit×4, 80)`),不随库线性膨胀。
  326. **结论三:唯一真正线性增长的是向量打分。** 没有 ANN 索引,就是「读全表 BLOB + 逐个 cosine」:5 000 张要读 14.6 MB、约 55 ms。这张表里增长最快的就是它。
  327. 于是可以给出可执行的容量口径:
  328. | 库规模 | 建议 | 理由 |
  329. |---|---|---|
  330. | ≤ 5 千张 | 全开:词法 + 语义 + rerank | 向量打分数十毫秒,可无感 |
  331. | 5 千 – 1 万 | 词法 + rerank 常开;语义改成**按需** | 9 752 张实测:cosine 124 ms / 读 38 MB,端到端约 300 ms |
  332. | > 1 万 | 词法 + rerank;语义只在**分库后**开 | 分库是唯一能真正压住线性项的手段 |
  333. ### 🧪 真实库实测:9 752 张卡的一次索引事故
  334. 比合成数据更值得读的,是一次真实排障。
  335. 库里 9 752 张已批准卡,`cards_fts` 却只有 **50 行** —— 索引在某次批量导入之后就没再补齐,而召回在索引缺失时会**静默**退到「全表扫描 + 子串计数」兜底。于是同一条查询给出两种答案:
  336. | 查询 | 索引只剩 50 行时(兜底扫描) | 重建索引后(FTS5 + BM25) |
  337. |---|---|---|
  338. | `审核 红线 批准` | 「DSH 记忆库巡检现状…」无关 | 「审核中心 #27 可就地查看正文 + 批准/驳回」✓ |
  339. | `Ollama 语义召回` | 「autokill-purge 模型清单…」无关 | 「本地 Embedding 服务(Ollama/bge-m3)离线部署」✓ |
  340. | `npm 发布 403 账号冷却` | 「0.47.0 发版前收尾…」勉强相关 | 「v0.49.13 发布记录与 npm 冷却问题」✓ |
  341. 这就是「agent 变蠢」的真实长相:**不是卡片多,是索引没了**。功能不报错、搜索不报错,只是答案变得像随机抽卡。
  342. | 指标(真库 9 752 张) | 实测 |
  343. |---|---|
  344. | 词法召回(重建后) | **2.5 – 4.3 ms** |
  345. | 重建索引 | **3.5 – 9.8 s**(一次性,9 752 行) |
  346. | 全表 cosine(灌满 9 752 条 dim=1024 向量,读 38.1 MB) | **124 ms** |
  347. | 端到端召回(开语义,含 1 次 Ollama 查询嵌入) | **250 – 314 ms** |
  348. | 单次召回注入上下文 | **约 1 350 字**(5 条 × 标题 + 路径 + 130 字摘要),与卡片总数无关 |
  349. 代价结构一目了然:**词法几乎免费,语义每万张约 0.3 秒**。
  350. Ollama 的账另外算:本机 `bge-m3` 热态一次查询嵌入实测 **28–35 ms**(dim=1024),但它只在你开启语义召回时、每次召回调 **一次**,且与库大小无关 —— 慢的是「把库读一遍算相似度」,不是模型本身。冷启动另有一次性开销(模型首次加载)。
  351. 至于「会不会变蠢」:变蠢的机制从来不是「卡多」,而是**坏卡挤进那 5 个名额**。所以真正的防线是闸门而不是容量:
  352. - 只有人批准的卡才进主库(`quarantine` 物理隔离 232 张待审也影响不到召回);
  353. - 沉淀时先做近重判定(阈值 0.62),重复内容会被 `append_to` 合并而不是堆成新卡;
  354. - 召回结果可以点「有用 / 没用」,反馈直接参与排序(`有用×2 − 没用的×2`);
  355. - 过时卡归档后**物理上不参与召回**;
  356. - 判断标准写在账本里:**有用率长期低于 60%,就调小 `recallLimit` / `recallSummaryLen`,或者直接关掉记忆** —— 这是插件自己给出的退场条件。
  357. ### 🧰 运维:索引和向量什么时候要手动补
  358. 索引只在**写卡那一刻**逐条维护(`indexCardById` / `unindexCard`)。批量导入、Markdown 迁移、跨版本升级进来的存量卡不会自动补 —— 这是当前实现的已知缺口,所以要自己查一次:
  359. ```bash
  360. node scripts/reindex-fts.mjs # 只报告:已批准卡数 vs 已索引行数
  361. node scripts/reindex-fts.mjs --force # 重建(只写 cards_fts / _fts_rows,不动卡)
  362. ```
  363. | 症状 | 判断依据 | 处理 |
  364. |---|---|---|
  365. | 命中有「随机抽卡」感 | `cards_fts` 行数 < `cards` 行数 | 上面两行命令 |
  366. | 语义召回像没开 | `card_vec` 覆盖率 < 30%,门控会静默关掉 | 面板 → 语义召回 → 补向量(`batch 16`) |
  367. | 越用越慢 | 索引缺失时每次召回都走全表扫描 | 同上,先重建索引 |
  368. > 反过来的情况也要知道:**索引建全、向量灌满之后,召回会从「全表兜底」切到「FTS + 语义融合」**,单次耗时从几毫秒升到约 300 ms(1 万张、dim=1024)。这是花了时间换准确度,不是变慢的 bug —— 觉得不划算就把语义关掉,词法路径照常。
  369. ### 🧯 任意一环挂了会怎样
  370. | 失败点 | 自动行为 | 你看到的现象 |
  371. |---|---|---|
  372. | Ollama 没启动 / 端口不通 | 60s 失败冷却,退回纯词法 | 召回照常,只是同义词弱一些 |
  373. | 向量覆盖率 < 30% | 不启用语义路 | 同上(避免"半库向量"污染排序) |
  374. | rerank 未配置 / 超时 | 保留原排序 | 无感 |
  375. | 宿主 LLM 不可用 | 存原文卡,标记降级 | 卡片变「原始对话」,仍要人审 |
  376. | FTS 索引异常 | 全表兜底扫描 | 召回变慢但仍能搜到 |
  377. | 库文件损坏 | 每日备份 + auto-restore | 启动时自动回滚到最近可用备份 |
  378. ## 🔗 MEM Pair:两个记忆库互配对、互传卡(v0.49.10)
  379. 本机常常同时跑着多个 memory-eternal:运营库(7999)、隔离运营的 mem-purge(7989)、云端实例。
  380. 它们各有独立 SQLite,**不能共享一个库**;但你需要让它们互相喂料(运营口径 → purge,purge 的清理结论 → 运营库)。
  381. MEM Pair 就是这套「显式、可审计、默认不打扰」的通道:
  382. | 阶段 | 怎么做 | 判定信号 |
  383. |---|---|---|
  384. | 发现 | 局域网 UDP 广播(默认 7990),或直接填 `host:port` | 面板列出对方名字 + **匹配码** + 指纹 |
  385. | 首次配对 | 一端发起 → 另一端**面板弹窗**确认(显示 6 位握手码,两边肉眼核对) | 双方配对表里都出现对方 |
  386. | 之后再连 | **只需要匹配码**:对方认得这个码且指纹没变 → 直接建立,不再弹窗 | 面板显示「已配对 → 对方」 |
  387. | 指纹变了 | 对方重装 / 可能被冒充 → 回到人工确认,弹窗标红 | 必须重新点确认 |
  388. | 传数据 | 「上传」(本库 → 对方)/「下载」(对方 → 本库),一律进**对方待审队列** | 计数:sent / written / failed |
  389. ```bash
  390. dsh-memory peer code # 我的匹配码
  391. dsh-memory peer pair 192.168.1.20:7989 # 首次配对(对方要确认)
  392. dsh-memory peer connect 7K2M-Q9FA --host 192.168.1.20 --port 7989 # 之后只凭码重连
  393. dsh-memory peer upload --to 7K2M-Q9FA # 推卡过去(进对方待审)
  394. dsh-memory peer download --from 7K2M-Q9FA # 拉卡回来(进本库待审)
  395. ```
  396. 安全口径:共享密钥由两端各自算出(一次性 ephemeral 派生,长期密钥永不上网);每个请求带 HMAC 签名 + ±5 分钟时间窗 + nonce 去重;对方推来的卡**只能进待审**,不会直接污染已审库。
  397. ## 🔌 Agent MCP 挂载(一份标准,六种宿主)
  398. **作为 DSH 插件安装时,默认就把 MCP 挂到 DSH 自己**(`~/.dsh/mcp-servers.json`),装好即用;
  399. Claude Code / Codex / Cursor / Windsurf 这些「你另开的宿主」**必须手动挂** —— 否则同一个仓库里
  400. 被多个 agent 读到不同库,沉淀与召回就会串味。
  401. 所有宿主共用同一个标准(一处声明 → 各自渲染):server 名固定 `memory-eternal`、只用 stdio、
  402. 命令写绝对路径、参数走 `env`、幂等写入且**只增删自己那一条**、写后回读校验、能检测「指向旧包路径」的漂移。
  403. ```bash
  404. dsh-memory mcp status # 状态 + 各宿主矩阵
  405. dsh-memory mcp mount --vault ~/.dsh/memory-vault # 挂本机库(默认只写 DSH)
  406. dsh-memory mcp mount --url http://127.0.0.1:7989 --host dsh,claude # 一次投影多个宿主
  407. dsh-memory mcp mount --vault <库> --host all # 所有已安装宿主
  408. dsh-memory mcp unmount # 从所有已挂载宿主摘掉(幂等)
  409. ```
  410. 面板:**设置 → 🧪 实验性 → 🔌 Agent MCP 挂载**(v0.49.10 起是**列表点击式**)
  411. ```text
  412. ● 2 / 6 已挂载 → 本机默认库 [刷新] [自检]
  413. ⬤ 装成 DSH 插件时自动挂载 默认开启,装好即用…
  414. 挂哪个库(点一行选中)
  415. ● 本机默认库 已选中 ○ mem-purge 9DUW-QPVM ○ 云端 5EZK-RWM5
  416. 挂到哪些宿主(点哪行就挂/摘哪行) [全部挂载] [全部卸载]
  417. ● DeepSeek Harness (DSH) 已挂载 …\.dsh\mcp-servers.json 卸载
  418. ○ Claude Code 未挂载 …\.claude.json 挂载
  419. ○ Claude 项目级 .mcp.json 未挂载 …\.mcp.json 挂载
  420. 展开其余 3 个宿主
  421. ```
  422. - **默认只显示 3 个宿主**,多出来的收进「展开其余 N 个宿主」;
  423. - 每行状态一眼可辨:实心绿=已挂载 / 空心=未挂载 / 虚线圈=未安装(未安装置灰不可点);
  424. - **「自检」按钮**会**真的拉起一次 MCP 进程做 initialize 握手**,把 `ok / 耗时 / 启动命令 / stderr` 直接显示出来 —— Windows 上"路径不对、宿主识别不了"当场就能看到原因;
  425. - **Windows / Electron 兼容**:条目里的 node 不再取 `process.execPath`(在 DSH 这类 Electron 宿主里那是宿主自己的 exe),而是走 PATH 解析 + 校验存在性;写盘前统一反斜杠绝对路径,**脚本不存在直接拒绝写入**(不留死条目);
  426. - 想彻底关掉自动挂载:配置 `mcpAutoMount: false`,或环境变量 `MEMORY_MCP_AUTOMOUNT=0`。
  427. ## 🧷 多实例并行:端口、库文件名、vault 目录
  428. 同一台机跑多个 memory-eternal(比如运营库 + 某个项目的隔离库)时,三个维度都能分开:
  429. | 维度 | 怎么设 | 默认 |
  430. |---|---|---|
  431. | **端口** | `dsh-memory open --port 7989` / `serve --port 7989` / 环境变量 `MEMORY_WEB_PORT=7989` / 配置项 `webPort` | 7999 |
  432. | **库文件名** | 环境变量 `MEMORY_DB_FILE=mem-purge.db` | `memory-eternal.db` |
  433. | **vault 目录** | `--vault <dir>` / 配置项 `vaultDir` / `vaultProfiles` 多库切换 | `~/.dsh/memory-vault` |
  434. ```bash
  435. # 第二个实例:端口 7989、库文件 mem-purge.db、独立 vault
  436. DSH_HOME=~/.dsh/memory-vault-mem-purge \
  437. MEMORY_WEB_PORT=7989 \
  438. MEMORY_DB_FILE=mem-purge.db \
  439. node $(dirname $(which dsh-memory))/../lib/web.js --port 7989 --vault ~/.dsh/memory-vault-mem-purge
  440. ```
  441. 两个安全口径:
  442. - 库文件名只接受**纯文件名**(字母数字 `.` `_` `-`,必须以 `.db` 结尾),带路径分隔符一律退回默认名 —— 不会因为一个环境变量把库写到别处;
  443. - 设了自定义名、但该目录里已经是 `memory-eternal.db` 的库 → **继续用标准名**,避免"改了个环境变量结果打开空库、以为数据丢了"。
  444. ## 📚 文档与链接
  445. - [完整手册(中文)](docs/GUIDE.zh-CN.md) · [Full manual (English)](docs/GUIDE.md)
  446. - [云端多租户与部署](docs/CLOUD.md) · [私有化部署(Docker / systemd)](docs/DEPLOY.md) · [私有组件边界](docs/PRIVATE.md)
  447. - [更新日志](docs/CHANGELOG.md) · [架构细节](docs/ARCHITECTURE.md) · [主题皮肤](docs/UI-SKINS.md)
  448. - [📚 全部文档索引](docs/README.md) —— 接入 / 运维 / 历史发版说明按目录归档
  449. - [终端插件(dsh-tui)](dsh-tui-plugin/README.md) · [Orca 启动器](orca-plugin/README.md) · [Cursor / VS Code 扩展](cursor-extension/README.md)
  450. - [反馈问题](https://github.com/EternalNight996/memory-eternal/issues)
  451. ## 💬 交流群
  452. **遇到问题、想提需求、或者想聊聊 DSH 插件开发 —— 欢迎进群:**
  453. | QQ 交流群 | 微信交流群 |
  454. |:---:|:---:|
  455. | <img src="https://raw.githubusercontent.com/EternalNight996/memory-eternal/main/assets/support/group-qr.jpg" width="240" alt="QQ 群二维码" /> | <img src="https://raw.githubusercontent.com/EternalNight996/memory-eternal/main/assets/support/group-wechat.jpg" width="240" alt="微信群二维码" /> |
  456. **如果这个插件帮你省了时间,可以请作者喝杯咖啡(微信 / 支付宝任选其一):**
  457. | 微信收款码 | 微信赞赏码 | 支付宝 |
  458. |:---:|:---:|:---:|
  459. | <img src="https://raw.githubusercontent.com/EternalNight996/memory-eternal/main/assets/support/wechat-pay.jpg" width="200" alt="微信收款码" /> | <img src="https://raw.githubusercontent.com/EternalNight996/memory-eternal/main/assets/support/wechat-reward.jpg" width="200" alt="微信赞赏码" /> | <img src="https://raw.githubusercontent.com/EternalNight996/memory-eternal/main/assets/support/alipay.jpg" width="200" alt="支付宝收款码" /> |
  460. > 打赏完全自愿,不影响任何功能;插件本体始终开源免费(MIT)。详见 [SPONSOR.md](SPONSOR.md)。
  461. ## 📄 License
  462. MIT —— 随便用、随便自托管、随便二次开发。
  463. ## 🖋 作者语录
  464. _「大爱」二字,是全篇最大的反讽。面板左栏底部同步轮播。_
  465. > 落魄谷中寒风吹,春秋蝉鸣少年归。<br>
  466. > 荡魂山处石人泪,定仙游走魔向北。<br>
  467. > 逆流河上万仙退,爱情不敌坚持泪。<br>
  468. > 宿命天成命中败,仙尊悔而我不悔。
  469. > 早岁已知世事艰,仍许飞鸿荡云间。
  470. > 男儿不展凌云志,空负天生八尺躯。
  471. > 天河一挂淘龙鱼,逆天独行顾八荒。<br>
  472. > 今朝暂且展翼去,明朝飞仙笞凤凰!
  473. <p align="right"><sub>——《蛊真人》· 大爱仙尊</sub></p>
  474. ## 🌟 贡献者
  475. 感谢每一位让记忆核心更好用的人。
  476. | 贡献者 | 贡献 |
  477. | --- | --- |
  478. | [@aloneangel45](https://github.com/aloneangel45) | 发现并修复 [#54](https://github.com/EternalNight996/memory-eternal/issues/54) —— `tools` 服务晚挂载时 `memory_recall` / `memory_note` 从未注册([#58](https://github.com/EternalNight996/memory-eternal/pull/58)) |
  479. | [@EternalNight996](https://github.com/EternalNight996) | 作者与维护者 |
  480. 有想落地的修复?欢迎开 issue 或 PR —— 每个被合并的贡献都会出现在这里。
lib/ollama-install.js · Bundled script · 211 lines · 1 finding marked
  1. // Ollama 安装闭环:下载安装器 → 静默安装 → 等可执行文件出现
  2. //
  3. // 为什么需要它:原来 `/embedding/install-ollama` 只能跑「你已经下好安装器、并且把路径写进
  4. // MEMORY_OLLAMA_SETUP」这一条路,没装的人点按钮只会拿到一个下载链接 —— 面板上看着像能装,
  5. // 实际还是手动挡。这里把三件事接起来,让「没装」也能一键走完。
  6. //
  7. // 安全边界:
  8. // · 只从**官方域**取安装器(可用 MEMORY_OLLAMA_MIRROR 指向可信镜像做国内加速);
  9. // · 下载后校验文件大小(<10MB 视为失败页/错误响应)并记录 sha256 到日志;
  10. // · 静默安装参数先 Inno(/VERYSILENT),再退 NSIS(/S);都失败就把安装器路径交给用户;
  11. // · **执行前校验路径**(审计 S3):只允许安装器后缀、必须是绝对路径、必须已存在 ——
  12. // 调用方(`/embedding/install-ollama`)已改成只认 MEMORY_OLLAMA_SETUP,这里再兜一道,
  13. // 避免以后有人从别的入口把任意路径送进 execFile;
  14. // · MEMORY_OLLAMA_INSTALL_DRY=1 时只下载不执行(CI/测试用)。
  15. import fs from 'node:fs'
  16. import fsp from 'node:fs/promises'
  17. import path from 'node:path'
  18. import os from 'node:os'
  19. import crypto from 'node:crypto'
  20. import { execFile } from 'node:child_process'
  21. import { findOllamaExe } from './ollama-service.js'
  22. const OFFICIAL_URL = 'https://ollama.com/download/OllamaSetup.exe'
    • Note: Links to a Windows program from code, which is how droppers fetch their payload
    • Line 24 on GitHub
  23. const MIN_SIZE = 10 * 1024 * 1024
  24. const MAX_WAIT_MS = 3 * 60 * 1000
  25. /**
  26. * 允许被执行的安装器后缀。
  27. *
  28. * 为什么按后缀拦:`runSilentInstall` 的入参最终会进 `execFile(exePath, …)`,
  29. * 等于「以插件权限执行一个文件」。把可选集合钉在安装器类型上,
  30. * 挡得住「任意脚本/任意无后缀文件」,但**挡不住 `cmd.exe`**(它后缀合法又真实存在)——
  31. * 所以还有下面的黑名单,以及最关键的「只认 MEMORY_OLLAMA_SETUP」(见 lib/api.js 的路由)。
  32. */
  33. export const INSTALLER_EXTS = ['.exe', '.msi', '.dmg', '.pkg', '.sh', '.deb']
  34. /** 明确不许执行的通用解释器 / 加载器(审计 S3 的 PoC 就是 cmd.exe)。 */
  35. const BLOCKED_BASENAMES = new Set([
  36. 'cmd.exe', 'conhost.exe', 'powershell.exe', 'pwsh.exe', 'wscript.exe', 'cscript.exe',
  37. 'mshta.exe', 'rundll32.exe', 'regsvr32.exe', 'certutil.exe', 'bitsadmin.exe', 'msiexec.exe',
  38. 'sh', 'bash', 'zsh', 'dash', 'ksh', 'csh', 'su', 'sudo', 'curl', 'wget',
  39. 'python', 'python.exe', 'python3', 'node', 'node.exe', 'perl', 'perl.exe', 'ruby', 'php',
  40. ])
  41. /**
  42. * 校验一个「要执行的安装器」路径是否可信。
  43. *
  44. * 三条硬要求(缺一不可):**绝对路径** + **已存在的文件** + **安装器后缀**,
  45. * 外加通用解释器/加载器黑名单。相对路径会让工作目录(比如用户的项目目录)决定执行什么,必须拒。
  46. *
  47. * @param {string} raw 待校验的路径(通常来自 MEMORY_OLLAMA_SETUP)
  48. * @returns {{ok:boolean, path?:string, error?:string, code?:string}}
  49. */
  50. export function validateInstallerPath(raw) {
  51. const want = String(raw || '').trim()
  52. if (!want) {
  53. return {
  54. ok: false, code: 'setup_not_configured',
  55. error: '未配置安装器:只允许执行 MEMORY_OLLAMA_SETUP 指定的安装器',
  56. }
  57. }
  58. if (!path.isAbsolute(want)) {
  59. return { ok: false, code: 'path_not_absolute', error: '安装器必须是绝对路径:' + want }
  60. }
  61. const ext = path.extname(want).toLowerCase()
  62. if (!INSTALLER_EXTS.includes(ext)) {
  63. return {
  64. ok: false, code: 'path_not_allowed',
  65. error: '只允许执行安装器文件(' + INSTALLER_EXTS.join(' / ') + '),收到:' + (ext || '(无后缀)'),
  66. }
  67. }
  68. const base = path.basename(want).toLowerCase()
  69. if (BLOCKED_BASENAMES.has(base)) {
  70. return { ok: false, code: 'path_not_allowed', error: '不允许执行通用解释器/加载器:' + base }
  71. }
  72. let st = null
  73. try { st = fs.statSync(want) } catch { st = null }
  74. if (!st || !st.isFile()) {
  75. return { ok: false, code: 'path_not_found', error: '安装器不存在或不是普通文件:' + want }
  76. }
  77. return { ok: true, path: path.resolve(want) }
  78. }
  79. /** 安装任务状态(模块级,进程内单例:同时只允许一个安装)。 */
  80. let job = { phase: 'idle', at: 0, bytes: 0, total: 0, path: '', sha256: '', error: '', log: [] }
  81. const pushLog = (line) => {
  82. job.log = [...job.log.slice(-19), { at: Date.now(), line: String(line).slice(0, 300) }]
  83. }
  84. export function installState() {
  85. return { ...job, installed: !!findOllamaExe(process.env), exe: findOllamaExe(process.env) }
  86. }
  87. function setPhase(phase, patch = {}) {
  88. job = { ...job, ...patch, phase, at: Date.now() }
  89. pushLog(phase + (patch.error ? ':' + patch.error : ''))
  90. }
  91. /**
  92. * 下载安装器(流式,带进度)。
  93. * @param {{url?:string, dest?:string, env?:NodeJS.ProcessEnv}} opts
  94. */
  95. export async function downloadInstaller({ url = '', dest = '', env = process.env } = {}) {
  96. const mirror = String(env.MEMORY_OLLAMA_MIRROR || '').trim()
  97. const target = String(url || mirror || OFFICIAL_URL).trim()
  98. // 默认落到**本次运行独占**的目录(mkdtemp → 0700)而不是共享 tmp 里的固定文件名:
  99. // 固定名字 + 共享 tmp 正是「预置同名符号链接 → 高权进程覆盖任意文件」的组合(与审计 H3 同类)。
  100. const out = dest
  101. ? path.resolve(String(dest))
  102. : path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'me-ollama-')), 'OllamaSetup.exe')
  103. setPhase('downloading', { path: out, bytes: 0, total: 0, error: '' })
  104. const res = await fetch(target, { redirect: 'follow' })
  105. if (!res.ok) throw new Error('下载失败 HTTP ' + res.status + '(' + target + ')')
  106. const total = Number(res.headers.get('content-length') || 0)
  107. job.total = total
  108. await fsp.mkdir(path.dirname(out), { recursive: true })
  109. const tmp = out + '.part'
  110. // 清掉可能残留的 .part,再用 wx 独占创建(既防符号链接抢跑,也不覆盖别人的文件)
  111. await fsp.rm(tmp, { force: true })
  112. const hash = crypto.createHash('sha256')
  113. const file = fs.createWriteStream(tmp, { flags: 'wx', mode: 0o600 })
  114. let bytes = 0
  115. try {
  116. for await (const chunk of res.body) {
  117. bytes += chunk.length
  118. hash.update(chunk)
  119. file.write(chunk)
  120. job.bytes = bytes
  121. }
  122. } finally {
  123. await new Promise((r) => file.end(r))
  124. }
  125. const size = (await fsp.stat(tmp)).size
  126. if (size < MIN_SIZE) {
  127. await fsp.rm(tmp, { force: true })
  128. throw new Error(`安装器只有 ${Math.round(size / 1024)} KB,明显不是安装包(可能被重定向到错误页)`)
  129. }
  130. await fsp.rename(tmp, out)
  131. job.sha256 = hash.digest('hex')
  132. print(`downloaded ${out} ${Math.round(size / 1048576)}MB sha256=${job.sha256.slice(0, 16)}`)
  133. return { path: out, size, sha256: job.sha256 }
  134. }
  135. const print = (s) => { try { console.error('[memory-eternal] ollama-install: ' + s) } catch { /* 忽略 */ } }
  136. /** 跑静默安装(先 Inno 参数,失败退 NSIS)。会等到进程退出。 */
  137. export function runSilentInstall(exePath, { env = process.env, timeoutMs = 10 * 60 * 1000 } = {}) {
  138. // ★ 防线(审计 S3):进 execFile 之前先过「绝对路径 + 已存在 + 安装器后缀」三关
  139. const check = validateInstallerPath(exePath)
  140. if (!check.ok) {
  141. setPhase('failed', { path: String(exePath || ''), error: check.error })
  142. return Promise.resolve({ ok: false, code: check.code, error: check.error })
  143. }
  144. const exe = check.path
  145. if (String(env.MEMORY_OLLAMA_INSTALL_DRY || '') === '1') {
  146. setPhase('verifying', { path: exe })
  147. return Promise.resolve({ ok: true, dry: true })
  148. }
  149. setPhase('installing', { path: exe })
  150. const attempts = [
  151. ['/VERYSILENT', '/SUPPRESSMSGBOXES', '/NORESTART', '/SP-'],
  152. ['/S'],
  153. ]
  154. return new Promise((resolve) => {
  155. const tryAt = (i) => {
  156. if (i >= attempts.length) return resolve({ ok: false, error: '静默安装参数都被拒绝,请手动运行:' + exe })
  157. const child = execFile(exe, attempts[i], { timeout: timeoutMs, windowsHide: true, env }, (err) => {
  158. // Inno 的静默安装经常返回非 0 但实际已装好:交给后面的 findOllamaExe 判定
  159. if (err && i + 1 < attempts.length) return tryAt(i + 1)
  160. resolve({ ok: !err, code: err ? (err.code || 1) : 0, args: attempts[i] })
  161. })
  162. try { child.unref?.() } catch { /* 忽略 */ }
  163. }
  164. tryAt(0)
  165. })
  166. }
  167. /** 等可执行文件出现(安装器是异步的,装完才落地)。 */
  168. export async function waitInstalled({ timeoutMs = MAX_WAIT_MS } = {}) {
  169. const deadline = Date.now() + timeoutMs
  170. while (Date.now() < deadline) {
  171. const exe = findOllamaExe(process.env)
  172. if (exe) { setPhase('done', { path: exe }); return exe }
  173. await new Promise((r) => setTimeout(r, 1500))
  174. }
  175. return ''
  176. }
  177. /**
  178. * 一键安装:已有就跳过;否则下载 → 静默安装 → 等 exe。
  179. * @returns {Promise<{ok:boolean, exe?:string, phase?:string, error?:string, path?:string}>}
  180. */
  181. export async function autoInstall({ env = process.env, url = '' } = {}) {
  182. if (job.phase === 'downloading' || job.phase === 'installing') return { ok: false, busy: true, phase: job.phase }
  183. const existing = findOllamaExe(env)
  184. if (existing) { setPhase('done', { path: existing }); return { ok: true, exe: existing, phase: 'done' } }
  185. try {
  186. const dl = await downloadInstaller({ url, env })
  187. const run = await runSilentInstall(dl.path, { env })
  188. if (!run.ok) { setPhase('failed', { error: run.error || '安装失败' }); return { ok: false, phase: 'failed', error: run.error, path: dl.path } }
  189. setPhase('verifying', { path: dl.path })
  190. const exe = await waitInstalled({})
  191. if (!exe) {
  192. setPhase('failed', { error: '安装器跑完了但没找到 ollama 可执行文件(可能要重启终端/系统),安装器在:' + dl.path })
  193. return { ok: false, phase: 'failed', error: '安装后仍未检测到可执行文件', path: dl.path }
  194. }
  195. return { ok: true, exe, phase: 'done', path: dl.path }
  196. } catch (e) {
  197. const msg = String((e && e.message) || e)
  198. setPhase('failed', { error: msg })
  199. return { ok: false, phase: 'failed', error: msg }
  200. }
  201. }
scripts/setup-local-embedding.ps1 · Bundled script · 90 lines · 1 finding marked
  1. # 本地语义召回服务(Ollama)离线安装/配置助手
  2. #
  3. # 背景:很多内网机器无法直连 ollama.com / registry.ollama.ai。本脚本不负责联网下载,
  4. # 而是把「已经拷进来的安装包 / 模型」装好、配好 7997 端口,并验证 OpenAI 兼容端点。
  5. #
  6. # 用法:
  7. # # A. 只装了安装包(模型还要联网 pull)
  8. # powershell -ExecutionPolicy Bypass -File scripts\setup-local-embedding.ps1 -OllamaSetup D:\OllamaSetup.exe
  9. #
  10. # # B. 离线:把另一台机器上 %USERPROFILE%\.ollama\models 整个目录拷过来
  11. # powershell ... -OllamaSetup D:\OllamaSetup.exe -ModelsFrom D:\ollama-models
  12. #
  13. # # C. 离线:用 GGUF 文件创建模型(模型名默认 bge-m3)
  14. # powershell ... -Gguf D:\bge-m3.Q4_K_M.gguf
  15. #
  16. # 做完后到「设置 → 记忆 → 语义召回(可选)」点「检测连接 → 一键配置并建缓存」。
  17. param(
  18. [string]$OllamaSetup,
  19. [string]$ModelsFrom,
  20. [string]$Gguf,
  21. [string]$Model = 'bge-m3',
  22. [int]$Port = 7997
  23. )
  24. $ErrorActionPreference = 'Stop'
  25. function Info($m) { Write-Host "[ollama-setup] $m" }
  26. # 1) 安装
  27. $exe = Join-Path $env:LOCALAPPDATA 'Programs\Ollama\ollama.exe'
  28. if (-not (Test-Path $exe)) {
  29. if (-not $OllamaSetup) {
  30. Write-Host "未检测到 Ollama,也没有传 -OllamaSetup。请在有网的机器下载 https://ollama.com/download/OllamaSetup.exe 后拷过来再运行。" -ForegroundColor Yellow
    • Dismissed after review: Links to a Windows program from code, which is how droppers fetch their payload
    • Line 32 on GitHub
  31. exit 2
  32. }
  33. if (-not (Test-Path $OllamaSetup)) { throw "找不到安装包:$OllamaSetup" }
  34. Info "安装 Ollama:$OllamaSetup"
  35. Start-Process -FilePath $OllamaSetup -ArgumentList '/S' -Wait
  36. if (-not (Test-Path $exe)) { throw '安装后仍未找到 ollama.exe,请手动确认安装位置' }
  37. }
  38. # 2) 端口固定到 7997(写用户环境变量,后续终端生效)
  39. [Environment]::SetEnvironmentVariable('OLLAMA_HOST', "127.0.0.1:$Port", 'User')
  40. $env:OLLAMA_HOST = "127.0.0.1:$Port"
  41. Info "OLLAMA_HOST=127.0.0.1:$Port(已写入用户环境变量)"
  42. # 3) 离线模型目录(可选):直接覆盖到本机 Ollama models
  43. if ($ModelsFrom) {
  44. if (-not (Test-Path $ModelsFrom)) { throw "找不到模型目录:$ModelsFrom" }
  45. $dst = Join-Path $env:USERPROFILE '.ollama\models'
  46. New-Item -ItemType Directory -Path $dst -Force | Out-Null
  47. Info "复制模型目录 → $dst(可能较慢,约 1–2GB)"
  48. Copy-Item (Join-Path $ModelsFrom '*') $dst -Recurse -Force
  49. }
  50. # 4) 启动服务(若端口没在监听)
  51. function Test-Port($p) { try { (Test-NetConnection -ComputerName 127.0.0.1 -Port $p -InformationLevel Quiet -WarningAction SilentlyContinue) } catch { $false } }
  52. if (-not (Test-Port $Port)) {
  53. Info '启动 ollama serve(后台)'
  54. Start-Process -FilePath $exe -ArgumentList 'serve' -WindowStyle Hidden
  55. for ($i = 0; $i -lt 30 -and -not (Test-Port $Port); $i++) { Start-Sleep -Milliseconds 500 }
  56. if (-not (Test-Port $Port)) { throw "服务没有在 $Port 上起来;检查 OLLAMA_HOST 是否被其它进程占用" }
  57. }
  58. # 5) 模型:GGUF 导入 > 已拷贝 > pull(需要外网)
  59. if ($Gguf) {
  60. if (-not (Test-Path $Gguf)) { throw "找不到 GGUF:$Gguf" }
  61. $mf = Join-Path $env:TEMP 'Modelfile.bge'
  62. "FROM $Gguf" | Set-Content -Path $mf -Encoding ASCII
  63. Info "从 GGUF 创建模型 $Model"
  64. & $exe create $Model -f $mf
  65. } else {
  66. $has = $false
  67. try {
  68. $tags = (curl.exe -s --max-time 5 "http://127.0.0.1:$Port/api/tags") | ConvertFrom-Json
  69. $has = @($tags.models | ForEach-Object { $_.name }) -contains $Model
  70. } catch { $has = $false }
  71. if (-not $has) {
  72. Info "本机没有模型 $Model,尝试 ollama pull(需要联网;离线请用 -ModelsFrom 或 -Gguf)"
  73. & $exe pull $Model
  74. }
  75. }
  76. # 6) 验证 OpenAI 兼容端点
  77. $probe = curl.exe -s --max-time 8 "http://127.0.0.1:$Port/v1/models"
  78. Info "GET /v1/models => $probe"
  79. $payload = '{"model":"' + $Model + '","input":"测试"}'
  80. $embed = curl.exe -s --max-time 20 -X POST "http://127.0.0.1:$Port/v1/embeddings" -H 'Content-Type: application/json' -d $payload
  81. $embedHead = if ($embed) { $embed.Substring(0, [Math]::Min(160, $embed.Length)) } else { '(空响应,检查模型名/服务日志)' }
  82. Info "POST /v1/embeddings => $embedHead"
  83. Info '完成。回到 DSH:设置 → 记忆 → 语义召回(可选)→ 检测连接 → 一键配置并建缓存。'

Version history

  • v0.49.1411/18/2026

  • v0.49.1311/17/2026

  • v0.49.111/16/2026

  • v0.45.011/14/2026

  • v0.40.111/13/2026

  • v0.31.411/12/2026

  • v0.31.211/11/2026

  • v0.30.211/9/2026

  • v0.28.111/8/2026

  • v0.27.111/7/2026

  • v0.22.011/5/2026

  • v0.19.010/31/2026

  • v0.18.210/27/2026

  • v0.17.010/25/2026

  • v0.15.010/23/2026

  • v0.10.5410/21/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.