@cup319/dsh-mmpl

MMPL (Memory Palace) memory plugin for DeepSeek Harness — connects the Rust DuckDB vector-memory MCP server via Streamable HTTP.

Plugin vs MCP — how this fits into dsh

DSH plugins and MCP servers are two integration surfaces that end at the same place: the model's tool list (ctx.tools).

• A native plugin is an in-process Cordis module (apply(ctx)) packaged as a bundle (dsh.bundle.patch in package.json). It registers tools, commands, and web panels directly.
• An MCP server is an external process/endpoint. The official @deepseek-ai/dsh-mcp-client — itself a native plugin — bridges it: it lists the server's tools and re-registers them as mcp__<serverName>__<tool>.

This package mounts the official MCP client against your MMPL server with sane defaults, then adds the lifecycle glue in-process. Memory logic (forgetting curve, retrieval, compression) stays server-side in Rust — one MMPL server can be shared by dsh, Claude Code, Codex, and anything else that speaks MCP, each seeing the same memories.

What it does

Three layers:

1. Tools (bundle patch) — mounts the shared @deepseek-ai/dsh-mcp-client against a running MMPL server, exposing its 9 memory tools as mcp__mmpl__*:

   • memory_write / memory_search / memory_list
   • memory_manage / memory_stats / memory_evolve
   • memory_compress / memory_palace / memory_symbol

2. Native lifecycle glue (index.js) — the official MCP client only bridges tools (it ignores MCP instructions), so this plugin adds what Hermes gets from its MemoryProvider hooks:

   • 常驻热记忆：ctx.systemPrompt.section() + variable() 注册 mmpl:hot-memory 段（order 60），内容来自 GET /admin/api/context，默认 300 token，后台每 5 分钟刷新。
   • 每轮捕获 L0：监听 session/event 的 turn/start / user/message / assistant/message / turn/end，turn 结束时把 U: …\nA: … POST 到 /admin/api/capture（≤4000 字符，sha1 去重）。

3. 连接与守护（v3.5.0） — 插件设置页（Settings）新增三个可编辑字段，均持久化到 profile patch：

   • url：MCP 端点，默认 http://127.0.0.1:7680/mcp，可填远端服务器。
   • authToken（密文显示）：Bearer token，自动同步到 memory-mmpl 条目的 headers.authorization。
   • autoStart（默认开）：URL 指向本机（127.0.0.1/localhost）且端口未监听时，自动拉起本机已安装的 @cup319/mmpl 服务端（隐藏后台进程，60s 冷却重试）；远端 URL 永远不会启动本地进程。
   • 启动时在日志打印后台管理网址（<base>/admin）。

4. 管理面板镜像（v3.11.0，多标签 + 增删改） — 双入口 + 七个标签，样式走 DSH 主题变量（浅色/深色自动跟随）：

   • 入口①（v3.12.0）：侧栏顶层页面——main 槽（key=mmpl）+ sidebar.panellist 槽（同 id、order=1、自带 SVG 图标），与「Plugins / Automation tasks」并列的独立入口，web 与桌面端一致（对齐内置 plugin-manager 的注册配方）。
   • 入口②：Plugins → @cup319/dsh-mmpl 插件详情页（plugins.bundle.config 槽）。
   • 入口③：设置窗口左菜单「MMPL 记忆」（settings.section 槽，桌面端设置窗）。
   • 总览：八张统计卡片——常驻记忆、L0 原始记录、技能库、检索账本、演化管道、服务信息，加遗忘曲线（S/复习增益/三道保留线/永久数/启停）与向量模型（当前档位维度/文件/就绪档数），30 秒自动刷新。
   • L1 记忆 / L2 场景 / L3 画像 / L0 原始 / 技能库：与后台表格同构的列表，支持新建/编辑/删除——L1（内容/类型/永久）、L2 场景（名称/摘要/成员记忆 ID）、L3 画像（画像文本改写 + 槽位增删改）、L0 原始（内容/类型）、技能库（名称/描述/正文/触发词/启停）。删除有确认框，操作结果 toast 反馈；编辑 L1 内容自动走版本链并重嵌入。
   • 模型（v3.13.0）：四档向量模型（small/base/m3/qwen3）就绪状态、体积与说明一览，就地下载 / 设为当前（同后台 /admin/api/models/download：已就绪仅记录选择，未就绪后台下载 3s 轮询进度，重启 mmpl 生效）。
   • 本地服务端安装（v3.13.0）：连接页顶部显示本地服务端检测状态（已装版本 + 路径）；未装且 URL 为本机地址时提供一键安装（npm i -g @cup319/mmpl@latest，经插件宿主执行，远端 URL 永远不出安装钮）。autoStart 拉起服务端时 DATA_DIR 取 dataDir 配置 → 环境变量 → 默认 ~/.mmpl/data（不再依赖进程 cwd，杜绝看门狗重启落到空库）。
   • 数据通路：GET /api/dsh-mmpl/admin/* 只读查询 + POST/PUT/DELETE 写透传（自动带 Bearer token、无 CORS、路径白名单、body 上限 2MB）。
   • 服务离线时显示诚实横幅（错误原因 + 重试 + 跳转配置），不静默伪装。
   • v3.7.1 实机修复：package.json 补 "." 主导出（宿主按包名 import 原生模块，缺它整包不激活）；client.js 插件 API 双写兜底（module.exports 与 exports 都挂）；宿主 volatile 配置字段可能以对象形态传入，bridge 读写全程消毒，杜绝 [object Object] 毒 URL 自续。

Everything is best-effort: if a service/hook is missing or MMPL is down, the plugin stays inert and the MCP tools keep working.

MMPL's Ebbinghaus forgetting curve, "memory palace" (archived-memory palace with confirm-before-purge), BM25 + ONNX semantic vector retrieval, and RRF fusion all live server-side — this bundle only wires the connection.

自动记忆（原生，对齐 Hermes）

官方 @deepseek-ai/dsh-mcp-client 只桥接工具、不读 MCP instructions；本插件在 index.js 补了两层原生逻辑：

能力	实现	行为
常驻热记忆	ctx.systemPrompt.section() + variable()	把 GET /admin/api/context 的热块注入系统提示（默认 300 token，后台每 5 分钟刷新）
每轮捕获 L0	ctx.on('session/event')	turn/end 时把 U: …\nA: … POST 到 /admin/api/capture，进入 L0 后管道自动跑 L1→L3

服务或事件不可用时插件静默降级，MCP 工具照常可用。临时关闭：

MMPL_CONTEXT_TOKENS=0 dsh ...      # 不注入热块
MMPL_CAPTURE_TURNS=false dsh ...   # 不自动捕获

老版本 DSH 若没有 ctx.systemPrompt，用规则文件兜底（写进 workspace AGENTS.md）：

## MMPL 记忆
- 每轮开始前调用 `mcp__mmpl__memory_search`，参数 {"mode":"context","token_budget":300}，把返回的 text 当作已知背景。
- 每轮结束调用 `mcp__mmpl__memory_write`，参数 {"action":"capture","content":"U: <用户原文>\nA: <助手回复>","record_type":"conversation"}，把真实对话落到 L0。
- 重要事实/偏好用 {"action":"encode","input":"...","type":"preference"} 沉淀为长期记忆。

通用做法（包括没有 hook 的 IDE）见 ../generic/README.md。

Prerequisites

A running MMPL server at http://127.0.0.1:7680/mcp. With autoStart on (default) and a loopback URL, the plugin launches it for you when it finds a local @cup319/mmpl install (env MMPL_HOME, require.resolve, or the global npm root — install once with npm and forget). It never downloads or builds anything.

Install the server separately:

# npm (Rust single-binary edition)
npm install -g @cup319/mmpl
mmpl   # → http://127.0.0.1:7680/mcp

Install into a DSH profile

dsh plugin --profile <name> add @cup319/dsh-mmpl
dsh --profile <name>

Configuration

Primary configuration is the plugin's Settings page (volatile schema fields, persisted into the profile patch); the env vars remain as bootstrap/fallback overrides.

Setting 字段	默认	说明
url	http://127.0.0.1:7680/mcp	MCP 端点；改后插件自动把 memory-mmpl 条目同步为新端点
authToken	—	Bearer token（密文）；自动写入 memory-mmpl 条目的 headers.authorization，清空则移除
autoStart	true	本机 URL 且端口未监听时自动拉起 @cup319/mmpl；远端 URL 忽略

Env	Default	Purpose
MMPL_URL	http://127.0.0.1:7680/mcp	Override the MCP endpoint (remote host / proxy); native layer derives /admin/api/* from it
MMPL_AUTH_TOKEN	—	Bearer token for native /admin/api/* calls
MMPL_AUTOSTART	true	Supervisor fallback when the Settings field is untouched
MMPL_CONTEXT_TOKENS	300	Hot-memory budget in tokens (0 disables prompt injection)
MMPL_CONTEXT_REFRESH_MS	300000	Hot-memory refresh interval (min 30000)
MMPL_CAPTURE_TURNS	true	Capture finished turns to L0 (false disables)

Setting 优先于环境变量。MCP 工具调用的鉴权头由插件按 authToken 自动同步到 memory-mmpl 条目（经 host config-editor 写回 profile patch），无需再手改 cordis.patch.yml。

MMPL v3.3.6 起默认鉴权（监听 0.0.0.0 时自动生成 DATA_DIR/auth-token）。把该 token 填进插件设置页的 authToken 字段即可——插件会同时用于本地 /admin/api/* 调用和 memory-mmpl 条目的 headers.authorization。用 HOST=127.0.0.1 启动 MMPL 则不需要。

Verify

1. Session A: "Remember that my validation drink is lapsang-."（模型用 mcp__mmpl__memory_write 写入）
2. 后台 /admin → 「L0 原始记录」应出现本轮 U: … / A: …（原生捕获生效）
3. Session B: 直接问 "What is my validation drink?"（不说"查记忆"）——热块已注入系统提示时可直接答；否则模型会调 memory_search 兜底

若第 2 步没有记录：确认 MMPL_CAPTURE_TURNS 未被设为 false、MMPL 在 MMPL_URL 可达；若第 3 步仍需显式检索：确认 DSH 有 ctx.systemPrompt 服务（rc.5 的 base/headless/web profile 均内置），否则用 AGENTS.md 规则兜底。

Plugin marketplace (awesome-dsh-plugin)

To be listed in the awesome-dsh-plugin catalog (dsh-plugin-catalog on npm), submit a PR to awesome-dsh-plugin/awesome-dsh-plugin adding one file data/plugins/<owner>__<repo>.yml:

url: https://github.com/<owner>/MMPL          # GitHub repo hosting this package
name: <owner>/MMPL#dsh-mmpl                    # monorepo subpackage form
category: memory
description:
  en: Connects DeepSeek Harness to the external MMPL Rust DuckDB vector-memory
    MCP server via the official MCP client bridge, exposing 9 memory tools.
  zh: 通过官方 MCP 客户端桥接，将 DeepSeek Harness 连接到外置的 MMPL Rust DuckDB
    向量记忆服务器，提供 9 个记忆工具。

Requirements checked by their CI: dsh.bundle declared in package.json (✅), repo ≥1 day old, dsh-plugin topic on the repo, description factual and verifiable against source.

Note

This is an independent community integration, not an official DeepSeek or MMPL endorsement. See examples/mcp-memory in the deepseek-harness repo for the reference integration pattern.