slow-stack/mneme · 上手攻略

  • 仓库：slow-stack/mneme
  • 链接：https://github.com/slow-stack/mneme
  • 分类：ai（agent / RAG / llm-infra / evaluation）
  • 作者：spark
  • 更新：2026-10-19

是什么

dsh-mneme（npm 包 @modusensus/dsh-mneme）是面向 DeepSeek Harness (DSH) 的跨会话记忆插件。名字 Mneme 取自希腊记忆女神 Mnemosyne——她同样掌管记忆与"梦境"，呼应了插件里 autoDream 的离线巩固机制。

它不只是一个"把对话存起来"的工具，而是把记忆当成需要持续治理的资产来管：

  • 存储底座：本机 SQLite + 可手工编辑的 Markdown 双向镜像，记忆只落本地。
  • 检索：4 路混合召回——关键词 / 向量 / BM25 / 实体图谱，配伍色融合 + 精排。
  • 治理：后台 autoDream 离线去重、合并、归档、修正；冲突先冻结不擅自裁决，留给人在状态页做"保留 A / 保留 B / 仅标记"。
  • 可回放：每次自动整理都留一份 sha256 决策凭证（输入快照 + 决策明细 + 结果哈希），同样的输入可复现。
  • 隔离：可选的 scopeEnabled / strictScope，按 agent + workspace 双维隔离，多 Agent 多项目互不串台。
  • MCP：自带零依赖 stdio MCP server（独立 npm 包 mneme-memory，bin mneme-mcp），暴露 memory_save / memory_search / memory_list / memory_get / memory_update / memory_delete 六件套。
  • CLI 与 daemon：dsh-mneme-serve 可把记忆库跑成常驻数据面（DSH 关着也能读写），端口默认 127.0.0.1:8790。
  • M.O.（modus operandi · 手法）beta（v0.9 起）：把"操作手法"从记忆库的一行文字，搬进项目仓库 .mneme/pipelines/<id>.json——能提交、能 diff、能 PR、能被 CI 读。

解决什么问题

普通 agent 的痛点：

场景 没装插件 装了插件
周一聊完项目需求，周三继续 "能再描述一下你的项目吗？" "你指的是上周提到的博客重构吗？当时你说想用 Astro。"
告诉 AI 你的编码偏好 每轮都要重复交代 一次设定，长期生效
整理大量资料后关窗口 资料丢了 自动归档，随时检索找回

更深层的问题是"看不见的失败"——默默吞错、擅自做主、记忆库无声膨胀。dsh-mneme 的做法是把"出错"显形：决策凭证可回放、矛盾先冻结、等你裁决、夜间分层压缩。

快速安装

⚠️ 仓库是单仓多包，根目录那份 package.json 只是为了让单仓多包探测器能找到子包——它是 private、0.0.0、且没有 dsh 字段。装到根目录 = 装了一个壳，不会工作。

# 推荐：npm 包名（最省事）
dsh plugin --profile web add @modusensus/dsh-mneme
dsh web

# 带版本
dsh plugin --profile web add @modusensus/dsh-mneme@0.9.2

# 从源码装（本地目录，改完代码重启即生效）
git clone https://github.com/slow-stack/mneme.git
dsh plugin --profile web add "$(pwd)/mneme/dsh-mneme"

# 从 Git 装（不落源码）
dsh plugin --profile web add 'git+https://github.com/slow-stack/mneme.git#path:/dsh-mneme'

⚠️ #path:/dsh-mneme 不可省——省掉装到的是仓库根那份壳。宿主还会做一次可达性检查，超时默认 5 秒。

tarball 装法（Windows 路径示例）：

dsh plugin --profile web add "C:\\path\\to\\modusensus-dsh-mneme-0.9.2.tgz"

tarball 必须在 dsh-mneme/ 子目录里 npm pack 产出。pnpm pack 会因 bin 脚本 CRLF 失败。已实测。

5 分钟自验：

  1. 新开对话，跟 AI 聊几句你的偏好（比如"我写代码更喜欢 4 空格缩进"）。
  2. 关掉窗口，重开新对话。如果它还记得 = 记忆已写入。
  3. 去「设置 → 记忆库设置」按需开三个开关（见快速配置）。

快速配置

需求 配置项 默认 改法
完全离线运行 embedProvider openai 改为 local
后台自动整理记忆 autoDream true 改为 false 可关
自动提取结构化实体 entityExtractionEnabled false 改为 true
多 Agent / 多项目记忆隔离 scopeEnabled（更强隔离再加 strictScope） false 改为 true

完整键参考走 dsh-mneme/docs/CONFIGURATION.md。

⚠️ memoryDir 不要指进 profile 作用域（形如 …/profiles/<名字>/…）。插件会打一条告警但不搬库——宿主清理或迁移 profile 时记忆库会被连带带走（#218 末楼记录的实际事故）。安全做法：保持默认值 ~/.dsh/memory。要迁移 = 停写 → 复制整个目录 → 改配置指向新位置 → 重启。

核心用法

命令行（DSH 面板之外）

# 安装 / 卸载
dsh plugin --profile web add @modusensus/dsh-mneme@0.9.2
dsh plugin --profile web remove @modusensus/dsh-mneme

# 启动 Web 面板
dsh web

# 独立 daemon（DSH 关着也能读写记忆库）
npm i -g @modusensus/dsh-mneme
dsh-mneme-serve  # 默认 ~/.dsh/memory + 127.0.0.1:8790

MCP 客户端接入

前置：DSH 在运行 + 已在面板「设置 → 外部访问 API」生成 token。

// Claude Code 项目根 .mcp.json
{"mcpServers": {"mneme-memory": {"command": "mneme-mcp", "env": {"MNEME_TOKEN": "<你的token>"}}}}

# OpenClaw
openclaw mcp add mneme-memory --command mneme-mcp --env MNEME_TOKEN=<你的token>

完整客户端列表（Cursor / Codex / Hermes / OpenCode / OpenClaw 等）见 dsh-mneme/README.md 的 MCP Server 段。旧挂载兼容 dsh-mneme-mcp + DSH_MNEME_TOKEN 写法继续有效。

数据流（写入 → 巩固 → 召回）

写入 ──► 质量过滤（无用信息先拦下）
       │
       ▼
   SQLite + 本地 Markdown 镜像
       │（空闲时）
       ├─ autoDream ：去重 / 合并 / 归档 / 修正 / 冲突冻结
       └─ Sleep Mode ：分层压缩 + 模式发现 + 关系补全（可关）
       │
       ▼
   召回（混合检索 + 精排）──► 注入会话上下文

典型适用场景

  • 跨会话持续项目（多日 / 多周同一项目）：周一聊需求，周三继续不用重述。
  • 多 Agent 多项目：不同 agent / 不同 workspace 互不串台（scopeEnabled）。
  • 离线优先：embedProvider=local 可让检索完全离线（语义检索走本地 Embedding + 精排）；没配嵌入时关键词 / BM25 照样可用。
  • 审计合规：每次自动整理都留决策凭证，同样的输入可复现——适合需要可解释性（也支持可解释性）的场景。
  • 混合 LLM 栈：DSH 宿主是主模型，巩固与摘要可走宿主或另配。

坑与注意

  1. 仓库根装不上：单仓多包结构，必须指到 dsh-mneme/ 子目录或用 npm 包名。
  2. pnpm pack 失败：tarball 装法必须用 npm pack；pnpm pack 会因 bin 脚本 CRLF 失败。
  3. memoryDir 不要进 profile 作用域：宿主清理 profile 时会一起删——必须先停写再迁。
  4. 功能开关"已改"状态有第三态：v0.9.2 起新增"待重启"（#481）——改了不等于生效，配置面板会显示是否需要重启。
  5. dreamMaxTokens 默认值：v0.9.2 前一直把默认值原样当 max_tokens 发出去，撞服务商上限后 180 次巩固 0 次成功（#478）。超上限现在会自动按服务商声明上限降级。
  6. 自动蒸馏写入行 100% 拿不到向量：注释承诺的"提交后补跑"从未存在，已修（#477）。
  7. CLI -- 解析缺陷：v0.9.2 之前，-- 开头的值会被当成新旗标；只在 token 前两位恰好掷中 -（约 1/4096）时现形，潜伏了整整一个发布周期。
  8. Git 装法默认 5 秒超时：超大仓库或网络抖动时可能安装失败；可改 tarball / 本地目录绕过。
  9. 测试语料里的"形状样本"：secret scanning 告警可能来自 test/helpers/ 下刻意构造的 sk-proj- + 顺序字母数字（#465）——不是真泄露，是测试夹具；判定红/绿以双向对齐的扫描规则为准。
  10. v0.9.x M.O. 是 beta：节点状态（refuted / trusted / stale / candidate）目前全体恒为 candidate，因为还没有运行记录落点。这是 beta 标签必须摆在脸上的原因。
  11. scopeEnabled 不等于 strictScope：前者是"他者作用域降权"，后者是"显式声明收窄到他者作用域的记忆在检索/注入里完全不可见"——载体自动标注只降权，不硬挡。
  12. empirical ownership 实测 14.2%：归属即"认不出一条命令唯一属于谁"实测只有 14.2%，所以"认不出来"是合法答案，不要硬凑归属。

与同类对比

仓库自带与 Zep / Mem0 / Letta / Hindsight 的逐项对照表（11 行：存储底座 / 检索 / 写入时抽取 / 离线巩固 / 冲突处理 / 遗忘 / 作用域 / 可审计性 / 多宿主 / 离线 / 许可证），路径 docs/COMPARISON.md。要点：

  • vs Zep（arXiv:2501.13956，已核实存在）：Zep 走时序知识图谱路线，写入时 LLM 抽取；dsh-mneme 巩固由 LLM 参与但产物全程留痕可回放，冲突冻结待人工。
  • vs Mem0（arXiv:2504.19413，待核）：Mem0 走生产级抽取式记忆 + 向量/图检索；dsh-mneme 差异在冲突冻结 + 本机落库 + 决策凭证。
  • vs Letta / Hindsight：Letta 的 Sleep-time Compute（arXiv:2504.13171，已核实存在）是 autoDream「离线巩固」思想背后的学术脉络——dsh-mneme 在此之上加了 K-Means++ 聚类预分组 + 类型化决策清单（keep / merge / archive / conflict / update，sleep 侧 supersede / differentiate）+ 可回放的 dream_runs / receipt_chain sha256 审计链。

机制设计还与以下论文相互印证（引用 ID 仅基于 README 给出，未独立核实全部 arXiv 收录页，引用前请自查）：

  • 在线写入 + 离线巩固：arXiv:2608.22215（待核）——与 autoDream「快写慢巩固」同构。
  • 热度衰减：arXiv:2601.18642（待核）——heat 记忆热度模型（指数衰减 × 访问强化 × 重要性调制）的学术近亲。
  • 冲突裁决：arXiv:2608.19652（待核）——C1 冲突裁决（supersede 后不再引用旧值）以其为验收靶子。
  • 何时该忘 / scope 门控：arXiv:2602.01146（待核）；呈现层缓解见 arXiv:2608.08300（待核）。
  • 综述：arXiv:2603.07670（待核）——「写入 / 管理 / 读取」三段式与插件整体形状互证。
  • 可靠性工程：arXiv:2609.05510（待核）——与 sha256 审计链、fail-safe 降级同属「记忆即基础设施」。

一句话推荐结论

如果你用 DeepSeek Harness 且需要跨会话记忆——尤其是需要"记忆可审计、可回放、冲突不擅自裁决、记忆只落本机"——dsh-mneme 是当前 DSH 生态里少数同时给出"治理范式 + 学术近亲 + 离线优先 + MCP 生态"的方案，值得装来试；v0.9.x 的 M.O. 是 beta，按项目级工作流的需求慎用。

参考

  • 仓库主页：https://github.com/slow-stack/mneme
  • npm 包：https://www.npmjs.com/package/@modusensus/dsh-mneme
  • 插件完整文档：https://github.com/slow-stack/mneme/blob/main/dsh-mneme/README.md
  • 配置全键参考：https://github.com/slow-stack/mneme/blob/main/dsh-mneme/docs/CONFIGURATION.md
  • 与 Zep / Mem0 / Letta / Hindsight 对照：https://github.com/slow-stack/mneme/blob/main/docs/COMPARISON.md
  • 版本历史：https://github.com/slow-stack/mneme/blob/main/dsh-mneme/CHANGELOG.md
  • 安全策略：https://github.com/slow-stack/mneme/blob/main/SECURITY.md
  • 学术脉络：arXiv:2504.13171（Sleep-time Compute，已核实）、arXiv:2501.13956（Zep，已核实）
  • 当前版本：v0.9.2（2026-10-19 周报所示最新）
  • Stars 数：160（采集时 2026-10-19）