memory-eternal

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

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

对话结束自动沉淀成知识卡，跨会话不失忆；召回只取相关小块，省 token 少噪音。

全自研、零第三方记忆框架、不改 DSH 源码；一个记忆库所有 Agent 共享，SQLite 持久存储，零外部依赖。

🧩 支持平台

平台 / 宿主 · Memory Atlas UI · 待审 / 批驳 · 知识星图 · 入口与状态 DSH 桌面版 / Web · 完整内嵌 · ✅ · ✅ · 左栏「记忆」，已支持 任意终端（TUI） · 终端原生 · ✅ 全选 / 批量批驳 · 连接簇 / 邻接表 · dsh-memory tui，免绝对路径 Orca · 侧栏启动器 · Web 内完成 · Web 内完成 · 右栏「记忆」，本版新增 dsh-tui · 原生 /audit + 完整 TUI · 原生场景 · 原生场景 · 本版新增 Codex · 浏览器打开 · Web 内完成 · Web 内完成 · memory-open skill，本版新增 Claude Code · 浏览器打开 / Pane · Web 内完成 · Web 内完成 · /memory-eternal:memory-open，本版新增 Cursor · Webview 内嵌 · ✅ · ✅ · 扩展 Webview，本版新增 纯 Web · 主实现 · ✅ · ✅ · http://127.0.0.1:7999/

原则：一套 Web UI 作为唯一真源；能内嵌的宿主用 Webview，不能内嵌的宿主只做轻量启动器，不复制第二套 UI。所有入口打开同一版本，避免 DSH / Web 版本漂移。

🖥️ 终端版（TUI）

Web 不是唯一入口。终端版是同一套记忆库的原生 TUI，适合快速批卡、全选、长文阅读和低干扰工作流。

任意用户，一条命令

不需要克隆仓库、不需要 cd、不需要填写本机绝对路径：

npx -y -p memory-eternal dsh-memory tui

已经安装 memory-eternal 的机器：

dsh-memory tui          # 默认实时：记忆库/待审/星图/状态/回收站
dsh-memory tui --write  # 写入：允许真实批准/驳回
dsh-memory tui --demo   # 示例数据（无 API 时也可看效果）

dsh-memory 不在 PATH 时，直接用上面的 npx 命令；它会临时下载并运行当前 npm 版本。

tui 子命令从 0.14.1 开始提供。旧版 dsh-memory 会显示帮助；升级：npm i -g --force memory-eternal@0.15.0。

终端版包含

页面 · 能力 记忆库 · 搜索、类型筛选、今日回看、读卡 待审 · 全选 / 反选、批量批准、批量驳回、判词 知识星图 · 连接簇、邻接表、相关卡片 运行状态 · 知识库、备份、版本、沉淀日志 回收站 · 恢复、彻底删除 设置 · 自动沉淀、失败提醒、审核、回收站保留、主题 读卡器 · 长文换行、目录、相关记忆、滚动

终端键位

键 · 作用 1–6 · 切换主页面 Tab · 循环页面 ↑↓ / j k · 移动 ←→ / t · 切换类型 Space · 多选 / 切换设置 s / Ctrl+A · 全选 / 反选 a · 批准当前或批量 r · 驳回当前或批量；回收站里是恢复 d · 回收站彻底删除 Enter · 读卡 / 切换设置 L · 直接打开长文读卡器 j k / PgUp PgDn / g G · 读卡器滚动 / 翻页 / 首尾 / · 搜索 Esc · 返回 / 清空 ? · 帮助 q · 退出

为什么 Web 不直接嵌 TUI

终端 TUI 依赖 alternate screen、原始键盘事件和字符网格，无法用 iframe 忠实嵌入。 所以 Web 的「终端版」页面提供可复制命令和预览，真正运行时进入终端；dsh-tui 里则使用原生 /audit 场景。

限制

• 终端不渲染图片 / 二维码 / Canvas 星图；星图使用连接簇和邻接表。
• 长文、颜色和边框依赖终端字体；Windows 建议 Windows Terminal / VS Code 集成终端。
• 默认只读；真实批驳必须显式加 --write；示例数据用 --demo。

✨ 它到底解决什么问题

你遇到的 · 以前的做法 · 用了之后 聊了 3 天的项目，新会话全忘 · 手动翻历史 / 重新解释一遍 · 每轮结束自动沉淀成卡，开工前 memory_recall 一句就回来 记忆塞进 prompt，token 爆掉 · 全量粘贴、越聊越贵 · 只召回相关的一小块（可配上限），省 token 也少噪音 AI 写的东西不敢直接信 · 无法追溯、无法回滚 · 卡片带来源 / 时间 / 状态，先审后入，删除进回收站

• 看得见：知识卡 / 图谱 / 健康概览 / 沉淀日志，四层可视化；
• 控得住：审核模式（全部人工 / 仅高风险）、去重与矛盾扫描、批量合并、每日备份与一键恢复；
• 带得走：知识库是本地 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 memory-eternal@0.15.0

# 验版本（应等于上面装的号），然后重启对应宿主生效
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 撤下的 `dsh-desktop-shell@0.3.0`，会让 `pnpm install` 直接失败；建议迁到官方桌面版，并从 profile 里删掉这套依赖**。
• 兼容矩阵（均已实测）：官方桌面版 desktop profile（schemastery 3.18.4）＋ dsh web 的 web profile（schemastery 3.18.1），两条路径共用同一份代码。

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

效果 · 在哪看 自动沉淀知识卡 · 每轮对话结束自动发生，无需操作 memory_recall 工具 · Agent 需要历史时自动调用 图形化界面 · 侧边栏底部「记忆」按钮 / 设置 → 记忆

入口：侧边栏底部「记忆」按钮 → 记忆库（左栏含 知识卡 / 知识图谱 / 用量 / 审核中心 / 回收中心 / 记忆配置）；「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 tui                # 完整终端客户端（只读真实队列；--write 才批驳）
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，用完即退，没有「开机自启」一说。

三种部署强度

场景 · 配置 · 内存 个人开发（推荐） · autoWebMode=init + 手动把 watchdogAutoSpawn 关掉（默认是开，见下方配置表） · web 47 MB 常驻 7×24 · watchdogAutoSpawn=on · web + watchdog 47+47 MB 真正开机自启（无 DSH） · Windows 计划任务跑 dsh-memory watchdog --port 7799 --interval 5000 --max-restart 10 · 同上

⚙️ 记忆配置（大白话）

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

一、最常用

配置项 · 默认 · 大白话说明 自动沉淀 · 开 · 每轮聊完自动把有用的内容存成知识卡 自动召回 · 开 · AI 需要历史时自动帮你查记忆 记忆库目录 · ~/.dsh/memory-vault · 记忆存哪，纯 Markdown 可 git 管理

多库（按项目隔离记忆）

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