dsh-memory-manager
为 AI Agent 提供短期记忆缓存、长期知识沉淀、语义检索与持久化存储的统一记忆管理层
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:xiaoshi7915/dsh-memory-manager#a7010dbec00b06e68486e778ff1c001d19ce7d85Memory Manager 以 dsh-memory-manager 发布，当前版本为 1.0.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
面向 AI Agent 的统一记忆管理插件（DeepSeek Harness 生态）。短程滑动窗口记忆 + 长程向量记忆 + 语义/混合检索 + 智能摘要 + 生命周期管理（TTL / 重要性 / 存储上限 / 清理）+ 多会话隔离 + 全局记忆共享 + JSON/JSONL 导入导出，并附带可视化 Web 管理界面。
完整需求与验收口径见
TASK-spec.md。本插件本地优先、零云依赖，默认开箱即用（哈希+关键词降级），可配置真实嵌入模型提升语义精度。
| 能力 | 说明 |
|---|---|
| 🧠 短期记忆 | 每会话滑动窗口（消息条数 + Token 上限），超出自动截断/摘要 |
| 📚 长期记忆 | SQLite 元数据 + 自定义向量索引（node:sqlite 原生，零原生依赖） |
| 🔍 混合检索 | 向量（余弦）与关键词（词项重叠）加权融合，降级模式自动适配阈值 |
| ✂️ 智能摘要 | 本地抽取式摘要（可选 LLM 增强），生成 【对话摘要】 长期记忆 |
| ♻️ 生命周期 | TTL 过期、重要性评分、存储超限清理（LRU + 低重要性优先） |
| 🔒 会话隔离 | 默认仅本会话可见；is_global 记忆跨会话共享，可整体开关 |
| 🔐 安全 | 默认 AES-256-GCM 加密存储（主密码 scrypt 派生密钥） |
| ⇅ 导入导出 | JSON / JSONL 备份，合并 / 替换两种恢复模式 |
| 🌐 Web GUI | 记忆浏览 / 语义搜索 / 导入导出 / 设置 四面板，深浅双主题 |
dsh-memory-manager/
├── src/
│ ├── core/ # 核心引擎（类型/分词/短期/嵌入/向量/加密/存储/检索/摘要/生命周期/导入导出/统计/门面）
│ ├── tools/ # 7 个 Agent 工具（handlers.mjs + 定义）
│ ├── triggers/ # 触发词规则
│ ├── dsh/plugin.mjs # DSH 插件适配层（name/inject/apply）
│ └── server/ # 共享 REST 路由 + 独立服务器入口
├── gui/ # Web 界面（index.html 真实模式 / preview.html 独立预览 / css / js）
├── contracts/ # 工具契约（tools.md）与 Web API 契约（web-api.md）
├── scripts/ # seed-2000 / verify / smoke（含 md 报告）
├── review/ # UI 视觉验收
├── TASK-spec.md # 需求规格
├── ARCHITECTURE.md # 架构设计
└── PLAN.md # 实施计划与分工
环境要求：Node.js ≥ 22.5（使用内置 node:sqlite 与 crypto）。
# 1) 安装依赖（无运行时依赖，仅包元数据）
npm install
# 2) 独立演示/验收服务器（无需 DSH workspace）
npm run serve # 默认 http://127.0.0.1:4599，PORT 可覆盖
# 打开浏览器访问 http://127.0.0.1:4599/ 即可使用 Web GUI
数据目录默认 ~/.dsh/memory-manager/（P0 起与 dsh-layered-memory 解耦的专属目录；首次启动自动把旧 ~/.dsh/memory 中本插件白名单文件迁移过来，源文件保留为 *.migrated-<ts> 墓碑）。可用环境变量 DSH_MEMORY_DIR 覆盖：
~/.dsh/memory-manager/
├── config.json # 配置（自动生成默认值）
├── short_term/{session}.jsonl # 短期滑动窗口
├── long_term/
│ ├── memories.db # SQLite 元数据（内容默认加密）
│ ├── vector.index # 向量索引（原子写，崩溃不留半写）
│ └── embeddings/ # 嵌入模型缓存
├── .salt / .key # 加密盐与随机密钥
├── .lock # 单写者锁（防止插件/独立服务双写）
└── migration.json # 目录迁移审计记录
插件入口 src/dsh/plugin.mjs（export const name / inject / apply），基于真实 DSH API 实现：
@deepseek-ai/dsh-tools 的 defineTool + ctx.tools.register 注册 7 个 Agent 工具（含完整 parameters 参数 schema 与 output 输出 schema/渲染）ctx.webServer.register 挂载 /api/memory/* REST 路由ctx.on('session/event') 监听会话事件：写入短期记忆、超阈值自动摘要ctx.get('llm') 接入真实 LLM 生成式摘要（ctx.llm.stream + BlockAssembler），失败自动回退本地抽取式装载与验证（在 DSH workspace 内）：本项目 node_modules/@deepseek-ai/{cordis,dsh-tools,dsh-llm} 为指向 DSH checkout 真实包目录的 junction，使插件可用 DSH 的包树裸导入加载。
npm run integration # scripts/dsh-integration.mjs：真实 Cordis + ToolRuntime 装载插件，26/26 通过
从 GitHub 一键安装（推荐，发布后可用）：仓库声明了 dsh.bundle 清单（package.json → cordis.patch.yml），因此可直接用 DSH 的插件命令安装：
dsh plugin add xiaoshi7915/dsh-memory-manager
安装后验证：http://127.0.0.1:3080/api/memory/healthz 返回 200；GUI 面板在 http://127.0.0.1:3080/memory-manager/。
接入运行中的 DSH（本机开发验证，首次装载经 HMR 自动生效）：
~/.dsh/profiles/web/）下建 junction 指向本项目：
plugins\dsh-memory-manager → 本项目根目录（保证插件内部 @deepseek-ai/* 经本项目 junction 包树解析）。cordis.patch.yml 补丁层追加一条 insert（DSH 的 HMR 监听该文件，首次新增条目即事务性重载生效）：- insert:
- id: dsh-memory-manager
name: ./plugins/dsh-memory-manager/src/dsh/plugin.mjs
http://127.0.0.1:3080/api/memory/healthz 返回 200 即已生效；GUI 面板在
http://127.0.0.1:3080/memory-manager/（与 REST 同源 /api/memory/*，GUI 内四面板直接读写真实记忆）。⚠️ 更新插件代码后需重启 DSH 才加载：DSH 的 Cordis HMR 以
root: []运行（不监听用户插件代码文件）， 补丁配置重载不会清除 ESM 模块缓存（相对路径同名条目重导仍返回旧模块）。这是 DSH 运行时限制，非插件问题。
| 标准 | 要求 | 实测 |
|---|---|---|
| 1. 20 轮后引用第 3 轮信息 | 注入延迟 <100ms | ✅ 命中 + 25–36ms |
| 2. 跨会话偏好检索 | 相似度 >0.85 | ✅ 0.8908 |
| 3. 2000 条记忆 | Top-5 平均 <300ms；Top-1 直接相关 ≥90% | ✅ 平均 220ms / Top-1 90% / Top-5 100% |
复现：
npm run verify # 完整验收，输出 scripts/verify-report.md
npm run smoke # 端到端冒烟（工具 + REST），输出 scripts/smoke-report.md
npm run seed # 批量种入 2000 条演示记忆（默认 ~/.dsh/memory-manager）
降级模式说明：未配置真实嵌入模型时，检索以「哈希向量(0.25) + 关键词(0.75)」融合，并把配置阈值（默认 0.75）自适应映射到哈希尺度（
max(0.38, thr*0.5)），保证真实命中不被误杀；配置真实模型（local/OpenAI）后即用配置阈值。
| 段 | 键 | 默认 | 说明 |
|---|---|---|---|
short_term | max_messages | 20 | 窗口消息条数 |
max_tokens | 4000 | 窗口 Token 上限 | |
long_term | auto_summarize_threshold | 10 | 超过该消息条数自动摘要（0 = 关闭） |
retrieval_top_k | 5 | 检索返回条数 | |
similarity_threshold | 0.75 | 相似度阈值 | |
hybrid_weight | 0.7 | 向量占比（混合检索权重） | |
embedding_model | local | local / openai | |
embedding_model_id | '' | 留空 = 哈希降级 | |
openai_api_key | '' | OpenAI Key | |
llm_guardrails | 见下 | LLM 生成式摘要成本护栏 | |
storage | max_storage_mb | 500 | 存储上限（超限 LRU 清理） |
encryption_enabled | true | AES-256-GCM | |
master_password | '' | 主密码（scrypt 派生密钥） | |
api_token | '' | Web API 可选鉴权 | |
global_memory | enabled | true | 跨会话全局记忆开关 |
long_term.llm_guardrails 子项（生成式摘要的 LLM 成本护栏，超出自动回退本地抽取式摘要）：
| 键 | 默认 | 说明 |
|---|---|---|
max_concurrency | 1 | 全局并发上限；忙则回退抽取式，不排队阻塞会话链 |
fail_threshold | 3 | 连续失败熔断阈值 |
cooldown_ms | 600000 | 熔断冷却时长（毫秒） |
max_calls_per_hour | 30 | 小时调用上限 |
max_tokens_per_day | 50000 | 日 Token 预算（输入+输出近似；0 = 不限） |
/api/memory）healthz / stats / memories(GET, 列表) / memories/:id(GET/DELETE) / memories/delete(批量) / search / recent / summarize / memories/:id/importance(PATCH) / config(GET/POST) / export?format=json|jsonl / import / cleanup。详见 contracts/web-api.md。
node:sqlite、crypto、http），离线可用。@huggingface/transformers 或 OpenAI 后自动升级。term → {id, freq} 增量索引（启动构建一次，增删/导入实时维护；与存储失步时自愈重建），关键词检索从全表扫描降到命中集——2000 条下检索平均 ~104ms、峰值 <170ms。id → 明文 内存缓存加速。master_password 提供则 scrypt 派生，否则自动生成随机密钥（.key，0600）。