🧠 memory-eternal — 给 AI 装「第二大脑」

Memory Atlas · 本地优先的 AI 记忆库
_{自动沉淀 · 先审后入 · 知识星图 · 全 Agent 共享}

简体中文（默认） · English

_{▲ Memory Atlas · 在线 Demo（示例数据）· 点此打开}

对话结束自动沉淀成知识卡，跨会话不失忆；召回只取相关小块，省 token 少噪音。
全自研、零第三方记忆框架、不改 DSH 源码；一个记忆库所有 Agent 共享，SQLite 持久存储，零外部依赖。

⭐ 如果它帮你少解释了一遍上下文，点个 Star 就是最大的支持
_{DSH 一条命令：dsh plugin --profile desktop add memory-eternal}

🌐 在线体验 · 打开记忆库 Demo _{（示例数据，不用安装）}

_{▲ 真实运行截图：待审判词 · 知识星图 · 读卡器}

✨ 它到底解决什么问题

• 看得见：知识卡 / 图谱 / 健康概览 / 沉淀日志，四层可视化；
• 控得住：审核模式（全部人工 / 仅高风险）、去重与矛盾扫描、批量合并、每日备份与一键恢复；
• 带得走：知识库是本地 Markdown + SQLite，可 git 管理、可导出，不锁在插件里。

🚀 五分钟上手

🟦 DeepSeek Harness（DSH）—— 重点

装（官方桌面版走插件市场，dsh web 用一条 CLI）：

# ① 官方 DeepSeek Harness 桌面版（推荐）：设置 → 插件 → 搜 memory-eternal 安装
#    等价 CLI（该壳的 profile 名就是 desktop）：
dsh plugin --profile desktop add memory-eternal

# ② dsh web（浏览器端）：
dsh plugin --profile web add memory-eternal

# 或在 profile（pnpm workspace）里直接更新。注意用 pnpm，npm install 会报 EUNSUPPORTEDPROTOCOL
cd ~/.dsh/profiles/web && pnpm add memory-eternal@latest

# 刚发新版时 @latest 可能被 pnpm 的最小发布年龄门槛/元数据缓存挡住（静默停在旧版）：
# 直接指定版本号最快，pnpm 会自动把它加进 workspace 的 minimumReleaseAgeExclude
cd ~/.dsh/profiles/web && pnpm add [email protected]

# 验版本（应等于上面装的号），然后重启对应宿主生效
node -e "console.log(require('memory-eternal/package.json').version)"

🖥️ 桌面版支持策略（先看这条）

• 优先、且只保证支持官方 DeepSeek Harness 桌面版（官方 Electron 发行版，profile 名 desktop）。v0.9.4 → v0.9.6 三轮修复全部围绕它：0.1.7 设置服务换血、schemastery 3.18.4 的 volatile 活引用、以及窗口标题栏避让（data-windows-titlebar，避免全屏浮层压住最小化/最大化/关闭）。
• 作者自研的 dsh-desktop（dsh-desktop-shell / dsh-ui-* / dsh-plugin-marketplace 那一套）已停止维护，不再作为支持目标 —— 官方桌面版已覆盖同样能力，继续维护两条壳只会分裂兼容性。注意它的 profile 依赖里还钉着已从 npm 撤下的 [email protected]，会让 pnpm install 直接失败；建议迁到官方桌面版，并从 profile 里删掉这套依赖。
• 兼容矩阵（均已实测）：官方桌面版 desktop profile（schemastery 3.18.4）＋ dsh web 的 web profile（schemastery 3.18.1），两条路径共用同一份代码。

重启宿主后，三样东西立即生效：

入口：侧边栏底部「记忆」按钮 → 记忆库（左栏含 知识卡 / 知识图谱 / 用量 / 审核中心 / 回收中心 / 记忆配置）；「DSH 设置 → 记忆」= 纯配置页。

界面语言：全套 UI 中英双语，跟随 DSH 设置 → 语言 实时切换（含知识卡 / 知识图谱 / 审核中心 / 新建卡模板）；浏览器直接访问 web 时跟随浏览器语言。

改配置：记忆库左栏「记忆配置」（或 DSH 设置 → 记忆）→ DSH 记忆配置 / 成本控制 / 自动审核配置 / 服务自管理，点「保存配置」即写入。autoWebMode/watchdogAutoSpawn 的改动需重启 DSH 生效；注意已常驻的 watchdog 不会被配置改动自动停掉，要停止或换新版请执行 dsh-memory stop / dsh-memory restart（见「服务自管理」）。

🟨 Claude Code

npm i -g memory-eternal     # 装 CLI + MCP（写 ~/.claude.json mcpServers.memory）
dsh-memory connect claude       # 写 ~/.claude/settings.json 的 SessionEnd hook → 会话结束自动沉淀

装完即用：会话里说「recall 一下数据库选型」→ 自动检索记忆；会话结束 → 自动沉淀进统一 ~/.dsh/memory-vault（新卡 pending 待审核）。

🟧 Codex CLI / Cursor

npm i -g memory-eternal     # 装完自动写 Codex config.toml / Cursor mcp.json 的 mcpServers.memory
dsh-memory connect codex        # 写用户级 ~/.codex/hooks.json 的 Stop hook → 会话结束自动沉淀（含 Codex Desktop）
dsh-memory connect cursor       # 写 ~/.cursor/hooks.json 的 stop/sessionEnd hook → 自动沉淀

重启工具 → MCP 已在列表，会话里直接：用 memory_recall 查一下项目历史决策；会话结束自动沉淀进统一 ~/.dsh/memory-vault（新卡 pending 待审核）。

三种 agent 同一套库：全部写入 ~/.dsh/memory-vault，每卡 submittedBy 区分作者（DeepSeek Harness / claude-code / codex / cursor），主库只显已审核、审核中心管新卡。

原生插件（可选，平台 Marketplace）：仓库含 .claude-plugin / .codex-plugin / .cursor-plugin 清单，可 claude /plugin marketplace add EternalNight996/memory-eternal + /plugin install、codex plugin marketplace add EternalNight996/memory-eternal + codex plugin add、Cursor Settings→Plugins。connect 走用户级 hooks.json（更稳，不依赖 Marketplace 审核；Codex Desktop 也走这条）。

只保留本插件（卸载其它记忆插件，如 agentmemory）：dsh-memory 只写自己的键（mcpServers.memory / 含 capture.mjs 的 hooks），不依赖、也不冲突任何其它记忆插件。卸载其它插件需在其自身配置层删除对应条目（如 Codex 的 [marketplaces.*] 与 hooks.state.*、其 hooks.json 事件、~/.agentmemory 数据目录）。

🟩 浏览器（不依赖任何 Agent）

dsh-memory open    # 起 web + 开浏览器（默认 http://127.0.0.1:7999）

统计 / 搜索 / 知识卡（增删改合并导入导出）/ 知识图谱，全在此。与 DSH 内嵌页同一份 UI，数据同步。

zcode（智谱）：暂无原生 MCP，经社区 zcode-open-bridge 转 MCP 或用 CLI。

📖 命令速查

dsh-memory recall "数据库选型"       # 检索
dsh-memory capture "重要结论..."     # 手动沉淀（- 读 stdin）
dsh-memory sweep ~/.claude/projects  # 挖掘已有会话记录
dsh-memory setup [--dry-run]         # 重跑/预览自动挂载（幂等）
dsh-memory connect <claude|codex|cursor>  # 写会话结束自动沉淀 hook（用户级 hooks.json，含 Codex Desktop）
dsh-memory mcp                       # MCP stdio（挂任意 MCP 客户端）
dsh-memory serve [--port 7999]       # 前台跑 web
dsh-memory open                      # ensure web 存活 + 开浏览器
dsh-memory watchdog [--port 7799]    # 看门狗保活 web（独立进程）
dsh-memory status [--json]           # 看常驻 watchdog：pid / 端口 / 版本 / 是否存活
                                     # 以及**端口上真正在服务的版本**（锁里的版本号只是 watchdog 自述）
dsh-memory stop [--port 7799]        # 停止常驻 watchdog（配置改动不会自动停；连它拉起的 web 一起停）
                                     # 停完会再问一次端口占用者，仍被占着就明确告警
dsh-memory restart [--port 7799]     # 停止并重起 watchdog（升级后换新版）
                                     # 按端口占用者兜底收掉锁里没登记的旧 web，起完自检端口上服务的版本
dsh-memory audit list [--status pending|rejected|approved|deleted|all] [--limit N] [--json]
                                     # 列出卡片；总数不受 --limit 影响，--limit 只限制显示条数（默认全部）
                                     # all = 审核队列（pending + rejected），不含 approved / deleted
dsh-memory audit approve <卡片路径...>              # 人工批量批准
dsh-memory audit reject <卡片路径...> --reason "..." # 人工批量驳回

单独装（不发 DSH）时 dsh-memory 命令来自 npm i -g。

⚙️ 服务自管理（白话）

三个概念，别搞混：

• web server 怎么保活（autoWebMode）→ init=DSH 启动时拉一次（默认）；interval=DSH 进程内定时探活自动拉起（0 额外内存）；manual=全手动只从 dsh-memory open 起。
• 看门狗进程（watchdogAutoSpawn，默认开）→ 一个独立 node 进程，DSH 退出了它也能拉起 web（约 +47 MB 内存）。只在要 7×24 保活时开。
• 版本漂移自愈（autoRestartOnDrift，默认开）→ 常驻 web 比 DSH 活得久：升级只换磁盘文件，端口上那个进程仍跑着启动时加载的旧代码（「启动 dsh 后运行中还是旧版本」就是这么来的）。开着它，DSH 激活时会问端口上真正服务的版本，与磁盘不一致就用新代码重启常驻实例；关掉则只告警，需要时在「插件信息」点重启常驻实例。
• 自动挂载 MCP（autoMcpSetup，默认关）→ 是否自动把 MCP 写进 Claude Code/Codex/Cursor 配置。关 = 不碰你本机配置文件，需要时手动 dsh-memory setup。

改这些：记忆库左栏「记忆配置」（或 DSH 设置 → 记忆）→ 表格里改，点「保存配置」；autoWebMode/watchdogAutoSpawn 需重启 DSH 生效。

⚠️ 同端口不会因配置改动而自动替换（#19）：看门狗是独立进程且故意不杀（多会话共用一个），所以
关闭 watchdogAutoSpawn 不会停掉已经在跑的那个，改 webCheckIntervalMs/webMaxRestart 也不会生效。
要停止 / 换新版请显式执行 dsh-memory stop [--port N] 与 dsh-memory restart [--port N]（stop 会连它拉起的 web 一起停，不留占端口的孤儿）；
dsh-memory status 会显示常驻实例的 pid、端口、启动时间与版本是否落后于本机安装的包，并单独报出端口上真正服务的版本
（锁文件里的版本号只是 watchdog 自述，端口上跑旧代码时它不会变）。

⚠️ 升级后请以「端口实际服务版本」为准（#23）：restart 现在不只信锁里登记的 web 子进程，
还会按端口占用者兜底清理（锁里没登记的旧 web 也会被识别并收掉，非本插件的进程只告警不动手），
并在起完之后自检「端口上服务的版本 = 本机版本」——对不上就以非 0 退出码报失败，不再打印「已启动」就完事。

✅ 「更新了却还是旧版本」现在有两条出路（#19/#23）：① 默认开的 autoRestartOnDrift 在 DSH 启动时
自动替换旧常驻实例；② 面板「插件信息」里发现版本漂移时给一个**🔄 重启常驻实例按钮（服务端即
dsh-memory restart --port N 的同一实现：收旧实例 → 抢锁 → 拉起新 web → 自检端口版本）。
注意「运行中」那一格指的是服务本页的进程**：独立 Web 页里就是常驻 web，DSH 设置页里是宿主 ——
面板会同时列出常驻实例的版本，两者不同时一眼能看出该重启谁。

MCP 是协议不是常驻服务：agent 开会话才 spawn，用完即退，没有「开机自启」一说。

三种部署强度

⚙️ 记忆配置（大白话）

所有配置都在 记忆库左栏「记忆配置」（或 DSH 设置 → 记忆）里改，点「保存配置」生效。下图就是配置页全貌（含插件信息 / Agent MCP 挂载状态 / 自动审核配置）：

一、最常用

多库（按项目隔离记忆）

配置里还有两个字段（写在 memory-eternal-config.json，或设置面板同步过来的共享配置）：

{
  "vaultProfiles": [{ "name": "work", "path": "D:/vaults/work" }],
  "activeVault": "work"
}

解析顺序：MEMORY_VAULT_DIR 环境变量 → activeVault 命中 vaultProfiles[].name 的 path → vaultDir → 默认 ~/.dsh/memory-vault。

v0.9.8 起，CLI / MCP / hooks / 独立 web / sweep 与 DSH 宿主共用同一套顺序：以前只有宿主认 activeVault，切库后终端与 hooks 仍往默认库写，记忆会被劈成两份。

说明：配置页目前还没有 vaultProfiles / activeVault 的可视化表单（要手工写配置文件），按 workspace 自动选库也还没做。

二、省钱包（重要）

三、服务怎么跑

🔑 密钥怎么放（secretHint 的用法）：把值留在本机凭据里（环境变量 / 密钥文件，权限收紧），
记忆库里只留一张目录卡（有哪些键、放在哪、干什么用、轮换状态），再用 secretHint 让 agent
每次会话都想到去查这张卡。为什么值不能入库：卡片 summary 就是正文开头，召回默认就带 130 字
（recallSummaryLen），值一入库就随每次相关召回进入模型上下文；/export、备份、多机同步也会带上。
dsh-memory setup 会在 Claude Code 里注册一个 PreToolUse 守卫：直接读
.credentials.yaml / .env / *-token 会被拒绝并指路到目录卡。

💰 想省钱：把「蒸馏知识卡」关掉、调低「蒸馏输出上限」、调高「召回相关性阈值」。

🎯 一键推荐配置（按场景点一下）

配置页顶部有 🟢 A 轻量省心 / 💰 B 极致省钱 / ⭐ C 高质量 三个按钮，点一下自动填好对应值，再点保存即可：

🔔 自动沉淀日志 & 异常提示

自动沉淀是后台静默管线：一旦坏了，以前只能表现为「卡不再增加」，看不出原因。v0.9.0 起它会自己说话。

• 自动沉淀日志：设置 → 记忆 → 用量/今日，最近 100 条运行轨迹：🚀 启动 / 👂 会话接入（用的事件接口 + 事件数） / ✅ 新建卡 / ➕ 追加更新 / ⏭ 跳过（原因） / ❌ 失败（原因）。
• 异常主动提示：出现失败即亮红——记忆库页面顶部红条，同时把「自动沉淀异常 + 原因」注入 Agent 上下文，Agent 会在回复第一句提醒你，不需要你自己去翻日志。
• 停滞兜底：本次运行至今一次收尾事件都没收到、且最近 20 分钟内持续有轮次开始（例如 DSH 改了事件名/作用域），5 分钟巡检记一条 warn —— 不再冒充红色「自动沉淀异常」，正在进行的长回合也不会被误判（一轮对话中途 inbox/claimed 会多次触发，收尾要等回合真的结束）。
• 接口自适应：自动识别 DSH 会话事件接口（ownEvents() → snapshotEvents() → events），DSH 升级换 API 不会再静默断掉。

🛡️ 审核中心 & 回收中心

新卡默认进审核中心（pending），由你确认后才入主库；驳回的进「已驳回」，可恢复或删除进回收站。命中免审条件（审核模式=全部免审 / 免审智能体 / 免审类型）的新卡直接入库；回收站软删卡 30 天内可恢复，超期自动永久删除。

v0.3.0 起：审核守卫下沉到数据库层。 所有写入路径（自动沉淀 / MCP / UI 新建 / 导入）强制经过 enforceAudit()，调用方无法绕过。setCardStatus() 是唯一审核操作入口，每次变更写入 audit_log 审计日志（who/what/when/why），不可篡改。

v0.10.0 起：升级为「两套存储」——未审核内容物理隔离。
cards（主库 / 正常区）物理上只存 approved；quarantine（隔离区 / 异常区）存 pending / rejected / deleted。
意义：召回、检索、知识图谱、去重池、导出这些读路径查主库即安全——不再依赖「每处 SQL 都记得写 WHERE status='approved'」。
（v0.9 审计实测漏过三处：去重池会把新知识追加进待审卡、readCard 可按 path 直读未审核正文、/card 接口无状态校验。）
审核流转 = 跨表搬家：批准 → 搬进主库，驳回/软删 → 搬进隔离区；搬家在一个事务里完成，更新记录与审计日志跟着走。
升级说明：首次启动会自动把存量非 approved 卡搬进隔离区（不删除任何内容，都在同一个 .db 文件里）。
若回滚到旧版本，审核队列会显示为空（旧代码看不到隔离区表），升级回来即恢复。

• 待审核 / 已驳回 双页签，按类型 / 日期 / 智能体筛选，全选后一键「批准 / 驳回 / 删除进回收站」。
• 审核规则在「记忆配置 → 自动审核配置」：审核模式（全部要审 / 全部免审）+ 免审智能体 + 免审类型 + 回收保留天数。
• Agent 不能代你审批（v0.9.1 起）：只要审核生效，插件就往 Agent 的上下文里注入红线——新卡只能停在「待审核」，并明确禁止调用 approve/reject 接口或任何等价方式绕过；判断权始终在你手里。

🥇 为什么审核系统更靠谱（对比其它记忆产品）

多数记忆产品（mem0 / Zep / agentmemory…）对话一结束就自动全量入库，好坏不论——噪音、错误事实、敏感内容一起进库，之后又被召回，污染上下文、放大幻觉。

memory-eternal 走人机协同审核，只让可信内容进主库：

🧬 为什么全自研

市面上记忆方案多，但大多依赖第三方框架 / 动不动起 MCP 服务 / 记忆锁私有库。本插件把骨架自己搭，零第三方运行时依赖，逻辑逐行可读：

与热门项目同向（总结→存储→按需召回），但定位不同：本地、自研、零依赖、可读可控。如果你已在用 mem0/Zep 等，也能把它当「本地持久记忆底座」叠加使用。

🛠 开发 / 测试

npm i
npm test        # 单元测试：vault 去重/检索/图谱 + capture 管线 + API 形状
npm run build   # 构建 lib/client.js（DSH 内嵌）+ web/app.js（独立 web bundle）

📄 README 是中英两份独立文件：README.md（简体中文，默认，npm / 插件市场展示这一份）
与 README.en.md（English）。两份标题层级一一对应，改一处要同步另一处（新增一节两边都加）。

🐞 反馈问题

插件左栏有 🐞 反馈异常 入口：填完问题描述后可以

• 在 GitHub 提交（已预填） —— 标题 / 正文 / 诊断信息 / bug 标签都填好，再点一次 Submit 即提交；
• 复制给 AI 的提示词 —— 粘进 AI 对话框，让它用 gh 查重后建 issue 并回报链接。

为什么不能「点一下自动提交」：GitHub 不允许匿名创建 issue；插件里内置 token 会被反编译提取；OAuth / 自建中转需要服务器。所以实现为「预填 + 一次点击」。
诊断信息会自动脱敏（home 目录 → ~，sk- / ghp_ / github_pat_ / api_key: 等 → ***），但公开提交前仍建议自己扫一眼。

如果你拿不到插件界面，也可以直接把下面这段贴给 AI（把「我的问题描述」换成你的问题即可）：

我在使用 memory-eternal（DeepSeek Harness 的记忆插件）时遇到了问题，请你帮我把这个问题提交到 GitHub。

仓库：https://github.com/EternalNight996/memory-eternal

请按这个流程做：

1. 先跑 `gh issue list --repo EternalNight996/memory-eternal --state open --limit 50`，看是否已有相同问题：
   - 已有 → 用 `gh issue comment <编号> --body-file <文件>` 补充现象，不要重复开新 issue；
   - 没有 → 继续第 2 步。
2. 把正文写成文件，然后 `gh issue create --repo EternalNight996/memory-eternal --title "[Bug] <一句话概括>" --body-file <文件>`；正文用这个结构：
   现象 / 复现步骤 / 期望行为 / 实际行为 / 环境（插件版本 / DSH 版本 / 操作系统 / Node）/ 诊断信息。
3. 如果 `gh` 没登录或不可用，不要尝试提交，改为输出一条「标题与正文都已预填」的 GitHub 新建 issue 链接给我，我自己点提交。
4. 提交成功后，把 issue 链接发给我。

注意：我的问题描述请原样照录，不要替我美化或省略细节；诊断信息原样放进「诊断信息」一节。

我的问题描述：
<在这里写你的问题>

诊断信息：
<把「反馈异常」弹窗里复制的诊断信息粘到这里>

环境自检（贴问题时附上更快定位）

dsh plugin list                      # 插件版本
node -v                              # Node 版本
curl http://127.0.0.1:7999/memory-eternal/api/web-info    # 独立 web 是否活着

📋 更新日志

发布规则（2026-09-30 起）：正式版一律三端同步发布 —— npm publish + GitHub Release + Gitee Release，并保证 vX.Y.Z tag 在三端一致。桌面版 profile 依赖 github:EternalNight996/memory-eternal、dsh web 走 npm 版本号，少任何一端都会出现「npm 上是新版、桌面版还是旧的」。统一入口：npm run release:dry（预演）→ npm run release（正式）。详见 PUBLISH.md。

版本撤回说明：v0.9.16 – v0.9.22 已全部撤回（问题期间版本：git tag 已删除、npm 已标记 deprecated，请使用 v0.9.23）。v0.9.14 已 deprecated（客户端渲染改动降低手感，已回退；其服务器侧算法优化并入 v0.9.15，渲染与 v0.9.13 完全一致）。v0.9.0 – v0.9.5 均已在 npm 标记 deprecated；v0.9.1 / v0.9.2 / v0.9.3 / v0.9.4 的 release tag 已从 git 移除（v0.9.5 只是被取代、tag 保留）—— v0.9.1/v0.9.2 带记忆页白屏缺陷，v0.9.0 沉淀告警误报刷屏，v0.9.3 不支持 DSH v0.1.7-rc.2（升级后插件整体挂不上：设置服务换血 + 客户端 settingsScope 消失），v0.9.4 在官方桌面版（schemastery 3.18.4 的 volatile 活引用）下抛 cfg.vaultDir.trim is not a function、插件整体挂不上，v0.9.5 的全屏浮层会盖住桌面版的窗口控制面板（右上角「×」压在窗口「关闭」上，点一下会退出整个桌面壳）。请一律使用 v0.9.6+（npm i memory-eternal@latest）。
DSH 兼容性：>=0.1.5-alpha.2 <0.3.0-0（v0.10.1 起放宽：旧的上界 <0.2.0 在 semver 上会把 DSH 0.2.0-rc.x 排除在外 —— DSH 的插件守卫用 includePrerelease:true 判定，实际仍能装上，但声明与事实不一致；现在明确覆盖整个 0.1/0.2 线，且 <0.3.0-0 仍然挡住 0.3.0 及其预发布。已在官方桌面版 DSH 0.2.0-rc.2 上实测运行：插件挂载、记忆页、自动沉淀、审核中心、导入导出均正常）。v0.9.4 起适配 DSH v0.1.7-rc.2（该版本把设置服务换成纯表单 API，并移除了 @deepseek-ai/dsh-client-runtime 与 settingsScope）；v0.9.5 起兼容 schemastery ≥3.18.4 的 volatile 活引用（官方桌面版 profile 即此形态，web profile 仍是 3.18.1，两者都支持）；v0.9.6 起全屏浮层自动让开桌面壳的窗口标题栏（不再压住最小化/最大化/关闭）。0.1.5 系列仍走旧的 settings.register 路径，两条路径都保留。

 长路径加 word-break（远程 agent 的路径没有断点，以前必横向滚）；大标题 modal 的 h2 加省略号。新增 tests/ui-overflow.test.mjs（4 项守卫）。npm test 共 406 项

💬 交流群 & 打赏

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

如果这个插件帮你省了时间，可以请作者喝杯咖啡（两个码任选其一）：

微信收款码	微信赞赏码

打赏完全自愿，不影响任何功能；插件本体始终开源免费（MIT）。
仓库页的 Sponsor 按钮下拉里选 custom 第一项，会落到 SPONSOR.md（同样是这一页的码）。

📄 License

MIT

让 AI 真正记住你：对话自动沉淀，知识随手可查。 ⭐ 觉得有用就点个 Star，Let's make AI not forget.

English README: README.en.md