前言¶
DeepSeek Harness（DSH）的智能体如果缺乏记忆，每次对话都是重新开始。已有的记忆插件要么只存一个文件，要么把所有东西一股脑注入，很快撑爆上下文。木偶记忆（Puppet Memory）解决的是这个问题：把记忆按用途分层，只在该进上下文时才写入，同时提供写入守卫、要点层、会话级管理等机制，保证记忆既持久又可控。
插件原名 dsh-memory，2026-10-20 更名。当前最新发布为 0.32.0（2026-10-24，兼容 DSH 0.2.1-rc.3），主分支是开发中的版本。维护者：xingyueDanYang。
五层记忆¶
记忆按用途分五层，分类轴是「什么时候进上下文」：
| 层 | 什么时候进上下文 | 放什么 |
|---|---|---|
| A 常驻 | 每轮（变了才追加，压缩后补回） | core.md（稳定事实）、core-rules.md（行为规则）、core-state.md（当前状态） |
| B 按需·行为 | 检索命中或注入时 | 人、关系、约定、偏好、人设 |
| C 按需·知识 | 要办事才翻 | 手册、梗、出处、结论型资料 |
| D 账本 | 要回查原话才翻 | 每回合流水、事件索引与会话清单、引导索引、摘要/要点视图 |
| E 临时 | 交接时看 | 便签 |
数据存放在 ~/.dsh/memory/，全部是纯文本文件，零依赖。
常驻层¶
常驻层有三张卡，优先级最高，优先从总预算里扣：
core.md：600 字核心记忆，每步缺就补core-rules.md：800 字行为规则core-state.md：400 字当前状态
按需·行为层¶
存放人、关系、约定、偏好、人设等，每轮注入时最多 1600 字符。关系条目超出预算时，保留最新的完整条目，旧条目自动转存到 deep/guide.jsonl（带日期标注，可用 memory_search layer=deep 查找）。
按需·知识层¶
手册、梗、出处、结论型资料，按需检索。
账本层¶
每回合一条流水，附带事件索引与会话清单。支持摘要/要点视图，可回读原文。
临时层¶
便签，用于交接或临时草稿，清空前自动归档。
核心记忆与注入控制¶
core.md 是 600 字常驻小卡，每步缺就补地注入，优先级最高。注入频率可切换：默认每步注入；切到 first-step 后只在会话里注入一次。
session-start 登记会话，pre-step 注入行为记忆摘要（人设、关系、最近笔记、最近日记），默认 ≤1600 字符，内容不变不重复注入。子代理会话跳过注入。
turn-stopping 把本回合压成一条日记 + 一条阵列索引（不调用模型）。disposed 会话结束时同步备份。
写入守卫与要点层¶
写入守卫会拒绝乱码（如 锟斤拷、替换字符、错编序列）、超长粘贴、把注入块整段复制进记忆，并说明原因。近似重复的便签/笔记自动合并，人设整行去重。
要点层在检索结果顶部先给 3 条「要点 + hash」速览，抽取式，不调模型、不花 token、不加存储。
三线状态、多人多群、会话管理¶
三线状态：工作 / 陪伴 / 学习，词表检测 + 半衰期衰减 + 话题锚点，只给定性，不给数字。
多人多群：人/群实体、身份归一（合并必须人确认）、四分区可见性、按场景注入，跨群默认不串台。
会话记忆管理：脏片段可在当前会话屏蔽（数据不删）或删掉（先归档），也可整会话暂停注入。
自动摘要、小模型路由与备份¶
自动摘要/事实候选：压缩后/会话结束压摘要；事实只提案，accept 才写记忆。
小模型路由：摘要/提炼可用独立 provider/model（本地 Ollama 等），失败自动回退主会话模型。
可移植性：默认备份到家目录、目录不可写自动回退、memory_doctor 一键自检。
图片记忆与声音记忆¶
图片记忆：人物设定、截图、示意图等「细节比描述重要」的东西，可以让图片跟着条目一起存。图片复制到 ~/.dsh/memory/assets/，按 sha256 命名（去重），支持 png / jpg / webp / gif / avif / bmp。memory_search 命中带图条目时，会直接列出图片的绝对路径。
声音记忆：语气、笑声、一段环境音、一句语音等，可以用 audios 参数带着音频一起存。音频复制到 ~/.dsh/memory/assets/，按 sha256 命名（去重），支持 mp3 / wav / m4a / aac / ogg / opus / flac / webm / amr。转写可选：调用时传 transcripts（与音频一一对应）；不传就自动读音频同目录同名 .txt。转写存进条目的 audios[].transcript，会参与 memory_search。
出处（provenance）¶
记一件事，除了「是什么」，还要记「谁说的、在哪看到的」。
文字条目：直接用条目的 source + quote 两个字段。source 是一行短串「作者@平台 ID」，如 蒙德砍壬@BV15X3n6mEWy。quote 是 verbatim（原文照抄）或 paraphrase（转述）。
媒体资产（图片/音频/视频截图）：登记在 behavior/sources.jsonl，一行一条，同一资产可挂多个出处。
安装与启用¶
- 下载插件压缩包
- 解压到本地任意位置
- 复制到 DSH 插件目录（通常是
~/.dsh/plugins/） - 重启 DSH
典型用法¶
写入核心记忆¶
memory_write layer=core keyword=大肥鱼形象 meaning="..." source="" quote=""
写入关系条目¶
memory_write layer=relation keyword="蒙德砍壬" meaning="..." source="蒙德砍壬@BV15X3n6mEWy" quote="verbatim"
写入带图片的条目¶
memory_write layer=relation keyword="大肥鱼两代形象" meaning="..." images=["D:\\Pictures\\v4.png"]
写入带音频的条目¶
memory_write layer=note text="深夜电台片段" audios=["D:\\Voice\\radio.m4a"] transcripts=["……这里是深夜电台，今晚聊聊记忆。"]
检索记忆¶
memory_search keyword="蒙德砍壬"
memory_search layer=deep keyword="炸盆子"
查看记忆统计¶
memory_stats
memory_image action=list
执行记忆自检¶
memory_doctor
适用场景与注意¶
适合需要长期维护对话上下文、需要按用途分类记忆、需要回查原话或出处、需要管理多人多群场景的开发者。
插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。
短结尾¶
木偶记忆通过五层记忆、写入守卫、要点层、三线状态、多人多群管理、会话级管理、自动摘要与小模型路由等机制，为 DSH 提供了一套完整的跨会话记忆解决方案。它不追求「记住一切」，而是让记忆只在需要时出现，避免上下文被撑爆。
