memory-eternal 0.16.0 → 0.18.0

package/README.zh-CN.md

@@ -0,0 +1,138 @@
+# 🧠 memory-eternal —— 给 AI 装一个可信的第二大脑
+
+[![GitHub stars](https://img.shields.io/github/stars/EternalNight996/memory-eternal?style=flat)](https://github.com/EternalNight996/memory-eternal/stargazers)
+[![npm](https://img.shields.io/npm/v/memory-eternal)](https://www.npmjs.com/package/memory-eternal)
+[![release](https://img.shields.io/badge/release-v0.18.0-FF7A45)](https://github.com/EternalNight996/memory-eternal/releases)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+[English (default)](README.md) · **简体中文（镜像）**
+
+<p align="center">
+  <a href="https://eternalnight996.github.io/memory-eternal/demo/"><img src="https://raw.githubusercontent.com/EternalNight996/memory-eternal/main/assets/screen/demo.gif" width="900" alt="memory-eternal 20 秒演示：审核队列、记忆账本、知识星图" /></a>
+</p>
+<p align="center"><sub>▲ 20 秒演示 —— 审核队列 · 记忆账本 · 知识星图 · <a href="https://eternalnight996.github.io/memory-eternal/demo/">在线 Demo</a></sub></p>
+
+> **你的 AI 每次会话都失忆。给它一个可信的记忆库。**
+>
+> 本地优先、先审后入、可度量 —— 一个 SQLite 库，DSH / Claude Code / Codex / Cursor 与任意 MCP 客户端共享。
+
+- 🔍 **先审核，再入库** —— 新卡先进待审队列，Web 或终端里批准/驳回；每次状态变更写入不可篡改的审计日志。
+- 🧾 **记忆账本** —— 召回注入了多少、蒸馏调了几次、召回到底有没有用，全部可查。
+- 🏠 **本地优先，零云端** —— SQLite + Markdown 存在你自己的磁盘上。没有第三方记忆框架、不需要账号、不外发请求。
+
+<p align="center"><strong>⭐ 如果它帮你少解释了一遍上下文，点个 Star 就是最大的支持</strong><br/><sub>DSH 一条命令：<code>dsh plugin --profile desktop add memory-eternal</code></sub></p>
+
+## ⚡ 快速开始
+
+**DeepSeek Harness（桌面版 / Web）**
+
+```bash
+dsh plugin --profile desktop add memory-eternal
+# 重开 DSH → 左栏「记忆」
+```
+
+**Claude Code、Codex 或 Cursor —— 通过 MCP 共享同一个库**
+
+```bash
+npm i -g memory-eternal
+dsh-memory connect claude    # 或：codex / cursor
+```
+
+**任意 MCP 客户端**
+
+```bash
+npx -y -p memory-eternal dsh-memory mcp
+```
+
+**浏览器或终端**
+
+```bash
+dsh-memory open              # http://127.0.0.1:7999
+npx -y -p memory-eternal dsh-memory tui   # 终端里的实时待审队列
+```
+
+## 🧾 真的省 token 吗？
+
+大多数记忆产品都说自己省 token。我们认为你应该自己验证。插件内置**记忆账本**（运行状态 → 记忆账本），记录：
+
+| 记录项 | 含义 |
+|---|---|
+| 召回：命中数 + 注入字符 | 到底有多少记忆进入了上下文 |
+| 沉淀：LLM 调用次数 + 输入/输出字符 | 蒸馏花了你多少成本 |
+| 有用率：有用 / 没用 反馈 | 召回的记忆是否真的帮上了忙 |
+
+诚实的算式：
+
+```text
+净收益 ≈ 被避免的上下文开销 −（注入字符 + 蒸馏调用 × 单价）
+```
+
+| 场景 | 你要付 | 你能省 |
+|---|---|---|
+| 有决策与踩坑记录的多会话项目 | 每次召回约 0.6–0.9k token | 重新解释上下文（约 1.5–3k）或重读文件（3–6k） |
+| 一次性问题、低命中率 | 召回注入 | 通常什么也省不到 |
+
+> 以上是示意数字，不是 benchmark —— 用账本测你自己的。如果召回有用率长期低于约 60%，就调小（更少条数、更短摘要）或直接关掉记忆。
+
+## 🛡️ 先审核，再入库
+
+一个「什么都自动吞进去」的记忆系统，迟早会把错误事实当成真相召回。memory-eternal 默认**先审后入**：
+
+- 新卡先进入**待审队列**，人工批准后才进主库；
+- 在 Web、终端 TUI 或 CLI 里批准 / 驳回 / 批量处理；
+- 每次状态变更追加到**不可篡改的审计日志**（谁 / 什么 / 何时 / 为什么）—— 由 SQLite 层强制，而不是靠约定；
+- Agent 可以读取和提议，但**不能批准自己写的卡**；
+- 删除的卡进回收站（默认保留 30 天）。
+
+## 🧩 一个库，所有 Agent
+
+| 入口 | 你能得到什么 |
+|---|---|
+| **DSH 桌面版 / Web** | 内嵌记忆界面：审核、图谱、配置、账本 |
+| **Claude Code / Codex / Cursor** | MCP server，同一个本地库，<code>dsh-memory connect</code> |
+| **任意 MCP 客户端** | <code>npx -y -p memory-eternal dsh-memory mcp</code> |
+| **终端** | <code>dsh-memory tui</code> —— 实时队列、全选、批量批/驳、长文读卡 |
+| **浏览器** | <code>dsh-memory open</code> → http://127.0.0.1:7999 |
+
+## 📸 截图
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/EternalNight996/memory-eternal/main/assets/screen/graph.png" width="32%" alt="知识星图：按类型分簇、标签连边" />
+  <img src="https://raw.githubusercontent.com/EternalNight996/memory-eternal/main/assets/screen/audit.png" width="32%" alt="审核中心：类型条、队列与判词栏" />
+  <img src="https://raw.githubusercontent.com/EternalNight996/memory-eternal/main/assets/screen/status.png" width="32%" alt="运行状态：库、备份、自动沉淀与版本" />
+</p>
+<p align="center"><sub>▲ 知识星图 · 审核中心 · 运行状态</sub></p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/EternalNight996/memory-eternal/main/assets/screen/tui-audit.png" width="49%" alt="终端原生审核：全选、批量批准/驳回" />
+  <img src="https://raw.githubusercontent.com/EternalNight996/memory-eternal/main/assets/screen/tui-reader.png" width="49%" alt="终端原生长文读卡器" />
+</p>
+<p align="center"><sub>▲ 终端原生审核与长文读卡 —— <code>dsh-memory tui</code></sub></p>
+
+## 📚 文档与链接
+
+- [英文完整手册](docs/GUIDE.md) · [完整手册（中文）](docs/GUIDE.zh-CN.md)
+- [私有化部署（Docker / systemd）](docs/DEPLOY.md)
+- [更新日志](docs/CHANGELOG.md) · [架构](docs/ARCHITECTURE.md)
+- [终端插件（dsh-tui）](dsh-tui-plugin/README.md) · [Orca 启动器](orca-plugin/README.md) · [Cursor / VS Code 扩展](cursor-extension/README.md)
+- [反馈问题](https://github.com/EternalNight996/memory-eternal/issues)
+
+## 💬 交流群
+
+**遇到问题、想提需求、或者想聊聊 DSH 插件开发 —— 欢迎进群：**
+
+| QQ 交流群 | 微信交流群 |
+|:---:|:---:|
+| <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.png" width="240" alt="微信群二维码" /> |
+
+**如果这个插件帮你省了时间，可以请作者喝杯咖啡（两个码任选其一）：**
+
+| 微信收款码 | 微信赞赏码 |
+|:---:|:---:|
+| <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="微信赞赏码" /> |
+
+> 打赏完全自愿，不影响任何功能；插件本体始终开源免费（MIT）。详见 [SPONSOR.md](SPONSOR.md)。
+
+## 📄 License
+
+MIT —— 随便用、随便自托管、随便二次开发。

package/bin/dsh-memory.mjs

@@ -4,7 +4,7 @@
 // 用法：
 //   dsh-memory recall <query> [--limit N] [--vault DIR]   检索知识卡
 //   dsh-memory capture <text | - > [--source TAG]         手动沉淀（- 读 stdin）
-//   dsh-memory serve [--port N] [--vault DIR]             启动 Web UI（前台常驻）
+//   dsh-memory serve [--port N] [--host H] [--vault DIR]  启动 Web UI（前台常驻；--host 0.0.0.0 用于容器/内网，需自行加认证）
 //   dsh-memory open [--port N]                            确保 Web 存活并用浏览器打开
 //   dsh-memory tui [--live] [--write]                     打开完整终端客户端（无需绝对路径）
 //   dsh-memory mcp                                        MCP stdio server（各 agent 挂载）
@@ -18,6 +18,7 @@
 //   dsh-memory refine [--vault DIR] [--json]              矛盾扫描候选（不调模型）；--apply --a A --b B --action keepA|keepB|merge|keepBoth 落裁决
 //   dsh-memory refine --junk [--purge --path P] [--json]   注入垃圾卡（技能目录等注入文本沉淀成的卡）：列清单 / 送回收站
 //   dsh-memory refine --goals [--keep --path A --path B]   同目标不同做法：聚类需模型（面板里跑）；--keep 落"都保留"
+//   dsh-memory ledger [--days N] [--json]                 记忆账本：召回注入 / 蒸馏调用 / 召回有用率
 //
 // 环境变量：
 //   MEMORY_VAULT_DIR       vault 目录（默认 ~/.dsh/memory-vault）
@@ -105,8 +106,10 @@ async function main() {
       const { startWebServer, DEFAULT_WEB_PORT } = await import('../lib/web.js')
       const { defaultVaultDir } = await import('../lib/capture-run.js')
       const port = Number(argOf('--port')) || DEFAULT_WEB_PORT
+      // 默认只监听本机：私有化/容器部署时显式 --host 0.0.0.0，并在前面加 TLS + 认证的反向代理
+      const host = argOf('--host') || process.env.MEMORY_WEB_HOST || '127.0.0.1'
       const vault = path.resolve(argOf('--vault') || defaultVaultDir())
-      await startWebServer({ port, vaultRoot: vault })
+      await startWebServer({ port, vaultRoot: vault, host })
       process.on('SIGINT', () => process.exit(0))
       process.on('SIGTERM', () => process.exit(0))
       return
@@ -148,6 +151,32 @@ async function main() {
       startMcpServer()
       return
     }
+    case 'ledger': {
+      const { ledgerSummary } = await import('../lib/ledger.js')
+      const { defaultVaultDir } = await import('../lib/capture-run.js')
+      const root = path.resolve(argOf('--vault') || defaultVaultDir())
+      const days = Math.min(Math.max(Math.floor(Number(argOf('--days')) || 7), 1), 90)
+      let s
+      try { s = ledgerSummary(root, { days }) } catch (e) {
+        console.error('读取记忆账本失败：' + (e?.message || e))
+        process.exitCode = 1
+        return
+      }
+      if (has('--json')) { console.log(JSON.stringify(s, null, 2)); return }
+      const fmt = (n) => Number(n || 0).toLocaleString('en-US')
+      console.log('记忆账本（最近 ' + s.days + ' 天）\n')
+      console.log('召回   ' + fmt(s.totals.recalls) + ' 次 · 注入 ' + fmt(s.totals.injectedChars) + ' 字符')
+      console.log('沉淀   ' + fmt(s.totals.captures) + ' 次 · LLM ' + fmt(s.totals.llmCalls) + ' 次 · 输入 ' + fmt(s.totals.captureInChars) + ' / 输出 ' + fmt(s.totals.captureOutChars) + ' 字符')
+      console.log('估算   ≈ ' + fmt(s.totals.estTokens) + ' tokens（中英混排按 2 字符 ≈ 1 token，仅看量级）')
+      console.log('')
+      console.log(s.feedback.rate === null
+        ? '召回有用率  暂无反馈（Agent 回传 useful 后才有数据）'
+        : '召回有用率  ' + Math.round(s.feedback.rate * 100) + '%（有用 ' + fmt(s.feedback.useful) + ' / 无用 ' + fmt(s.feedback.useless) + '）')
+      console.log('\n最近 ' + s.days + ' 天：')
+      for (const d of s.byDay) console.log('  ' + d.date + '  召回 ' + fmt(d.recalls) + ' · 注入 ' + fmt(d.injectedChars) + ' 字符 · 沉淀 ' + fmt(d.captures))
+      console.log('\n提示：--json 输出原始数据；Web 面板「运行状态 → 记忆账本」可看趋势。')
+      return
+    }
     case 'status': {
       const { watchdogStatus, probeServedVersion, findPortListener, looksLikeOurWeb } = await import('../lib/watchdog.js')
       const port = argOf('--port')
@@ -590,7 +619,7 @@ MCP 侧只提供只读的 memory_audit_list —— 批准/驳回必须由人显
 用法：
   dsh-memory recall <query> [--limit N]       检索知识卡
   dsh-memory capture <text | -> [--source T]  手动沉淀（- 读 stdin）
-  dsh-memory serve [--port N]                 Web UI（前台）
+  dsh-memory serve [--port N] [--host H]      Web UI（前台；私有化部署见 docs/DEPLOY.md）
   dsh-memory open                             确保 Web 存活并打开浏览器
   dsh-memory mcp                              MCP stdio server
   dsh-memory setup [--dry-run] ...            自动挂载 MCP 到已装 agent
@@ -601,6 +630,7 @@ MCP 侧只提供只读的 memory_audit_list —— 批准/驳回必须由人显
   dsh-memory status [--port N] [--json]      查看常驻看门狗（pid/端口/版本/存活）
   dsh-memory stop [--port N] [--json]        停止常驻看门狗（显式命令，配置变更不会自动停）
   dsh-memory restart [--port N] [--vault DIR] 停止并重新拉起看门狗（应用新版本）
+  dsh-memory ledger [--days N] [--json]      记忆账本：召回注入 / 蒸馏调用 / 有用率
   dsh-memory audit list [--status pending] [--kind K] [--json]  列出待审/驳回卡片
   dsh-memory audit approve <path...> | reject <path...> [--reason "原因"]  人工批量审批
 

package/cursor-extension/package.json

@@ -1,54 +1,54 @@
-{
-  "name": "memory-eternal",
-  "displayName": "Memory Atlas",
-  "description": "Memory-eternal: open the local Memory Atlas library, review queue and knowledge graph in a Cursor/VS Code webview.",
-  "version": "0.16.0",
-  "publisher": "EternalNight996",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/EternalNight996/memory-eternal"
-  },
-  "engines": {
-    "vscode": "^1.80.0"
-  },
-  "categories": [
-    "Other"
-  ],
-  "activationEvents": [
-    "onView:memory-eternal.view",
-    "onCommand:memory-eternal.open"
-  ],
-  "main": "./extension.js",
-  "contributes": {
-    "viewsContainers": {
-      "activitybar": [
-        {
-          "id": "memory-eternal",
-          "title": "Memory Atlas",
-          "icon": "icon.png"
-        }
-      ]
-    },
-    "views": {
-      "memory-eternal": [
-        {
-          "id": "memory-eternal.view",
-          "name": "记忆",
-          "type": "webview"
-        }
-      ]
-    },
-    "commands": [
-      {
-        "command": "memory-eternal.open",
-        "title": "Memory Atlas: Open"
-      }
-    ]
-  },
-  "files": [
-    "extension.js",
-    "icon.png",
-    "README.md"
-  ]
-}
+{
+  "name": "memory-eternal",
+  "displayName": "Memory Atlas",
+  "description": "Memory-eternal: open the local Memory Atlas library, review queue and knowledge graph in a Cursor/VS Code webview.",
+  "version": "0.18.0",
+  "publisher": "EternalNight996",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/EternalNight996/memory-eternal"
+  },
+  "engines": {
+    "vscode": "^1.80.0"
+  },
+  "categories": [
+    "Other"
+  ],
+  "activationEvents": [
+    "onView:memory-eternal.view",
+    "onCommand:memory-eternal.open"
+  ],
+  "main": "./extension.js",
+  "contributes": {
+    "viewsContainers": {
+      "activitybar": [
+        {
+          "id": "memory-eternal",
+          "title": "Memory Atlas",
+          "icon": "icon.png"
+        }
+      ]
+    },
+    "views": {
+      "memory-eternal": [
+        {
+          "id": "memory-eternal.view",
+          "name": "记忆",
+          "type": "webview"
+        }
+      ]
+    },
+    "commands": [
+      {
+        "command": "memory-eternal.open",
+        "title": "Memory Atlas: Open"
+      }
+    ]
+  },
+  "files": [
+    "extension.js",
+    "icon.png",
+    "README.md"
+  ]
+}

package/dsh-tui-plugin/dsh-plugin.json

@@ -1,42 +1,42 @@
-{
-  "$schema": "urn:dsh-std:community-draft:dsh-plugin:0.15",
-  "id": "memory-eternal-tui",
-  "name": "memory-eternal-tui",
-  "version": "0.16.0",
-  "manifestVersion": "0.15",
-  "description": "Open Memory Atlas from dsh-TUI: native /audit scene plus browser launcher.",
-  "facets": {
-    "host": {
-      "entry": "main.js",
-      "apiVersion": "v1alpha1"
-    }
-  },
-  "requires": {
-    "contracts": [
-      {
-        "apiVersion": "commands.dsh/v1alpha1",
-        "kind": "Command"
-      }
-    ]
-  },
-  "permissions": [],
-  "contributes": {
-    "commands": [
-      {
-        "id": "memory-eternal-tui.open",
-        "title": "memory",
-        "description": "Open Memory Atlas in the browser"
-      },
-      {
-        "id": "memory-eternal-tui.audit",
-        "title": "audit",
-        "description": "Open the native Memory Atlas audit scene"
-      }
-    ]
-  },
-  "subscriptions": [],
-  "license": "MIT",
-  "source": {
-    "repository": "https://github.com/EternalNight996/memory-eternal"
-  }
-}
+{
+  "$schema": "urn:dsh-std:community-draft:dsh-plugin:0.15",
+  "id": "memory-eternal-tui",
+  "name": "memory-eternal-tui",
+  "version": "0.18.0",
+  "manifestVersion": "0.15",
+  "description": "Open Memory Atlas from dsh-TUI: native /audit scene plus browser launcher.",
+  "facets": {
+    "host": {
+      "entry": "main.js",
+      "apiVersion": "v1alpha1"
+    }
+  },
+  "requires": {
+    "contracts": [
+      {
+        "apiVersion": "commands.dsh/v1alpha1",
+        "kind": "Command"
+      }
+    ]
+  },
+  "permissions": [],
+  "contributes": {
+    "commands": [
+      {
+        "id": "memory-eternal-tui.open",
+        "title": "memory",
+        "description": "Open Memory Atlas in the browser"
+      },
+      {
+        "id": "memory-eternal-tui.audit",
+        "title": "audit",
+        "description": "Open the native Memory Atlas audit scene"
+      }
+    ]
+  },
+  "subscriptions": [],
+  "license": "MIT",
+  "source": {
+    "repository": "https://github.com/EternalNight996/memory-eternal"
+  }
+}

package/dsh-tui-plugin/package.json

@@ -1,51 +1,51 @@
-{
-  "name": "memory-eternal-tui",
-  "version": "0.16.0",
-  "description": "Memory Atlas for dsh-TUI: /audit scene with reason/severity, batch confirmation and reject reasons.",
-  "type": "module",
-  "main": "main.js",
-  "files": [
-    "main.js",
-    "scene.js",
-    "demo-audit.mjs",
-    "demo.mjs",
-    "dsh-plugin.json",
-    "cordis.patch.yml",
-    "README.md"
-  ],
-  "keywords": [
-    "dsh",
-    "dsh-tui",
-    "dsh-tui-plugin",
-    "memory-eternal",
-    "memory",
-    "audit",
-    "plugin"
-  ],
-  "license": "MIT",
-  "author": "EternalNight996",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/EternalNight996/memory-eternal.git",
-    "directory": "dsh-tui-plugin"
-  },
-  "homepage": "https://github.com/EternalNight996/memory-eternal/tree/main/dsh-tui-plugin",
-  "bugs": {
-    "url": "https://github.com/EternalNight996/memory-eternal/issues"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=22"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1"
-  }
-}
+{
+  "name": "memory-eternal-tui",
+  "version": "0.18.0",
+  "description": "Memory Atlas for dsh-TUI: /audit scene with reason/severity, batch confirmation and reject reasons.",
+  "type": "module",
+  "main": "main.js",
+  "files": [
+    "main.js",
+    "scene.js",
+    "demo-audit.mjs",
+    "demo.mjs",
+    "dsh-plugin.json",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-tui",
+    "dsh-tui-plugin",
+    "memory-eternal",
+    "memory",
+    "audit",
+    "plugin"
+  ],
+  "license": "MIT",
+  "author": "EternalNight996",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EternalNight996/memory-eternal.git",
+    "directory": "dsh-tui-plugin"
+  },
+  "homepage": "https://github.com/EternalNight996/memory-eternal/tree/main/dsh-tui-plugin",
+  "bugs": {
+    "url": "https://github.com/EternalNight996/memory-eternal/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}