memory-eternal 0.23.0 → 0.25.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "memory-eternal",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "记忆核心（Memory Eternal）：对话结束后自动沉淀知识卡到本地记忆库（~/.dsh/memory-vault），支持检索 / 召回 / 审核中心。",
   "author": {
     "name": "EternalNight996",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-eternal",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "记忆核心（Memory Eternal）：对话结束后自动沉淀知识卡到本地记忆库（~/.dsh/memory-vault），支持检索 / 召回 / 审核中心。",
   "author": {
     "name": "EternalNight996",

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-eternal",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "记忆核心（Memory Eternal）：对话结束后自动沉淀知识卡到本地记忆库（~/.dsh/memory-vault），支持检索 / 召回 / 审核中心。",
   "author": {
     "name": "EternalNight996",

package/README.md

@@ -1,8 +1,14 @@
 # 🧠 memory-eternal — a second brain for your AI
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/EternalNight996/memory-eternal/main/assets/screen/cover-zh.png" width="900" alt="记忆核心 memory-eternal：给 AI 一个不会忘、可审核、可量化的长期记忆" />
+</p>
+
+**记忆核心（memory-eternal）** —— 给 AI 一个不会忘、可审核、可量化的长期记忆。本地优先 · 审核闸门 · 记忆账本 · 一个库接入 DSH / Claude Code / Codex / Cursor 与任意 MCP 客户端。
+
 [![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.23.0-FF7A45)](https://github.com/EternalNight996/memory-eternal/releases)
+[![release](https://img.shields.io/badge/release-v0.25.0-FF7A45)](https://github.com/EternalNight996/memory-eternal/releases)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 **English (default)** · [简体中文](README.zh-CN.md)
@@ -54,6 +60,75 @@ dsh-memory open              # http://127.0.0.1:7999
 npx -y -p memory-eternal dsh-memory tui   # live queue in the terminal
 ```
 
+## 🧬 How memory actually flows
+
+One SQLite vault, one write gate, two read paths. Nothing enters recall without passing the gate.
+
+```mermaid
+flowchart TD
+  subgraph S1["① Input"]
+    A1["Conversation + tool events<br/>captured when a turn ends"]
+    A2["Installed skills<br/>scanned from the host"]
+    A3["News follows<br/>RSS · GitHub · HN · arXiv · DSH plugins"]
+    A4["Manual cards / imports"]
+  end
+  subgraph S2["② Distill — the only LLM step"]
+    B1["LLM distills the session<br/>on failure: raw card, nothing lost"]
+    B2["Dedup: lexical Jaccard<br/>optional LLM merge decision"]
+    B3["Kind classification"]
+  end
+  subgraph S3["③ Review gate — human only"]
+    C1[("Quarantine<br/>pending / rejected")]
+    C2{"approve / reject"}
+    C3[("Main store<br/>approved only")]
+  end
+  subgraph S4["④ Storage"]
+    D1[("SQLite: cards + FTS5 index")]
+    D2["Markdown mirror<br/>git-able"]
+    D3["audit_log + token ledger"]
+  end
+  subgraph S5["⑤ Recall — every session"]
+    E1["Core memory → system prompt"]
+    E2["memory_recall → FTS5 + BM25"]
+    E3["memory_revise → pending revision"]
+  end
+  A1 --> B1 --> B2 --> B3 --> C1
+  A2 --> B2
+  A3 --> C1
+  A4 --> B2
+  C1 --> C2
+  C2 -->|approve| C3
+  C2 -->|reject| C1
+  C3 --> D1
+  D1 --> D2
+  C3 --> D3
+  C3 --> E1
+  C3 --> E2
+  E2 -->|hits + chars| D3
+  E3 --> C1
+```
+
+The diagram is only true because three invariants are enforced in code, not by convention:
+
+| Invariant | Enforced by |
+|---|---|
+| The main store **only** ever contains approved cards | Two physical tables; every read path queries the main one |
+| An agent can never approve its own memory | Agent writes land in quarantine; approve/reject is a human action in the UI / TUI / CLI |
+| Recall costs **zero model calls** | FTS5 + BM25; the LLM runs only while distilling |
+
+## 🔌 How agents talk to the memory
+
+| Channel | Direction | When | Gate | Cost |
+|---|---|---|---|---|
+| `memory_recall` | agent → memory | on demand | approved only | **0 model calls** (p50 2.3 ms) |
+| Core memory | memory → agent | every session, automatic | approved only | ~0.2k chars |
+| Session capture / `memory_write` | conversation → memory | turn end | **queued for review** | 1 LLM call |
+| `memory_revise` | agent → memory | on demand | **queued as a revision** | 0 |
+| Review (Web UI · TUI · CLI) | human → memory | manual | — | 0 |
+| Hooks (Claude Code / Codex / Cursor) | host → memory | session end | **queued** | 1 LLM call |
+| MCP server | any MCP client | on demand | same gate | same |
+| News follows | web → memory | interval / 24h | isolated from cards | network only |
+
 ## 🧾 Does it actually save tokens?
 
 Most memory products <em>say</em> they save tokens. We think you should check. The plugin ships a built-in **memory ledger** (Runtime status → Memory ledger) that records:
@@ -77,6 +152,42 @@ net benefit ≈ avoided context cost − (injected characters + distillation cal
 
 > Illustrative numbers, not a benchmark — measure your own with the ledger. If recall usefulness stays below ~60%, tune it down (fewer results, shorter summaries) or turn memory off.
 
+## 📊 How it compares — measured on a real vault
+
+Snapshot **2026-11-07**. Our figures are measured on a real **2,321-card vault** on Windows (not a toy corpus); competitor figures come from their public README / npm / GitHub on the same date. `—` means *not advertised or not verifiable*, not "absent".
+
+| Capability | **memory-eternal v0.24.0** | 灵枢 dsh-memory v0.9.23 | SAG-Wiki v0.2.7 | CLAUDE.md / AGENTS.md |
+|---|---|---|---|---|
+| Storage | SQLite + Markdown mirror | Markdown cognitive graph | SQLite FTS5 over your files | flat file(s) |
+| Write gate | **human review queue** (3 stores) | deterministic rules | none — index is truth | none |
+| Immutable audit log | ✅ enforced at the SQLite layer | ✅ claimed | — | — |
+| Retrieval | FTS5 + **BM25/IDF**, column weights | rule-based graph walk | BM25 → JEV (LLM judge) | whole file injected |
+| Recall latency | **p50 2.33 ms · p95 6.18 ms** | — | — | grows with file size |
+| Recall model calls | **0** | 0 | 1–2 per query | 0 |
+| Token ledger (measured usefulness) | ✅ | — | — | — |
+| Multi-agent | DSH + MCP + hooks + TUI + browser | DSH + MCP | CLI + skill | per tool |
+| npm downloads / month | 14,370 | **31,421** | 119 | n/a |
+| GitHub stars | 147 | **612** | 124 | n/a |
+| License | MIT | MIT | MIT | n/a |
+
+**We are not the biggest here.** 灵枢 has more stars and downloads; SAG-Wiki retrieves over your own documents better than we do. What we do differently is the *write path*: a human gate, a three-store separation, and an audit trail you can point at — plus a token ledger so you can check whether recall is worth its cost.
+
+Reproduce our numbers on your own vault:
+
+```bash
+node scripts/bench-search.mjs --rebuild   # rebuild time + p50/p95/max latency
+dsh-memory ledger --days 30 --json        # recall injection / capture / usefulness
+```
+
+| Our measured baseline | Value |
+|---|---|
+| Cards indexed | 2,321 |
+| Index rebuild (cold) | 869 ms |
+| Recall p50 / p95 / max | 2.33 / 6.18 / 7.60 ms |
+| Recall throughput | ~431 queries/s |
+| Recall model calls | 0 |
+| Injection per recall (60-day ledger) | ~1,394 chars |
+
 ## 🛡️ Review first, prove later
 
 A memory system that silently ingests everything will eventually recall a wrong fact as truth. memory-eternal defaults to **review-before-commit**:

package/README.zh-CN.md

@@ -1,8 +1,14 @@
 # 🧠 memory-eternal —— 给 AI 装一个可信的第二大脑
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/EternalNight996/memory-eternal/main/assets/screen/cover-zh.png" width="900" alt="记忆核心 memory-eternal：给 AI 一个不会忘、可审核、可量化的长期记忆" />
+</p>
+
+**记忆核心（memory-eternal）** —— 给 AI 一个不会忘、可审核、可量化的长期记忆。本地优先 · 审核闸门 · 记忆账本 · 一个库接入 DSH / Claude Code / Codex / Cursor 与任意 MCP 客户端。
+
 [![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.23.0-FF7A45)](https://github.com/EternalNight996/memory-eternal/releases)
+[![release](https://img.shields.io/badge/release-v0.25.0-FF7A45)](https://github.com/EternalNight996/memory-eternal/releases)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 [English (default)](README.md) · **简体中文（镜像）**
@@ -54,6 +60,75 @@ dsh-memory open              # http://127.0.0.1:7999
 npx -y -p memory-eternal dsh-memory tui   # 终端里的实时待审队列
 ```
 
+## 🧬 底层记忆是怎么流动的
+
+一个 SQLite 库、一道写入闸门、两条读取路径。**没过闸门的东西，永远不会被召回。**
+
+```mermaid
+flowchart TD
+  subgraph S1["① 输入"]
+    A1["对话 + 工具调用事件<br/>一轮结束后采集"]
+    A2["本机已装技能<br/>从宿主技能注册表扫描"]
+    A3["新闻关注<br/>RSS · GitHub · HN · arXiv · DSH 插件"]
+    A4["手动建卡 / 导入"]
+  end
+  subgraph S2["② 沉淀 —— 唯一消耗 LLM 的一步"]
+    B1["LLM 蒸馏成知识卡<br/>失败则降级原文卡，不丢内容"]
+    B2["去重：词法 Jaccard<br/>可选 LLM 判「新建 vs 追加」"]
+    B3["归类：knowledge / project / skill …"]
+  end
+  subgraph S3["③ 审核闸门 —— 只能由人操作"]
+    C1[("隔离区<br/>pending / rejected")]
+    C2{"批准 / 驳回"}
+    C3[("主库<br/>只存 approved")]
+  end
+  subgraph S4["④ 存储"]
+    D1[("SQLite：cards + FTS5 索引")]
+    D2["Markdown 镜像<br/>可 git 管理"]
+    D3["审计日志 + 记忆账本"]
+  end
+  subgraph S5["⑤ 召回 —— 每轮会话"]
+    E1["核心记忆 → systemPrompt"]
+    E2["memory_recall → FTS5 + BM25"]
+    E3["memory_revise → 待审修改副本"]
+  end
+  A1 --> B1 --> B2 --> B3 --> C1
+  A2 --> B2
+  A3 --> C1
+  A4 --> B2
+  C1 --> C2
+  C2 -->|批准| C3
+  C2 -->|驳回| C1
+  C3 --> D1
+  D1 --> D2
+  C3 --> D3
+  C3 --> E1
+  C3 --> E2
+  E2 -->|命中 + 注入字符| D3
+  E3 --> C1
+```
+
+这张图之所以成立，是因为三条不变量**写在代码里**，不是写在文档里：
+
+| 不变量 | 由什么保证 |
+|---|---|
+| 主库**物理上只存 approved** | 两张物理表；所有读取路径只查主库 |
+| Agent **永远不能批准自己的记忆** | Agent 只能写进隔离区；批准/驳回是 UI / TUI / CLI 里的人工动作 |
+| 召回**零模型调用** | FTS5 + BM25；LLM 只在沉淀时运行 |
+
+## 🔌 Agent 与记忆的交互通道
+
+| 通道 | 方向 | 何时 | 闸门 | 成本 |
+|---|---|---|---|---|
+| `memory_recall` | Agent → 记忆 | 按需 | 只读已批准 | **0 次模型调用**（p50 2.3ms） |
+| 核心记忆 | 记忆 → Agent | 每轮会话自动 | 只读已批准 | 约 0.2k 字符 |
+| 会话沉淀 / `memory_write` | 对话 → 记忆 | 一轮结束 | **进待审队列** | 1 次 LLM |
+| `memory_revise` | Agent → 记忆 | 按需 | **进待审「修改副本」** | 0 |
+| 审核（Web / TUI / CLI） | 人 → 记忆 | 手动 | — | 0 |
+| Hook（Claude Code / Codex / Cursor） | 宿主 → 记忆 | 会话结束 | **进待审** | 1 次 LLM |
+| MCP 服务 | 任意 MCP 客户端 | 按需 | 同上 | 同上 |
+| 新闻关注 | 网络 → 记忆 | 按间隔 / 24h | 与知识卡隔离 | 仅网络 |
+
 ## 🧾 真的省 token 吗？
 
 大多数记忆产品都说自己省 token。我们认为你应该自己验证。插件内置**记忆账本**（运行状态 → 记忆账本），记录：
@@ -77,6 +152,42 @@ npx -y -p memory-eternal dsh-memory tui   # 终端里的实时待审队列
 
 > 以上是示意数字，不是 benchmark —— 用账本测你自己的。如果召回有用率长期低于约 60%，就调小（更少条数、更短摘要）或直接关掉记忆。
 
+## 📊 与同类产品的实测对比
+
+数据快照：**2026-11-07**。我们的数字在**真实 2,321 张卡的库**上实测（不是玩具语料）；竞品数据取自同一日期的公开 README / npm / GitHub。`—` 表示**未公开或无法核实**，不代表"没有"。
+
+| 能力 | **memory-eternal v0.24.0** | 灵枢 dsh-memory v0.9.23 | SAG-Wiki v0.2.7 | CLAUDE.md / AGENTS.md |
+|---|---|---|---|---|
+| 存储 | SQLite + Markdown 镜像 | Markdown 认知图 | 对本地文件的 SQLite FTS5 索引 | 单个文件 |
+| 写入闸门 | **人工审核队列**（三库分离） | 确定性规则裁决 | 无（索引即真相） | 无 |
+| 不可变审计日志 | ✅ SQLite 层强制 | ✅ 官方声称 | — | — |
+| 检索 | FTS5 + **BM25/IDF**，多列加权 | 规则化图谱遍历 | BM25 → JEV（LLM 判定） | 整文件注入 |
+| 召回延迟 | **p50 2.33ms · p95 6.18ms** | — | — | 随文件体积增长 |
+| 召回模型调用 | **0** | 0 | 每次查询 1–2 次 | 0 |
+| 记忆账本（可量化有用率） | ✅ | — | — | — |
+| 多 Agent | DSH + MCP + Hook + TUI + 浏览器 | DSH + MCP | CLI + Skill | 各工具各自为政 |
+| npm 月下载 | 14,370 | **31,421** | 119 | 不适用 |
+| GitHub Star | 147 | **612** | 124 | 不适用 |
+| 许可证 | MIT | MIT | MIT | 不适用 |
+
+**我们不是这里最大的。** 灵枢的 star 和下载都比我们多；SAG-Wiki 检索你自己文档的能力也比我们强。我们做的不一样的是**写入路径**：人审闸门、三库分离、可指认的审计链条，外加一本让你能自己核对"召回到底值不值"的记忆账本。
+
+在我们的库上自己复跑：
+
+```bash
+node scripts/bench-search.mjs --rebuild   # 重建耗时 + p50/p95/max 延迟
+dsh-memory ledger --days 30 --json        # 召回注入 / 沉淀调用 / 有用率
+```
+
+| 我们实测的基线 | 数值 |
+|---|---|
+| 索引卡片数 | 2,321 |
+| 冷启动全量重建 | 869 ms |
+| 召回 p50 / p95 / max | 2.33 / 6.18 / 7.60 ms |
+| 召回吞吐 | 约 431 次/秒 |
+| 召回模型调用 | 0 |
+| 每次召回注入（60 天账本） | 约 1,394 字符 |
+
 ## 🛡️ 先审核，再入库
 
 一个「什么都自动吞进去」的记忆系统，迟早会把错误事实当成真相召回。memory-eternal 默认**先审后入**：

package/cursor-extension/package.json

@@ -2,7 +2,7 @@
   "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.23.0",
+  "version": "0.25.0",
   "publisher": "EternalNight996",
   "license": "MIT",
   "repository": {

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

@@ -2,7 +2,7 @@
   "$schema": "urn:dsh-std:community-draft:dsh-plugin:0.15",
   "id": "memory-eternal-tui",
   "name": "memory-eternal-tui",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "manifestVersion": "0.15",
   "description": "Open Memory Atlas from dsh-TUI: native /audit scene plus browser launcher.",
   "facets": {

package/dsh-tui-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-eternal-tui",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Memory Atlas for dsh-TUI: /audit scene with reason/severity, batch confirmation and reject reasons.",
   "type": "module",
   "main": "main.js",

package/lib/api.js

@@ -24,6 +24,7 @@ import { FOLLOW_DOMAINS, parseFollowIntent, listFollows, saveFollow, removeFollo
 import { buildDigest, readDigest, digestPrompt } from './news-digest.js'
 import { getSetupStatus, runSetup, mcpAgentAction } from './setup.js'
 import { ledgerSummary } from './ledger.js'
+import { starPromptStatus, markStarAction } from './star-prompt.js'
 import { backupDb, dbStatus, rebuildGuidance, withDbRetry } from './db.js'
 import { listNews, getNews, saveNews, deleteNews, setNewsRead } from './news.js'
 import { getNewsFeed, refreshNewsFeed } from './news-feed.js'
@@ -1306,6 +1307,24 @@ export function createApi(deps = {}) {
         } catch (e) { json(res, 200, { ok: false, error: String(e?.message || e) }) }
         return
       }
+      case '/star/status': {
+        // 价值触发的 star 提示：够不够格问、以及「讲证据」用的数字
+        try {
+          const env = typeof process !== 'undefined' ? process.env : {}
+          json(res, 200, starPromptStatus({ root: vaultRoot, env }))
+        } catch (e) { json(res, 200, { ok: false, error: String(e?.message || e) }) }
+        return
+      }
+      case '/star/action': {
+        const starChunks = []
+        for await (const chunk of req) starChunks.push(chunk)
+        let starBody
+        try { starBody = JSON.parse(Buffer.concat(starChunks).toString('utf8') || '{}') } catch { return json(res, 400, { ok: false, error: 'JSON 解析失败' }) }
+        const env = typeof process !== 'undefined' ? process.env : {}
+        const action = String(starBody?.action || 'later')
+        json(res, 200, { ok: markStarAction(env, action), action })
+        return
+      }
       case '/budget': {
         try {
           const cfg = getSettings() ?? {}