memory-eternal

Your AI forgets every session. Give it a memory you can audit: local-first, review-gated agent memory — one SQLite vault for DSH, Claude Code, Codex, Cursor, OpenClaw, Hermes and MengBot (any MCP client), with an immutable audit log and a token ledger. Agents propose, humans approve. MIT, self-hosted, no cloud.

Automatically checked · GitHub checked 2026-11-12

memory-eternal

Overview

🧠 memory-eternal —— 给 AI 装一个可信的第二大脑

memory-eternal icon

memory-eternal 蜘蛛侠皮肤:本地、可审核、可同步云端的 AI 长期记忆

stars npm release license

English · 简体中文(默认)

☁️ 云端记忆(v0.49.10 主打)

记忆库跟着人走,不跟着机器走。 本机库照旧离线可用;登录云端后,同一套知识卡在你的每台设备、每个 Agent 上都能读到 —— 换电脑不用搬家,换客户端不用重新喂上下文。

能力你能得到
一次登录MengBot 账号扫码 / 邮箱登录,或在任意实例上签发的访问密钥(me_…)
一人一库云端按 owner 分目录,每个用户一个独立 SQLite(cloud-vaults/{owner}/memory-eternal.db),物理隔离
换库不重启本地库 ↔ 云端库热切换(POST /vaults/switch):知识卡、星图、待审、回收站一次性换源,不刷新页面
上传 / 下载整库复制(本机 → 云端、云端 → 本机),分片传输 + 断点续传 + 中途取消 + 失败重试 3 次,重复内容自动跳过
离线优先云端不可达自动熔断、回退本地库,首屏最多等 3 秒;本地记忆一分不丢
自有实例自己的服务器跑 memory-eternal-cloud(systemd / Docker + HTTPS 反代),密钥可签发、可吊销、只存 sha256
发密钥三处入口CLI(dsh-memory cloud keys issue,本地台账模式免令牌)· 面板「🔑 服务端密钥管理」· curl;管理令牌首次启动自动生成
# ① 起一个云端实例(默认关闭,不开就是纯本地)
MEMORY_CLOUD=1 node lib/web.js --port 7999     # Docker / systemd 部署见 docs/CLOUD.md
# 首次启动会自动生成管理令牌 → $DSH_HOME/cloud-admin-token(0600,日志打印一次)

# ② 签发访问密钥(三选一)
dsh-memory cloud keys issue --owner alice --note 笔记本   # CLI:能在这台机跑命令就是管理员,免令牌、立即生效
# 或:面板 → 设置 → 🧪 实验性 → 云端连接 → 「🔑 服务端密钥管理」→ 粘贴管理令牌 → 新建
curl -X POST http://127.0.0.1:7999/memory-eternal/api/cloud/keys \
  -H "Authorization: Bearer $MEMORY_CLOUD_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' -d '{"owner":"alice"}'

# ③ 面板:设置 → 🧪 实验性 → 云端连接 → 填地址 + 密钥 → [测试连接] → [保存并切换]

反代 / 容器部署记两个变量:MEMORY_CLOUD_ADMIN_TOKEN(不配就用自动生成的那把;配了以它为准)、MEMORY_PUBLIC_HOST(写请求的 Host 白名单,填你的域名)。 边界说明:云端服务端(多租户 + 鉴权 + 计费对接)是独立私有组件,不随本开源包发布; 相关接口仍在快速迭代、可能微调。不用云端时,本地功能与之前完全一致 —— 见 docs/CLOUD.md、docs/PRIVATE.md。

📊 与同类产品的实测对比

数据日期 2026-11-18:Stars 取自 GitHub API(整数实值);公开成绩按各自 README / 论文原文口径转录, 不同指标的分数绝不混排。可视化版见 bench/comparison.html,口径与复跑脚本见 bench/COMPARISON.md。

表 1 · 记忆类:综合判断(10 维加权,我们自己的评分口径)

排名项目召回语义隐私治理成本总分
🥇 1memory-eternal(Ollama)8.68.69.59.08.08.54
🥈 2memory-eternal(内置语义)7.16.89.59.09.58.48
🥉 3Mem0(69.1k★)9.39.06.06.06.57.49
4MemOS(12.4k★)8.58.57.06.07.07.38
5graphiti(32.9k★)7.88.58.06.07.07.26
6basic-memory(4.6k★)6.56.59.06.09.07.26
7Letta(25.5k★)8.08.58.06.06.57.22
8mcp-memory-service(2.1k★)6.06.09.05.09.57.17
9memobase(3.0k★)7.27.08.06.08.07.15
10cognee(33.4k★)8.08.58.05.57.07.14
11supermemory(31.6k★)8.08.06.55.56.57.14
12Zep(5.0k★,产品闭源)7.07.56.56.56.06.88

表 2 · 记忆类:公开基准与部署硬指标

项目Stars公开成绩(原文口径)本地 / 零 API人工审核闸门
memory-eternal(bge-m3)196自建 500 题 R@5 97.2%(检索口径)需 Ollama✅
memory-eternal(内置)196自建 500 题 R@5 95.4%(检索口径)✅ / ✅✅
Mem069,120LongMemEval 94.4(托管平台口径,非开源版)部分弱
cognee33,371BEAM 100K 0.79 / BEAM 10M 0.67(0–1)部分中
graphiti32,889仓库无 LongMemEval / LoCoMo 数字部分中
supermemory31,644LongMemEval R@15 95%(约 720 token)部分弱
Letta ※25,471仓库无 LongMemEval / LoCoMo 数字部分中
MemOS12,435LongMemEval 89.20(OmniMemEval)部分中
Zep ※5,007论文:LongMemEval 准确率比 MemGPT +18.5%、延迟 −90%❌中
basic-memory4,612仓库无公开记忆基准数字✅ / ✅弱
memobase2,960LoCoMo 75.78(第三方复现,LLM-Judge Overall)部分中
mcp-memory-service2,135LongMemEval-S R@5 86.0%(零 LLM 调用)✅ / ✅弱

※ 必须标注的状态:getzep/zep 仓库是 Zep Cloud 的示例 / 集成目录,产品本体闭源(开源图引擎是 graphiti); letta-ai/letta 主仓已归档,活跃源码迁到 letta-code。这两家不能当"开源版 star"读。

🏷 命令名与别名

包名从一开始就是中性的 memory-eternal;只有命令行工具早期叫 dsh-memory(那时它只服务 DSH)。 现在三种写法是同一个入口:

命令用在哪
memory主名。任何宿主、纯 CLI、脚本里都推荐用它
mem简短别名,终端里敲得少
dsh-memory兼容入口。老文档、老脚本、DSH 插件内部仍用它,不会被移除
memory status --port 7999      # 等价于 dsh-memory status --port 7999
mem peer code                  # 等价于 dsh-memory peer code

数据目录同理不受限:MEMORY_VAULT_DIR(库目录)、MEMORY_DB_FILE(库文件名)、MEMORY_WEB_PORT(端口) 都可以改,所以库不一定要待在 ~/.dsh 下面。

⚡ 快速开始

# DSH 桌面版 / Web
dsh plugin --profile desktop add memory-eternal     # 重开 DSH → 左栏「记忆」

# 同一套库接 Claude Code / Codex / Cursor(MCP)
npm i -g memory-eternal && dsh-memory connect claude

# 任意 MCP 客户端(MengBot / OpenClaw / Hermes 见 docs/INTEGRATIONS.md)
npx -y -p memory-eternal dsh-memory mcp

# 云端 bot / 远程 agent:直接走 HTTP,不用装进程
curl -s http://127.0.0.1:7999/memory-eternal/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 浏览器 / 终端
dsh-memory open                             # http://127.0.0.1:7999
npx -y -p memory-eternal dsh-memory tui     # 终端里的实时待审队列

⭐ 如果它帮你少解释了一遍上下文,点个 Star 就是最大的支持

🧾 真的省 token 吗?

大多数记忆产品都说自己省 token。我们认为你应该自己验证。插件内置记忆账本(运行状态 → 记忆账本):

记录项含义
召回:命中数 + 注入字符到底有多少记忆进入了上下文
沉淀:LLM 调用次数 + 输入/输出字符蒸馏花了你多少成本
有用率:有用 / 没用 反馈召回的记忆是否真的帮上了忙
净收益 ≈ 被避免的上下文开销 −(注入字符 + 蒸馏调用 × 单价)
场景你要付你能省
有决策与踩坑记录的多会话项目每次召回约 0.6–0.9k token重新解释上下文(约 1.5–3k)或重读文件(3–6k)
一次性问题、低命中率召回注入通常什么也省不到

以上是示意数字,不是 benchmark —— 用账本测你自己的。如果召回有用率长期低于约 60%,就调小(更少条数、更短摘要)或直接关掉记忆。 上了云端之后,账本按库独立记账:本地库、云端库各算各的,跨设备看同一份统计。

🛡️ 先审核,再入库

一个「什么都自动吞进去」的记忆系统,迟早会把错误事实当成真相召回。memory-eternal 默认先审后入:

  • 新卡先进入待审队列,人工批准后才进主库;
  • 在 Web、终端 TUI 或 CLI 里批准 / 驳回 / 批量处理;
  • 每次状态变更追加到不可篡改的审计日志(谁 / 什么 / 何时 / 为什么)—— 由 SQLite 层强制,而不是靠约定;
  • Agent 可以读取和提议,但不能批准自己写的卡;
  • Agent 也可以提交修改:已批准卡的副本进待审队列并标注「✏️ 修改原卡:…」;批准 = 用副本覆盖原卡,驳回 = 原卡一字不动;
  • 删除的卡进回收站(默认保留 30 天)。

云端同样是这条闸门:换到云端库只换了数据源,没换规则 —— 云端库里的待审卡一样要人批准。

⭐ 核心记忆

不是所有内容都该每次注入上下文。核心记忆是一组必须每次遵守的偏好与硬约束:

  • 任意已批准卡片都可以在阅读器或卡片列表里提升为核心记忆;
  • 自动沉淀只会在用户明确要求长期偏好 / 硬约束时建议核心,且 core 候选一律待审;
  • 已批准的核心卡每次会话直接注入 systemPrompt,不依赖 memory_recall 调用;
  • 在「设置 → 记忆 → 核心记忆」里可配置条数上限和字符预算;
  • 知识星图里核心节点显示为橙色菱形 + ★;
  • 不要把密钥 / Token 的值写进核心卡,只保存凭证目录的引用。

🧩 宿主支持(一份库,谁都能用)

同一份 SQLite 库,下面这些宿主都能读写;写入一律进待审队列,审核在 DSH / Web 面板里做(与宿主是谁无关)。

15 个宿主,一张表看全 · ✅ 一键挂载 · ⚠️ 有条件 · ➖ 手填一条 · ❌ 不提供 MCP 配置

🌍 国际主流

宿主类型配置位置挂载
DeepSeek Harness插件(内嵌面板)~/.dsh/mcp-servers.json✅ 装插件即挂
Claude CodeCLI / IDE 插件~/.claude.json✅ connect claude
Codex CLI / DesktopCLI~/.codex/config.toml✅ connect codex
CursorIDE~/.cursor/mcp.json✅ connect cursor
WindsurfIDE~/.codeium/windsurf/mcp_config.json✅ 面板点一下
ClineVS Code 插件~/.cline/data/settings/cline_mcp_settings.json✅ 面板点一下
Gemini CLICLI(Google)~/.gemini/settings.json → mcpServers✅ 面板点一下
Antigravity桌面 IDE(Google)~/.gemini/config/mcp_config.json → mcpServers✅ 面板点一下
OpenClaw网关(JSON5)~/.openclaw/openclaw.json → mcp.servers✅ 含注释时拒绝改写
Hermes AgentCLI(YAML)~/.hermes/config.yaml → mcp_servers✅ 只换自己那块
VS Code CopilotIDEportable 的 mcpServers➖ 手填
Gemini 桌面应用 / 网页版聊天客户端不提供 MCP 配置❌ 接不了(Google 侧桌面形态用 Antigravity)

🇨🇳 国内主流

宿主类型配置位置挂载
MengBot机器人平台应用内「设置 → MCP 服务器」/项目 .mcp.json⚠️ 给了 MEMORY_HOST_MENGBOT_PROJECT 才写项目文件
Qwen CodeCLI(阿里,Gemini CLI 同源)~/.qwen/settings.json → mcpServers✅ 面板点一下
Kimi CLICLI(月之暗面)~/.kimi/mcp.json✅ 面板点一下
GrokBot桌面客户端~/.grokbot/mcp.json / %APPDATA%\GrokBot\mcp.json✅ 面板点一下(官方未公开格式,按约定探测)
智谱清言 / ZhipuAI桌面 / Web应用内添加➖ 只探测,手填
WorkBuddy桌面客户端应用内添加➖ 只探测,手填
Cherry Studio桌面客户端应用内「设置 → MCP 服务器」➖ 无外部配置文件

☁️ 不用装进程

通道用法
云端 bot / 远程 agentPOST /memory-eternal/api/mcp(Streamable HTTP,云端带 Bearer me_…)
终端 TUInpx -y -p memory-eternal dsh-memory tui —— 实时队列、全选、批量批/驳、长文读卡
Web 面板dsh-memory open → http://127.0.0.1:7999:独立部署,审核 / 检索 / 备份

一次投影多处:dsh-memory mcp mount --host gemini,qwen,kimi(--host all 全挂)。字段名、示例与坑见 docs/INTEGRATIONS.md;Orca 启动器见 orca-plugin,编辑器扩展见 cursor-extension。

MCP 对外就是标准 stdio server,5 个工具:memory_recall / memory_capture / memory_stats / memory_audit_list / memory_revise。没列到的客户端按上面那行 stdio 配置写即可。

我们不是这里最大的。 Mem0 有 6.9 万星和成熟团队,我们做的不一样的是写入路径: 人审闸门、物理三库分离、可指认的审计链,外加一本能自己核对"召回到底值不值"的记忆账本 —— 这些在表 1 的「治理」列里体现,而不是靠宣传。

在你自己的库上复跑:

node scripts/bench-search.mjs --rebuild   # 重建耗时 + p50/p95/max 延迟
node scripts/bench-recall.mjs             # 自建金标题 R@5 / Top1
dsh-memory ledger --days 30 --json        # 召回注入 / 沉淀调用 / 有用率
我们实测的基线(2026-11-12,2,943 张卡)数值
金标 109 题 R@5(内置 / bge-m3)96.3% / 99.1%
金标 109 题 Top1(内置 / bge-m3)86.2% / 89.9%
改写题 10 条 R@5(内置 / bge-m3)40% / 70%
LongMemEval-S 500 题 R@5(内置 / bge-m3)95.4% / 97.2%
召回延迟(词法 / 语义)约 7 ms / 81 ms
召回模型调用(内置语义)0

检索分 ≠ QA 分。表 2 我们两行是 检索 R@5;Mem0 的 94.4 是它自报的 LongMemEval QA(且是托管平台口径),两列不混比。

🔍 语义召回(默认内置,无需装模型)

新装默认就是内置语义:零安装、零网络、零费用,同义扩展兜底,开箱即用。三种部署方式:

方式说明
内置语义(默认)零依赖;自建集 R@5 96.3%,改写题 40%
本地 Ollama(推荐升级)bge-m3 向量;R@5 99.1%,改写题 70%,延迟约 100ms(含冷启动;热态查询嵌入实测 28–35 ms)
在线 APIOpenAI 兼容端点,按量计费

首次打开记忆库会走三步引导,并默认全开:记忆核心 / 自动沉淀 / 自动召回 / 核心记忆注入 / 工作记忆 / 内置语义。 设置页「语义召回」右上角可「🧭 引导」重新查看。细节见 docs/EMBEDDINGS.md。

🎨 皮肤与界面

五套皮肤,设置 → 通用 → 主题皮肤一键切换;选择会本地保存,刷新后保持。

五种主题皮肤:默认暗色、波普、明亮、生化危机、蜘蛛侠

皮肤风格
默认暗色深色底 + 琥珀强调,长时间阅读不刺眼
波普 Pop黄底黑框、硬阴影、半调与粗黑标题
明亮 Light暖纸面 + 衬线标题,适合白天
生化危机Umbrella 实验室、毒绿扫描线、B.O.W. 头图与巨爪
蜘蛛侠红蓝漫画、蛛网、半调、横版动作头图与悬吊挂件

知识卡:蜘蛛侠皮肤 知识星图:蜘蛛侠皮肤

▲ 知识卡 · 知识星图 —— 在线 Demo

🏗 架构:一个库、一道闸门、两条读取路径

flowchart TB
  subgraph IF["接入层"]
    UI["DSH Web UI<br/>记忆库 · 星图 · 审核中心 · 设置"]
    MCPC["MCP 客户端<br/>Claude Code · Codex · Cursor · OpenClaw"]
    CLI["CLI / TUI<br/>dsh-memory"]
    CLOUDC["云端客户端<br/>换库 / 上传 / 下载"]
  end
  subgraph RT["插件运行时(宿主 Node 进程)"]
    HOST["index.js<br/>事件订阅 · 配置 · systemPrompt 注入"]
    API["lib/api.js<br/>HTTP API · SSE · CSRF · 审核接口"]
    CAP["capture.js<br/>采集 → 蒸馏 → 降级原文卡"]
    IDX["search-index.js<br/>清洗 · 同义扩展 · FTS5 BM25"]
    EMB["embeddings.js<br/>向量 · 覆盖率门控 · 融合"]
    VAULT["vault.js<br/>读写 · 审核 · 审计 · 回收站"]
    MCPL["mcp.js + hooks<br/>工具注册 · 会话事件"]
  end
  subgraph DB["本地存储(SQLite WAL + 文件)"]
    CARDS[("cards<br/>仅 approved")]
    QUAR[("quarantine<br/>pending / rejected")]
    FTS[("cards_fts<br/>FTS5 索引")]
    VEC[("card_vec<br/>可选向量")]
    LOG[("audit_log · ledger · revisions")]
    MD["Markdown 镜像 + 每日备份"]
  end
  subgraph EX["可选外部服务"]
    LLM["蒸馏 LLM<br/>宿主 provider"]
    OLL["Ollama :7997<br/>或任意 OpenAI 兼容 embedding"]
  end
  subgraph SV["云端实例(memory-eternal-cloud,可选)"]
    TENANT["resolveTenant()<br/>一个 owner 一个独立库"]
    CV[("cloud-vaults/owner/<br/>memory-eternal.db")]
  end

  UI --> API
  MCPC --> MCPL
  CLI --> VAULT
  CLOUDC --> API
  HOST --> CAP
  CAP --> LLM
  CAP --> VAULT
  VAULT --> CARDS
  VAULT --> QUAR
  VAULT --> LOG
  QUAR -->|人工批准| CARDS
  CARDS --> FTS
  CARDS --> VEC
  IDX --> FTS
  EMB --> VEC
  EMB --> OLL
  HOST -->|systemPrompt / memory_recall| UI
  VAULT --> MD
  API -->|Bearer 令牌| TENANT
  TENANT --> CV

这张图之所以成立,是因为三条不变量写在代码里,不是写在文档里:

不变量由什么保证
主库物理上只存 approved两张物理表;所有读取路径只查主库
Agent 永远不能批准自己的记忆Agent 只能写进隔离区;批准 / 驳回是 UI / TUI / CLI 里的人工动作
召回零模型调用FTS5 + BM25;LLM 只在沉淀时运行

云端只加了一条边:API → resolveTenant() → 该 owner 自己的库。租户之间没有共享表,串不了数据。

🔁 一次会话里,到底发生了什么

宿主的 agent 不是「读写一个文件夹」,而是走一条有预算、有闸门、可降级的链路:

#时刻谁在动具体动作阻塞对话吗
1会话建立index.js往 systemPrompt 装配若干段:核心记忆(order 120,≤6 张 / ≤2000 字)、当前会话草稿、自动召回规则段(order 600)、新闻摘要(可选)。核心记忆每 5 秒重算一次,内容没变就不重建否
2你提问宿主 agent正常推理。用不用记忆由它自己决定 —— 规则段只是告诉它「什么时候该查」—
3agent 主动召回memory_recall 工具进程内直调 vault.search(),不经过 HTTP 端口;默认 5 条、每条摘要 130 字,工具超时 20s是(仅这一步)
4作答宿主 agent召回结果就是一段普通工具输出,和读文件没区别—
5轮次结束agent/turn-stopping会话事件入队 → 按字符上限截尾 → 连续轮合并(几轮攒一次 LLM 调用,而不是每轮一次)否(serial 事件里刻意不 await LLM,避免拖慢收尾)
6蒸馏成卡宿主 LLM(ctx.get('llm'))一段对话 → 一张卡;不足 captureMinChars=120 字跳过;同会话 60s 冷却;输出上限 max_tokens=4000否(后台任务)
7去重判定pickNeighbors()只取最相关 8 张已有卡(DEDUP_NEIGHBORS)喂给模型,让它选「新建」还是 append_to 追加(近重阈值 0.62)否
8落库vault.js写进 quarantine(status=pending),主库一动不动否
9人工审核你审核中心批准 → 进 cards → 建 FTS5 索引(5 分钟对账)+ 需要时补向量(batch 16)—

一句话概括分工:agent 负责「提议」和「按需取用」,永远不决定什么能进主库。

📥📤 两条读取路径

「两条」指的是上下文成本完全不同的两种读法,别混为一谈:

推送(push):systemPrompt 注入拉取(pull):memory_recall 工具
谁触发插件自动,每轮都带agent 自己决定
带什么核心记忆(≤6 张 / ≤2000 字)+ 规则段 + 会话草稿命中 Top-N 卡片的标题 / 路径 / 摘要
预算coreMemoryLimit / coreMemoryMaxChars 硬上限recallLimit(默认 5,上限 20)× recallSummaryLen(默认 130 字)
随卡片数增长吗不增长(上限写死)不增长(条数与字数写死)
典型用途「不要做的事」「我的偏好」这类每次都必须遵守的约束查历史决策、踩坑记录、项目背景

需要看正文时才有第三条路:recallIncludeBody=true 会给每条命中追加 ≤800 字正文摘录 —— 默认关闭,就是怕把上下文撑大。

💰 谁在什么时候调用模型

时机调谁同步/异步失败会怎样
召回(默认)不调模型:FTS5 + BM25 全在 SQLite 里同步索引异常 → 全表兜底扫描
召回(开了语义)Ollama bge-m3 算 1 次查询向量同步,超时 15s60s 失败冷却 → 自动退回纯词法
召回(开了 rerank)你配的重排模型,只看 Top-30 候选同步,超时 20s保留原排序
每轮沉淀宿主 LLM 蒸馏(喂 8 张近邻卡)异步存原文卡(零蒸馏成本),仍要人审
建向量缓存Ollama,batch 16异步 backfill覆盖率不到 30% 就不启用语义路

🚀 卡片变多了,会变慢 / 变蠢吗?

这是最该被量化的担心,所以给数字,不给形容词。下面这张表由仓库自带脚本在临时合成库上跑出来(Windows / node v24.19.0 / 2026-11-18;每卡正文约 1600 字,dim=768):

卡片数FTS/BM25向量打分端到端 search()向量读入单次召回注入字符全库正文
2000.31 ms1.2 ms28 ms0.6 MB283 字0.32 M 字
1 0000.90 ms11.4 ms38 ms2.9 MB286 字1.60 M 字
2 0001.61 ms25.8 ms43 ms5.9 MB304 字3.21 M 字
5 0003.55 ms55.5 ms71 ms14.6 MB307 字8.01 M 字

(同一台机器上多跑几次,耗时会有 ±20% 左右的抖动 —— 量级与曲线形状才是有意义的部分,绝对值不必抠。)

自己复现(只写系统临时目录,不碰你的库):

node scripts/bench-capacity.mjs                  # 默认 200,1000,2000,5000
node scripts/bench-capacity.mjs 500,5000,20000   # 自定义规模

容量用 bench-capacity.mjs(自带合成库,测耗时与注入量);质量另用 bench-recall.mjs(读 --vault 快照 + 金标集,测 R@5 / MRR / Top1)。两个脚本故意分开,别拿容量数字冒充质量结论。

结论一:上下文成本与卡片数无关。 卡片从 50 张涨到 5 000 张,单次召回注入仍是 300 字上下 —— 因为 limit=5 与每条 130 字是硬截断。作为对照,把全库正文直接塞进去是 8.1 百万字,差 4 个数量级。agent 看到的永远是「5 条摘要」,不是「一座图书馆」。

结论二:检索耗时增长远慢于直觉。 5 000 张卡时词法召回 3.6 ms、端到端 71 ms。词法是倒排索引 + 候选池固定 80 条(max(limit×4, 80)),不随库线性膨胀。

结论三:唯一真正线性增长的是向量打分。 没有 ANN 索引,就是「读全表 BLOB + 逐个 cosine」:5 000 张要读 14.6 MB、约 55 ms。这张表里增长最快的就是它。

于是可以给出可执行的容量口径:

库规模建议理由
≤ 5 千张全开:词法 + 语义 + rerank向量打分数十毫秒,可无感
5 千 – 1 万词法 + rerank 常开;语义改成按需9 752 张实测:cosine 124 ms / 读 38 MB,端到端约 300 ms
> 1 万词法 + rerank;语义只在分库后开分库是唯一能真正压住线性项的手段

🧪 真实库实测:9 752 张卡的一次索引事故

比合成数据更值得读的,是一次真实排障。

库里 9 752 张已批准卡,cards_fts 却只有 50 行 —— 索引在某次批量导入之后就没再补齐,而召回在索引缺失时会静默退到「全表扫描 + 子串计数」兜底。于是同一条查询给出两种答案:

查询索引只剩 50 行时(兜底扫描)重建索引后(FTS5 + BM25)
审核 红线 批准「DSH 记忆库巡检现状…」无关「审核中心 #27 可就地查看正文 + 批准/驳回」✓
Ollama 语义召回「autokill-purge 模型清单…」无关「本地 Embedding 服务(Ollama/bge-m3)离线部署」✓
npm 发布 403 账号冷却「0.47.0 发版前收尾…」勉强相关「v0.49.13 发布记录与 npm 冷却问题」✓

这就是「agent 变蠢」的真实长相:不是卡片多,是索引没了。功能不报错、搜索不报错,只是答案变得像随机抽卡。

指标(真库 9 752 张)实测
词法召回(重建后)2.5 – 4.3 ms
重建索引3.5 – 9.8 s(一次性,9 752 行)
全表 cosine(灌满 9 752 条 dim=1024 向量,读 38.1 MB)124 ms
端到端召回(开语义,含 1 次 Ollama 查询嵌入)250 – 314 ms
单次召回注入上下文约 1 350 字(5 条 × 标题 + 路径 + 130 字摘要),与卡片总数无关

代价结构一目了然:词法几乎免费,语义每万张约 0.3 秒。

Ollama 的账另外算:本机 bge-m3 热态一次查询嵌入实测 28–35 ms(dim=1024),但它只在你开启语义召回时、每次召回调 一次,且与库大小无关 —— 慢的是「把库读一遍算相似度」,不是模型本身。冷启动另有一次性开销(模型首次加载)。

至于「会不会变蠢」:变蠢的机制从来不是「卡多」,而是坏卡挤进那 5 个名额。所以真正的防线是闸门而不是容量:

  • 只有人批准的卡才进主库(quarantine 物理隔离 232 张待审也影响不到召回);
  • 沉淀时先做近重判定(阈值 0.62),重复内容会被 append_to 合并而不是堆成新卡;
  • 召回结果可以点「有用 / 没用」,反馈直接参与排序(有用×2 − 没用的×2);
  • 过时卡归档后物理上不参与召回;
  • 判断标准写在账本里:有用率长期低于 60%,就调小 recallLimit / recallSummaryLen,或者直接关掉记忆 —— 这是插件自己给出的退场条件。

🧰 运维:索引和向量什么时候要手动补

索引只在写卡那一刻逐条维护(indexCardById / unindexCard)。批量导入、Markdown 迁移、跨版本升级进来的存量卡不会自动补 —— 这是当前实现的已知缺口,所以要自己查一次:

node scripts/reindex-fts.mjs          # 只报告:已批准卡数 vs 已索引行数
node scripts/reindex-fts.mjs --force  # 重建(只写 cards_fts / _fts_rows,不动卡)
症状判断依据处理
命中有「随机抽卡」感cards_fts 行数 < cards 行数上面两行命令
语义召回像没开card_vec 覆盖率 < 30%,门控会静默关掉面板 → 语义召回 → 补向量(batch 16)
越用越慢索引缺失时每次召回都走全表扫描同上,先重建索引

反过来的情况也要知道:索引建全、向量灌满之后,召回会从「全表兜底」切到「FTS + 语义融合」,单次耗时从几毫秒升到约 300 ms(1 万张、dim=1024)。这是花了时间换准确度,不是变慢的 bug —— 觉得不划算就把语义关掉,词法路径照常。

🧯 任意一环挂了会怎样

失败点自动行为你看到的现象
Ollama 没启动 / 端口不通60s 失败冷却,退回纯词法召回照常,只是同义词弱一些
向量覆盖率 < 30%不启用语义路同上(避免"半库向量"污染排序)
rerank 未配置 / 超时保留原排序无感
宿主 LLM 不可用存原文卡,标记降级卡片变「原始对话」,仍要人审
FTS 索引异常全表兜底扫描召回变慢但仍能搜到
库文件损坏每日备份 + auto-restore启动时自动回滚到最近可用备份

🔗 MEM Pair:两个记忆库互配对、互传卡(v0.49.10)

本机常常同时跑着多个 memory-eternal:运营库(7999)、隔离运营的 mem-purge(7989)、云端实例。 它们各有独立 SQLite,不能共享一个库;但你需要让它们互相喂料(运营口径 → purge,purge 的清理结论 → 运营库)。

MEM Pair 就是这套「显式、可审计、默认不打扰」的通道:

阶段怎么做判定信号
发现局域网 UDP 广播(默认 7990),或直接填 host:port面板列出对方名字 + 匹配码 + 指纹
首次配对一端发起 → 另一端面板弹窗确认(显示 6 位握手码,两边肉眼核对)双方配对表里都出现对方
之后再连只需要匹配码:对方认得这个码且指纹没变 → 直接建立,不再弹窗面板显示「已配对 → 对方」
指纹变了对方重装 / 可能被冒充 → 回到人工确认,弹窗标红必须重新点确认
传数据「上传」(本库 → 对方)/「下载」(对方 → 本库),一律进对方待审队列计数:sent / written / failed
dsh-memory peer code                                  # 我的匹配码
dsh-memory peer pair 192.168.1.20:7989                # 首次配对(对方要确认)
dsh-memory peer connect 7K2M-Q9FA --host 192.168.1.20 --port 7989   # 之后只凭码重连
dsh-memory peer upload   --to 7K2M-Q9FA               # 推卡过去(进对方待审)
dsh-memory peer download --from 7K2M-Q9FA             # 拉卡回来(进本库待审)

安全口径:共享密钥由两端各自算出(一次性 ephemeral 派生,长期密钥永不上网);每个请求带 HMAC 签名 + ±5 分钟时间窗 + nonce 去重;对方推来的卡只能进待审,不会直接污染已审库。

🔌 Agent MCP 挂载(一份标准,六种宿主)

作为 DSH 插件安装时,默认就把 MCP 挂到 DSH 自己(~/.dsh/mcp-servers.json),装好即用; Claude Code / Codex / Cursor / Windsurf 这些「你另开的宿主」必须手动挂 —— 否则同一个仓库里 被多个 agent 读到不同库,沉淀与召回就会串味。

所有宿主共用同一个标准(一处声明 → 各自渲染):server 名固定 memory-eternal、只用 stdio、 命令写绝对路径、参数走 env、幂等写入且只增删自己那一条、写后回读校验、能检测「指向旧包路径」的漂移。

dsh-memory mcp status                                   # 状态 + 各宿主矩阵
dsh-memory mcp mount --vault ~/.dsh/memory-vault        # 挂本机库(默认只写 DSH)
dsh-memory mcp mount --url http://127.0.0.1:7989 --host dsh,claude   # 一次投影多个宿主
dsh-memory mcp mount --vault <库> --host all            # 所有已安装宿主
dsh-memory mcp unmount                                  # 从所有已挂载宿主摘掉(幂等)

面板:设置 → 🧪 实验性 → 🔌 Agent MCP 挂载(v0.49.10 起是列表点击式)

● 2 / 6 已挂载 → 本机默认库                       [刷新] [自检]
  ⬤ 装成 DSH 插件时自动挂载   默认开启,装好即用…

挂哪个库(点一行选中)
  ● 本机默认库   已选中        ○ mem-purge  9DUW-QPVM       ○ 云端  5EZK-RWM5

挂到哪些宿主(点哪行就挂/摘哪行)          [全部挂载] [全部卸载]
  ● DeepSeek Harness (DSH)  已挂载   …\.dsh\mcp-servers.json        卸载
  ○ Claude Code             未挂载   …\.claude.json                 挂载
  ○ Claude 项目级 .mcp.json  未挂载   …\.mcp.json                   挂载
                展开其余 3 个宿主
  • 默认只显示 3 个宿主,多出来的收进「展开其余 N 个宿主」;
  • 每行状态一眼可辨:实心绿=已挂载 / 空心=未挂载 / 虚线圈=未安装(未安装置灰不可点);
  • 「自检」按钮会真的拉起一次 MCP 进程做 initialize 握手,把 ok / 耗时 / 启动命令 / stderr 直接显示出来 —— Windows 上"路径不对、宿主识别不了"当场就能看到原因;
  • Windows / Electron 兼容:条目里的 node 不再取 process.execPath(在 DSH 这类 Electron 宿主里那是宿主自己的 exe),而是走 PATH 解析 + 校验存在性;写盘前统一反斜杠绝对路径,脚本不存在直接拒绝写入(不留死条目);
  • 想彻底关掉自动挂载:配置 mcpAutoMount: false,或环境变量 MEMORY_MCP_AUTOMOUNT=0。

🧷 多实例并行:端口、库文件名、vault 目录

同一台机跑多个 memory-eternal(比如运营库 + 某个项目的隔离库)时,三个维度都能分开:

维度怎么设默认
端口dsh-memory open --port 7989 / serve --port 7989 / 环境变量 MEMORY_WEB_PORT=7989 / 配置项 webPort7999
库文件名环境变量 MEMORY_DB_FILE=mem-purge.dbmemory-eternal.db
vault 目录--vault <dir> / 配置项 vaultDir / vaultProfiles 多库切换~/.dsh/memory-vault
# 第二个实例:端口 7989、库文件 mem-purge.db、独立 vault
DSH_HOME=~/.dsh/memory-vault-mem-purge \
MEMORY_WEB_PORT=7989 \
MEMORY_DB_FILE=mem-purge.db \
node $(dirname $(which dsh-memory))/../lib/web.js --port 7989 --vault ~/.dsh/memory-vault-mem-purge

两个安全口径:

  • 库文件名只接受纯文件名(字母数字 . _ -,必须以 .db 结尾),带路径分隔符一律退回默认名 —— 不会因为一个环境变量把库写到别处;
  • 设了自定义名、但该目录里已经是 memory-eternal.db 的库 → 继续用标准名,避免"改了个环境变量结果打开空库、以为数据丢了"。

📚 文档与链接

💬 交流群

遇到问题、想提需求、或者想聊聊 DSH 插件开发 —— 欢迎进群:

QQ 交流群微信交流群
QQ 群二维码微信群二维码

如果这个插件帮你省了时间,可以请作者喝杯咖啡(微信 / 支付宝任选其一):

微信收款码微信赞赏码支付宝
微信收款码微信赞赏码支付宝收款码

打赏完全自愿,不影响任何功能;插件本体始终开源免费(MIT)。详见 SPONSOR.md。

📄 License

MIT —— 随便用、随便自托管、随便二次开发。

🖋 作者语录

「大爱」二字,是全篇最大的反讽。面板左栏底部同步轮播。

落魄谷中寒风吹,春秋蝉鸣少年归。
荡魂山处石人泪,定仙游走魔向北。
逆流河上万仙退,爱情不敌坚持泪。
宿命天成命中败,仙尊悔而我不悔。

早岁已知世事艰,仍许飞鸿荡云间。

男儿不展凌云志,空负天生八尺躯。

天河一挂淘龙鱼,逆天独行顾八荒。
今朝暂且展翼去,明朝飞仙笞凤凰!

——《蛊真人》· 大爱仙尊

🌟 贡献者

感谢每一位让记忆核心更好用的人。

贡献者贡献
@aloneangel45发现并修复 #54 —— tools 服务晚挂载时 memory_recall / memory_note 从未注册(#58)
@EternalNight996作者与维护者

有想落地的修复?欢迎开 issue 或 PR —— 每个被合并的贡献都会出现在这里。