dsh-tool-user-memory

dsh plugin --profile web add dsh-tool-user-memory

dsh-tool-user-memory

[![npm 版本][badge-npm]][npm-url] [![GitHub Release][badge-release]][release-url] [![MIT License][badge-license]](LICENSE)

让 [DeepSeek Harness][harness] 记住你的偏好和项目背景，跨会话复用，换电脑也能迁移。

记忆保存在本地 Markdown 文件中，可以直接查看、编辑和备份。本项目由社区独立开发和维护。

[English](README.en.md) · [npm][npm-url] · [更新日志](CHANGELOG.md) · [Release v0.4.0][release-url]

核心特点

能力 · 说明

跨会话记忆 · 保存语言、沟通方式和长期偏好，有效内容按预算注入系统提示词

DSH 内管理 · 在当前窗口查看、搜索、新增、编辑和删除记忆

记忆置顶 · 重要偏好优先显示与注入，容量淘汰不会移出或截短置顶内容

项目隔离 · 分别保存项目约定；支持目录、Git 根目录或指定项目

跨电脑迁移 · JSON 导出与导入，目录映射、冲突预览、自动备份和撤销

修改保护 · 写入前保存历史；容量淘汰与截短前归档完整正文

生命周期管理 · 关键词检索、软失效、陈旧标注，以及默认关闭的自动整理

本地诊断 · 检查存储位置、项目身份和数量，排查配置与读取问题

配色跟随 DSH

弹窗只保留概览、记忆、迁移三个区域，直接读取 DSH 的配色和字体变量。

深色 · 浅色

![DSH 深色主题中的记忆概览][image-dark] · ![DSH 浅色主题中的记忆概览][image-light]

截图来自本地 DSH 网页版，使用演示记忆。

快速开始

在已安装 DeepSeek Harness 的环境中运行：

dsh plugin --profile web add dsh-tool-user-memory@0.4.0

将 web 替换为实际 profile。安装或升级后重启 DSH；网页模式需重启 dsh web。已有记忆文件可继续读取，无需手动迁移。

1. 打开插件 → dsh-tool-user-memory → 配置 → 管理记忆。

2. 进入记忆，新增一条用户记忆，例如“默认用中文回答，先给结论”。

3. 开启新会话，调用 memory_get 核验已保存的偏好。

也可告诉 agent：“使用 memory_update 保存我的回答偏好：默认用中文，先给结论，再解释细节。”

插件默认启用工具和提示词注入；自动整理默认关闭。记忆保存成功不代表模型每次都会准确遵循，可以先通过工具验证存储和读取。

记忆管理与置顶

• 概览：查看用户记忆、项目主题和画像容量。
• 记忆：切换用户或项目范围，关键词筛选，查看全文、新增或编辑。
• 编辑框：保存、取消；删除需再次确认。
• 迁移：导出、选择导入文件、映射项目、预览和确认导入。

置顶重要偏好

打开一条用户记忆的编辑框，勾选置顶记忆并保存；取消勾选后保存即可取消置顶。项目记忆暂不提供置顶选项。

置顶后的行为 · 规则

优先显示 · 用户列表和 memory_get 优先返回置顶条目

优先注入 · 同组条目置顶优先，其次按更新时间从新到旧；仍受 promptMaxBytes 限制

容量保护 · 不自动淘汰或截短置顶内容；置顶集合本身超出 maxBytes 时拒绝保存，原内容不变

保留内容年龄 · 仅切换置顶不改变条目内容更新时间，也不恢复失效条目

随迁移保留 · 新版 JSON 保存 pinned；导入、备份和历史恢复保留状态

置顶保护针对容量淘汰。手动修改、删除和整理规则仍可改变条目；失效记忆即使置顶也不注入。置顶不保证全文总能进入上下文，超出提示词预算仍可能截短或省略。

0.3.0 等旧客户端可读取正文，但不执行置顶保护，重新保存或导出可能丢失置顶状态。回退前请保留新版导出及完整存储备份。

换电脑：导出与导入

在 DSH 弹窗中迁移

1. 旧电脑：管理记忆 → 迁移，导出 JSON。

2. 通过 U 盘或你选择的方式，把文件传到新电脑。

3. 新电脑：选择 JSON，将旧项目对应到本机已经存在的项目目录。

4. 查看新增、同名冲突和未映射项目的预览，再确认导入。

5. 检查结果；需要撤销时，使用界面保留的导入备份恢复。

界面默认保留本机同名记忆。相同内容不重复创建；未映射项目列出并跳过。预览后目标记忆或文件发生变化，需要重新预览。导入前备份待修改文件；导入后又被修改的文件会阻止撤销，避免覆盖新内容。

旧电脑不方便升级：使用独立命令

旧电脑无需升级 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

…(truncated)