七层记忆库 Phant0Meow/dsh-meow-memory

meow-memory 🐱📝

| | English | Português (BR) | MIT License |

跨会话记忆插件，为 DeepSeek Harness（DSH）打造。

当前版本 0.31.0 ｜ 版本变更见 CHANGELOG.md ｜ 兼容 dsh 0.1.5

✨ 功能特性

- 七层记忆：soul（AI 自身）/ user（用户信息与偏好）/ project（项目信息，含 subcategory）/ fact（原子事实）/ lesson（教训与纠正）/ topic（进行中的话题，带目标句）/ rules（设计原则与行为准则）。每层一张 SQLite 表，UUID 带时间前缀，id 顺序即创建顺序。
- 首轮注入（长期记忆块）：第一条用户消息前注入 soul / user / 设计原则 / 记忆导引。记忆作为独立 plugin snapshot 消息放在真实 user 消息之前，不改写用户 prompt；首轮不跑关键词命中（命中从第二轮起）。
- 每消息关键词命中：从第二条用户消息起，每条真实用户消息检索 fact/lesson/rules/topic（全局 + 当前 project 锚定），top-2 命中注入。命中基于条目关键词而非全文。
- 当前 project 锚定：带 project 参数即锚定该会话的当前项目；未锚定时命中只搜全局（用户闲聊不误伤）。
- 缓存友好设计：静态 meow-memory:guide section 在 system prompt 中注册一次——文本恒定，破坏不了 provider 的 KV 缓存。
- 压缩后重注入：会话压缩后，下一轮自动重新注入长期记忆快照 + 本会话查阅过的项目全景 + 本会话写入过的记忆原文，AI 不会因为压缩突然失忆。
- 七层之上的三件事：写入自动去重合并、按 updated_at 展示记忆时间戳、全局信息用全局标记（区别于留空）。
- 按窗口 dream：窗口空闲 ≥3 小时即允许整理，由该窗口自己的主 agent 分三轮处理（原子记忆 / topic / 项目总结），峰时抑制（默认北京时间 09:00–12:00、14:00–18:00，API 峰谷电价峰时）不触发。也可敲 /dream 立刻手动整理。
- 反思：单次任务内连续 ≥7 个工具 step 后，插件询问模型自上次整理以来是否有值得记忆的内容。最后工具是 memory_ 视为已主动记忆、不重复反思。
- 外部记忆库信任门：工作区自带的 .dsh-meow 若非本机创建（如 clone 的外部仓库），默认暂停注入/检索/整理——首轮提示一次，/meow-trust 一键信任、即刻生效；本机创建与升级前打开过的工作区自动信任，正常使用零感知。
- 客户端 UI：注入文本折叠成横条、反思/dream 轮折叠成一条可展开的卡片、会话列表显示 dream 状态图标（🌙 已整理 / 呼吸灯 进行中 / 灰月牙斜杠 已跳过）。
- 无需另装运行时依赖：node:sqlite + esbuild 产物（lib/index.js）；schemastery 和 dsh-llm 由 DSH 宿主解析提供。无原生模块。

📦 安装

一键安装（推荐）

dsh plugin --profile web add github:Phant0Meow/dsh-meow-memory

一条命令装完即生效：安装时自动编译（包内含 prepare 脚本），自动挂载，重启 dsh web 后新会话自动加载插件。

pnpm ≥10 默认会阻止安装期的构建脚本：首次 add 可能失败并提示 allowBuilds，按提示把输出的键加进 profile 的 pnpm-workspace.yaml 后重跑即可。

卸载

dsh plugin --profile web remove meow-memory

PT-BR Fork

想要巴西葡语打包版本的仓库：coutogilson 的 fork：

dsh plugin --profile web add github:coutogilson/dsh-meow-memory

手动安装（开发者，任意 DSH 安装，无需 npm）

1. 把本包复制（或软链）到 profile 的 node_modules：

mkdir -p ~/.dsh/profiles/web/node_modules
ln -s /path/to/meow-memory ~/.dsh/profiles/web/node_modules/meow-memory

（Windows：New-Item -ItemType Junction ... —— NTFS junction，无需管理员权限。）

2. 把 meow-memory 加进 profile package.json 的 dsh.profile.bundles。

3. 重启 dsh web。新会话自动加载插件。

🔌 兼容性

支持 dsh 0.1.5（含最新的 0.1.5-rc.1），同时向下兼容旧版本——升级 dsh 不需要改本插件，也不需要改任何配置。

插件不写死版本号，而是运行时探测宿主能力，因此新旧版走各自正确的分支。已实测两代：0.1.5-rc.1 上首次注入、记忆工具调用、客户端渲染全部正常；0.1.1-rc.2 上行为与历史版本完全一致。

⚙️ 配置

所有字段均可选（profile patch 或 cordis.patch.yml）。也可以不手编文件：DSH 设置页里有本插件的「喵记忆」标签页（与「通用」「模型」平级），下面这些项全部图形化可改、字段级保存、可单项恢复默认（恢复默认 = 回到插件出厂默认，不受 patch 基线影响）；保存后热重载/重启 meow-memory 插件生效。

- id: meow-memory
name: 'meow-memory'
config:
enabled: true # 总开关 projectDir: '.dsh-meow' # 记忆目录（相对工作区） promptLang: 'zh' # ⚠️ 首次使用建议显式配置（见下方说明） hitTopK: 2 # 每条用户消息关键词命中的条目数上限 dream: enabled: true idleMinutes: 180 # 窗口空闲 ≥180 分钟（3 小时）允许 dream

完整字段、类型与默认值见 docs/配置参考.md，含 titleMax / autoMigrate / homeDir / disabledWorkspaces / backup / delegate 等全部配置项。

⚠️ promptLang 首次使用建议显式配置。 它决定注入/反思/dream 文案与工具描述的语言，同时影响模型写记忆条目用的语言——关键词按条目语言提取。内置 zh / en / pt-br 三套语言包。配置值就是 src/prompts/ 的子目录名，逐字匹配：填一个不存在的名字（例如 pt）不会报错，而是静默落回中文包。详见 docs/配置参考.md。

界面语言

插件界面文案跟随 DSH 的「设置 → 通用 → 语言」（内置中文 / English / Português (Brasil)），与 promptLang 是两层、互不影响。详见 docs/配置参考.md。

🧠 工作原理

第一条用户消息（首轮） 第二条起的每条消息 空闲≥3h 且非峰时 ┌────────────────────┐ ┌────────────────────┐ ┌──────────────────────┐ │ ===== 长期记忆 ===== │ │ 可能相关的记忆，仅供 │ │ 按窗口 dream： │ │ 【关于你】(soul) │ │ 参考：keywords 命中 │ │ 三轮（含项目总结） │ │ 【关于user】 │ │ top-2（全局+当前 │ │ 七层+提取过的， │ │ 【设计原则】(rules) │ │ project 锚定） │ │ updated_at 以 T 封存 │ │ 【记忆导引】 │ └────────────────────┘ └──────────────────────┘ └────────────────────┘ 已见 id 按会话记录独立 plugin snapshot (sessions/<id>.json) ↓ 原样 user prompt 压缩信号 → 释放已见每会话只注入一次，首轮不做命中

工具

| 工具 | 用途 |
| memory_remember | 写入一条记忆（必填 content/project/keywords/importance，自动去重合并） |
| memory_search | 关键词检索（BM25 × 近期权重，支持 level/project/status/days 过滤） |
| memory_project | 取回某项目的完整注入段落（project 参数必填） |
| memory_find_similar | 查重与冲突检测 |
| memory_read | 按 id 读取单条完整元数据 |
| memory_update | 修正 status / importance / goal / keywords |
| memory_dream | 手动触发本窗口的记忆整理 |
| memory_home | 查看 / 切换全局数据目录 |

另有 /dream 命令：在输入框敲 /dream 立即手动唤起本窗口的记忆整理，不受峰时抑制。

参数、返回与副作用见 docs/工具参考.md（含 memory_project 的项目锚定副作用与 memory_home 的三个预设目录标记）。

🛠 开发

npm install
npm run build # esbuild 打包 → lib/index.js（宿主 peer 保持 external）
npm run test # 228 项逻辑测试：db / bm25 / migrate / inject / reflect / dream / tools / apply

@deepseek-ai/ 包位于 dsh-meow pnpm workspace 中，不在本包的 node_modules 里。
在 Windows 上，npm run link-workspace（或 scripts/link-workspace.ps1）创建 workspace 包的 junction 镜像，使 esbuild 能解析它们；build.mjs 通过 nodePaths 引用。
构建不需要安装可选的 dsh-llm peer。直接用 Node 运行测试时，仍需从匹配的 DSH workspace 链接 @deepseek-ai/dsh-llm；正常插件运行由 DSH 的 profile loader 解析宿主提供的 peer。不要把它加回 devDependencies，否则 file: / link: 安装可能再次向 profile 引入宿主核心包的另一份副本（#84）。

node tests/build-host-peers.mjs 单独验证无宿主 peer 的干净构建（#87）。
node tests/host-peers.mjs /path/to/node_modules/@deepseek-ai/dsh 使用另行安装的官方 DSH，验证隔离 profile 的真实 Host 装载和消息契约，不调用模型。

📚 文档

| 想了解 | 看这里 |
| 七个工具的参数、返回与副作用 | docs/工具参考.md |
| 全部配置项、类型与默认值 | docs/配置参考.md |
| 为什么这样设计（缓存、命中、dream、踩过的坑） | docs/设计说明.md |
| 装不上、检索不准、报错怎么读 | docs/常见问题.md |
| 版本变更历史 | CHANGELOG.md |
| 加界面语言 | src/i18n/README.md |
| 加 prompt 语言包 | src/prompts/README.md |

🙏 致谢

感谢每一位贡献者，让 meow-memory 越来越好：

- daveycodez — 英文语言包与英文分词（PR #6，v0.22.0 发布）
- chenmzh — 记忆注入改为独立 plugin snapshot 消息，根治会话标题污染（PR #10）
- cuddly-guacamole — dsh 0.1.2-alpha.4 双版本 Session events 兼容（PR #11）
- coutogilson — 巴西葡语 prompt 语言包（src/prompts/pt-br/）与跟随 DSH 语言设置的界面文案层

📄 License

MIT —— 见 LICENSE。