dsh-tool-user-memory
Agent 与工作流IAMLieutenant/dsh-tool-user-memory
DeepSeek Harness 用户偏好记忆插件，让代理跨会话记住语言习惯、沟通风格、项目背景和目标。
- deepseek-harness
- deepseek-harness-plugin
- deepseek-harness-plugins
- dsh-plugin
- dsh-plugins
验证与兼容性
这里展示目录实际采集到的证据；未声明的信息会明确标为未知。
- 当前版本兼容性
- 已在当前目录版本验证
- 声明的 Harness 范围
- 未声明
- 声明的平台
- 未声明
- 适用 Profile
- web
- 构建授权
- 未知
- 权限声明
- 未声明
- 外部服务
- 未声明
- 遥测声明
- 未知
这不是安全背书；安装前仍应查看源码、权限和配置。
查看证据与判定范围
验证仅覆盖标出的来源、版本和 Harness 环境，不代表未来版本仍然兼容。
dsh-tool-user-memory@0.1.2- 插件通过清单与静态结构检查，尚未完成运行时加载检查。
README
dsh-tool-user-memory
让 DeepSeek Harness 记住你的偏好和项目背景，跨会话复用，换电脑也能迁移。
记忆保存在本地 Markdown 文件中，可以直接查看、编辑和备份。本项目由社区独立开发和维护。
English · npm · 更新日志 · Release v0.4.0
核心特点
| 能力 | 说明 |
|---|---|
| 跨会话记忆 | 保存语言、沟通方式和长期偏好，有效内容按预算注入系统提示词 |
| DSH 内管理 | 在当前窗口查看、搜索、新增、编辑和删除记忆 |
| 记忆置顶 | 重要偏好优先显示与注入，容量淘汰不会移出或截短置顶内容 |
| 项目隔离 | 分别保存项目约定；支持目录、Git 根目录或指定项目 |
| 跨电脑迁移 | JSON 导出与导入，目录映射、冲突预览、自动备份和撤销 |
| 修改保护 | 写入前保存历史；容量淘汰与截短前归档完整正文 |
| 生命周期管理 | 关键词检索、软失效、陈旧标注，以及默认关闭的自动整理 |
| 本地诊断 | 检查存储位置、项目身份和数量，排查配置与读取问题 |
配色跟随 DSH
弹窗只保留概览、记忆、迁移三个区域，直接读取 DSH 的配色和字体变量。
| 深色 | 浅色 |
|---|---|
 |  |
截图来自本地 DSH 网页版，使用演示记忆。
快速开始
在已安装 DeepSeek Harness 的环境中运行：
dsh plugin --profile web add dsh-tool-user-memory@0.4.0
将 web 替换为实际 profile。安装或升级后重启 DSH；网页模式需重启 dsh web。已有记忆文件可继续读取，无需手动迁移。
- 打开插件 → dsh-tool-user-memory → 配置 → 管理记忆。
- 进入记忆，新增一条用户记忆，例如“默认用中文回答，先给结论”。
- 开启新会话，调用
memory_get核验已保存的偏好。
也可告诉 agent：“使用 memory_update 保存我的回答偏好：默认用中文，先给结论，再解释细节。”
插件默认启用工具和提示词注入；自动整理默认关闭。记忆保存成功不代表模型每次都会准确遵循，可以先通过工具验证存储和读取。
记忆管理与置顶
- 概览：查看用户记忆、项目主题和画像容量。
- 记忆：切换用户或项目范围，关键词筛选，查看全文、新增或编辑。
- 编辑框：保存、取消；删除需再次确认。
- 迁移：导出、选择导入文件、映射项目、预览和确认导入。
置顶重要偏好
打开一条用户记忆的编辑框，勾选置顶记忆并保存；取消勾选后保存即可取消置顶。项目记忆暂不提供置顶选项。
| 置顶后的行为 | 规则 |
|---|---|
| 优先显示 | 用户列表和 memory_get 优先返回置顶条目 |
| 优先注入 | 同组条目置顶优先，其次按更新时间从新到旧；仍受 promptMaxBytes 限制 |
| 容量保护 | 不自动淘汰或截短置顶内容；置顶集合本身超出 maxBytes 时拒绝保存，原内容不变 |
| 保留内容年龄 | 仅切换置顶不改变条目内容更新时间，也不恢复失效条目 |
| 随迁移保留 | 新版 JSON 保存 pinned；导入、备份和历史恢复保留状态 |
置顶保护针对容量淘汰。手动修改、删除和整理规则仍可改变条目；失效记忆即使置顶也不注入。置顶不保证全文总能进入上下文，超出提示词预算仍可能截短或省略。
0.3.0 等旧客户端可读取正文，但不执行置顶保护，重新保存或导出可能丢失置顶状态。回退前请保留新版导出及完整存储备份。
换电脑：导出与导入
在 DSH 弹窗中迁移
- 旧电脑：管理记忆 → 迁移，导出 JSON。
- 通过 U 盘或你选择的方式，把文件传到新电脑。
- 新电脑：选择 JSON，将旧项目对应到本机已经存在的项目目录。
- 查看新增、同名冲突和未映射项目的预览，再确认导入。
- 检查结果；需要撤销时，使用界面保留的导入备份恢复。
界面默认保留本机同名记忆。相同内容不重复创建；未映射项目列出并跳过。预览后目标记忆或文件发生变化，需要重新预览。导入前备份待修改文件；导入后又被修改的文件会阻止撤销，避免覆盖新内容。
旧电脑不方便升级：使用独立命令
旧电脑无需升级 DSH 插件，也能使用新版导出工具。按终端类型选择：
Windows 命令提示符（CMD，通常显示 C:\...>）：
npx --yes --package=dsh-tool-user-memory@0.4.0 dsh-memory export --file "%USERPROFILE%\dsh-memory.json"
PowerShell（通常显示 PS C:\...>）：
npx --yes --package=dsh-tool-user-memory@0.4.0 dsh-memory export --file "$env:USERPROFILE\dsh-memory.json"
CMD 使用 %USERPROFILE%，PowerShell 使用 $env:USERPROFILE，不要混用。导出拒绝覆盖已有文件，再次导出请换文件名。DSH 可以保持打开；为取得更一致的快照，导出期间暂停修改记忆。
首次 npx 可能需要下载包及依赖；缓存完整后可加 --offline。导出最大 16 MiB，不读取账号配置或凭据文件，不会自行上传记忆。
命令行预览、执行与恢复
PowerShell 示例；项目 ID 来自导出结果或预览，目标目录必须存在：
# 只预览，不写入
npx --yes --package=dsh-tool-user-memory@0.4.0 dsh-memory import --file "$env:USERPROFILE\dsh-memory.json" --map "项目ID=C:\projects\demo"
# 确认后使用相同选项，加入返回的 token
npx --yes --package=dsh-tool-user-memory@0.4.0 dsh-memory import --file "$env:USERPROFILE\dsh-memory.json" --map "项目ID=C:\projects\demo" --apply --token "返回的previewToken"
# 恢复此次导入前的文件
npx --yes --package=dsh-tool-user-memory@0.4.0 dsh-memory rollback --file "返回的backupPath"
| 选项 | 用途 |
|---|---|
--global-only | 导出时只携带用户记忆 |
--skip-profile | 导入时跳过用户记忆 |
--map "ID=目录" | 项目映射，可重复指定 |
--policy keep-local | 保留本机同名内容，默认策略 |
--policy use-imported | 明确用导入内容替换同名记录 |
--profile <文件> | 自定义画像文件 |
--workspace-base <目录> | 自定义项目记忆根目录 |
--max-bytes <数字> | 自定义画像容量 |
--workspace-mode git-root | 按 Git 根目录定位项目，默认 directory |
CLI 默认读取 $DSH_HOME/user-memory；未设置时为 ~/.dsh/user-memory。CLI 不会读取 DSH 插件配置，自定义存储、容量或项目模式需要传入对应选项；DSH 工具和内置弹窗使用插件配置。
导入超出画像或主题容量时拒绝操作，不自动淘汰记忆。导出包和单次导入备份均限制 16 MiB。可处理的写入错误自动回滚；强制终止进程可能留下部分写入，可检查画像目录的 migration-backups/*.json。仍兼容 0.3.0 的版本 1 导出，缺省置顶状态为未置顶。
配置参考
默认配置即可使用。需要调整时，在 profile 的 cordis.patch.yml 中覆盖 id 为 tool-user-memory 的配置项。下表展示有效默认路径；配置中的空路径表示默认位置。
| 配置项 | 默认值 | 说明 |
|---|---|---|
path | $DSH_HOME/user-memory/user.md | 用户画像文件 |
maxBytes | 8192 | 画像文件字节上限，整数，1–16 MiB；非置顶条目先失效、再从旧到新淘汰，原文先归档 |
promptMaxBytes | 2048 | 画像正文注入预算，置顶优先；0 注入完整有效画像 |
includeInPrompt | true | 启用画像和项目索引注入；关闭后工具仍可读取 |
staleAfterDays | 0 | 超过指定天数未更新时添加陈旧标注，不删除；0 关闭 |
workspacePromptMaxBytes | 512 | 项目索引正文预算；0 关闭项目索引注入 |
workspaceBase | $DSH_HOME/user-memory/workspace | 项目记忆根目录 |
workspaceMode | directory | 按会话目录；git-root 使用最近 Git 根目录，无仓库时用当前目录 |
projectPath | '' | 显式指定已存在的项目目录，优先于会话目录及项目模式 |
autoConsolidate | false | 在回合边界异步触发自动整理 |
consolidateMinIntervalMs | 600000 | 自动整理最小间隔，毫秒；0 不限制 |
autoInvalidateAfterDays | 0 | 整理时软失效超过指定天数未更新的记录；0 关闭 |
consolidateProvider | '' | 可选模型辅助整理的 provider |
consolidateModel | '' | 模型辅助整理的 model id |
consolidateMaxTokens | 1024 | 一次整理模型调用的输出 token 上限 |
consolidationLogPath | $DSH_HOME/user-memory/consolidation-log.md | 整理审计日志 |
字节数不等于 token 数；提示词说明文字另计。项目主题正文最多 16 KiB，超限追加拒绝并保留原内容。maxBytes 不限制项目、历史、归档或日志总大小。超出注入预算的正文可通过 memory_get 或 memory_topic 按需读取。
默认目录模式下，子目录可能拥有独立记忆；Git 根目录模式让同仓库子目录共享记忆。切换模式或指定 projectPath 不自动合并旧记忆，可通过迁移完成目录对应。
记忆工具参考
插件向 agent 注册八个工具。项目工具使用会话目录或显式配置的项目路径。
| 工具 | 参数 | 能力 |
|---|---|---|
memory_get | query?, limit?（默认 50，最多 100）, includeStale? | 读取画像，置顶优先；默认排除失效记录 |
memory_update | key, value, mode?, reason?, scope? | 保存、追加、失效或删除；默认 global、set |
memory_search | query?, limit?（默认 10，最多 20）, includeStale? | 检索画像与当前项目，支持中文子串，返回评分与摘要 |
memory_topic | topic | 读取项目主题全文和失效信息 |
memory_consolidate | mode?（默认 plan）, useModel? | 预览或执行整理，模型辅助需配置 provider 与 model |
memory_export | destination, scope?（默认 all） | 导出本机 JSON；global 只导出画像 |
memory_import | source, includeProfile?, projectMap?, policy?, dryRun?, previewToken? | 默认预览并保留本机内容，执行需有效预览 token |
memory_status | 无 | 返回实际存储路径、项目身份和数量，不返回正文、不调用模型 |
memory_update 的 mode：set 覆盖、append 追加，均恢复有效；invalidate 保留原文与原因；remove 移除活动记录。后两者的 value 可为空。普通更新保留置顶状态，置顶开关由界面控制。写入结果返回容量淘汰、截短与归档信息。
includeStale=true 用于查看软失效记录；陈旧标注仍表示有效。项目正文按需读取，每轮只注入索引。主题名最多 64 字符，禁止路径分隔符、保留字符、MEMORY 和 Windows 保留设备名。
检索评分：主题名命中 3 分，正文每次 1 分、最多 5 分，全部关键词命中再加 4 分。尚未提供语义检索。
可选记忆整理
确定性规则合并重复记录（最新保留，其余失效），为相对时间补充绝对记录日期，按配置报告陈旧或失效旧内容。模型辅助校验 add、merge、rewrite、invalidate、topic-add、topic-invalidate 提案；模型不可用或响应非法时退回确定性规则。
plan 只返回方案；apply 执行并记审计日志。执行前核验内容和置顶状态，跳过已变化的条目，避免旧方案覆盖新修改。模型辅助把待整理记忆发送给配置的 provider，并产生模型调用费用。
数据存储、历史与备份
$DSH_HOME/user-memory/
├── user.md # 用户画像
├── .history/<file-hash>/ # 每文件最近 20 份写入前快照
├── .archive/<file-hash>/ # 淘汰或截短前的完整条目
├── migration-backups/ # 导入备份与恢复记录
├── consolidation-log.md # 整理审计日志
└── workspace/<project-hash>/
├── MEMORY.md # 有效主题索引
├── <topic>.md # 主题正文与元数据
└── .history/<file-hash>/ # 主题写入前快照
Windows 默认画像为 C:\Users\<用户名>\.dsh\user-memory\user.md；自定义路径时以实际配置为准。默认不写入项目仓库。项目标识为有效目录 realpath 的 SHA-256 前 16 位；Windows 按小写处理，Linux 保留大小写。主题写入后重建索引。
| 状态或操作 | 行为 |
|---|---|
| 有效 | 参与注入和默认检索 |
| 陈旧 | 添加时间标注，仍有效 |
| 软失效 | 保留正文与原因，停止注入，默认检索隐藏 |
| 删除 | 移除活动记忆，停止后续注入；写入前历史仍保留 |
| 容量淘汰或截短 | 只处理非置顶条目，先归档完整原文 |
历史与归档在后台保存，精简界面暂不提供历史浏览或归档恢复入口；恢复能力由存储与管理后端提供。归档达到 1000 份或 64 MiB 后拒绝继续写入，不自动删除旧归档。手动编辑 Markdown 不生成快照，应保留标题、时间和置顶元数据；格式损坏可能拒绝读取。
JSON 包含画像、主题、更新时间、失效与置顶状态；不包含历史、归档、整理日志和账号配置。完整备份请另行复制实际存储目录。导出、历史和备份含记忆正文，请按个人资料保存。
删除不等于永久清除；彻底清除还需处理相关历史、归档、迁移备份、整理日志及另存导出文件。
诊断与故障排查
在 DSH 中用 memory_status 检查实际配置。独立命令：
npx --yes --package=dsh-tool-user-memory@0.4.0 dsh-memory doctor --cwd "项目目录"
npx --yes --package=dsh-tool-user-memory@0.4.0 dsh-memory manage
doctor 检查存储和项目身份；管理后端支持当前提示词预览。独立 manage 输出本机管理页地址，只监听本机，Ctrl+C 关闭。DSH 网页版使用内置弹窗。自定义配置仍需传入对应选项。
| 问题 | 检查方式 |
|---|---|
| 新会话没用记忆 | profile、路径、includeInPrompt、失效状态及预算；用 memory_get 核验 |
| 找不到项目记忆 | 会话目录、项目模式、projectPath 和迁移映射 |
| 没有管理入口 | 确认 0.4.0、重启 DSH 网页服务，并启用插件客户端 |
| 置顶容量不足 | 缩短内容、取消部分置顶或提高 maxBytes；失败时原画像不变 |
| 内容已发生变化 | 刷新，或重新预览后再确认 |
导出报 ENOENT | 检查路径、权限，勿混用 CMD 与 PowerShell 变量 |
首次 npx 较慢 | 检查 npm 网络；缓存完整后可用 --offline |
提示词把记忆标注为参考数据并要求模型不执行其中的指令，但不能保证所有模型遵守。插件没有覆盖所有敏感内容的自动过滤器，请勿保存密码、密钥或令牌。真实模型的记忆提取、使用及长期准确性仍需实际评估。
开发与验证
git clone https://github.com/IAMLieutenant/dsh-tool-user-memory.git
cd dsh-tool-user-memory
pnpm install --frozen-lockfile
pnpm test
pnpm run build
pnpm pack
dsh plugin --profile web add ./dsh-tool-user-memory-0.4.0.tgz
| DSH 依赖版本 | 测试 | 构建 |
|---|---|---|
0.1.7-alpha.1 | 127/127 通过 | 通过 |
0.2.0-rc.2 | 127/127 通过 | 通过 |
测试覆盖解析、置顶保护、预算、并发锁、存储、项目身份、整理、迁移恢复、管理后端、Harness 和 AgentLoop 集成；循环测试使用固定模型响应。在真实 DSH 0.1.7-alpha.1 网页版验证了深浅主题、打开/关闭、取消、查看/保存、置顶/取消置顶和容量拒绝。依赖兼容测试不等于全部客户端实机验证。
| 文件 | 职责 |
|---|---|
src/index.ts | 配置、服务装配、工具注册和自动整理 |
src/profile.ts / src/store.ts | 格式、置顶、容量、渲染和持久化 |
src/lock.ts / src/history.ts | 并发、快照和归档 |
src/workspace.ts / src/prompt.ts | 项目、索引、检索和注入 |
src/consolidate.ts / src/tools.ts | 整理和记忆工具 |
src/migration.ts / src/migration-tools.ts | 导出、预览、备份和回滚 |
src/manager.ts / src/manager-web.ts | 管理操作和本机 HTTP 接口 |
src/manager-ui.ts / src/client.js | 界面、DSH 入口和主题同步 |
src/migrate-cli.ts / scripts/build-assets.mjs | 独立命令和客户端构建 |
版本演进
| 版本 | 主要变化 |
|---|---|
0.1.x | 用户画像和跨会话注入 |
0.2.x | 项目、检索、失效、时间标注、整理和并发修复 |
0.3.0 | JSON 迁移、目录映射、预览、冲突策略、备份和回滚 |
0.4.0 | DSH 内弹窗、置顶、主题同步、历史归档、迁移向导、项目身份和诊断 |
来源记录、用户确认的记忆候选、独立创建时间、项目优先级和可复现的效果评估是后续候选方向。语义检索和加密同步尚未实现，见 ROADMAP。问题与建议欢迎提交 Issues。
