sage-mem 0.1.3 → 0.4.1

package/README.md

@@ -1,117 +1,138 @@
-# sage-mem · DSH 的记忆系统插件
-
-给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）装上**跨会话记忆**——agent 今天记住的事，明天的新会话自动想起来。
-
-## 为什么需要它
-
-DSH 原生没有记忆系统。每个会话都是白纸：用户说过「我喜欢在深夜写代码」，下个会话再问「我喜欢什么」，agent 只能答不知道。
-
-sage-mem 补上这一块。它监听 DSH 的事件流，把会话内容沉淀到 SQLite，新会话启动时自动检索注入历史记忆。
-
-**中文优先**。市面上的记忆方案在中文检索上普遍失效（SQLite FTS5 默认分词器对中文全部 0 命中）。sage-mem 的 worker 用 trigram 分词 + 短词兜底，中文实测全命中。
-
-## 功能
-
-- **自动捕获**：工具调用（读写文件、执行命令）自动记录，无需手动整理
-- **AI 压缩**：会话内容由 LLM 压缩成结构化记忆（事实、摘要），中文输出
-- **跨会话注入**：新会话启动时自动检索并注入历史记忆，agent 不用自己翻
-- **中文检索**：trigram 分词（≥3 字查询）+ LIKE 兜底（<3 字短词如「猫」「芝麻」）
-
-## 架构
-
-```
-DSH（Cordis 插件）
-  └─ sage-mem 插件（事件监听 → HTTP 转发）← 本仓库
-       │  HTTP 127.0.0.1
-       ▼
-sage-mem worker（Bun 常驻，fork 自 claude-mem）← gezi-wen/claude-mem
-       │
-       ▼
-SQLite（FTS5 trigram 中文分词 + LLM 压缩）
-```
-
-设计选择：记忆逻辑复用 [claude-mem](https://github.com/thedotmack/claude-mem)（Apache-2.0，9 万星），fork 后加中文修复，DSH 侧只写一个轻量桥接插件。改动最小，能追上游更新。
-
-## 安装
-
-### 1. 部署 worker
-
-```bash
-git clone https://github.com/gezi-wen/claude-mem.git
-cd claude-mem
-git checkout sage-mem-worker   # 含中文 trigram 修复
-bun install
-```
-
-配置 `~/.claude-mem/settings.json`（worker 数据目录）：
-
-```json
-{
-  "CLAUDE_MEM_PROVIDER": "openrouter",
-  "CLAUDE_MEM_OPENROUTER_BASE_URL": "https://api.deepseek.com",
-  "CLAUDE_MEM_OPENROUTER_MODEL": "deepseek-chat",
-  "CLAUDE_MEM_CHROMA_ENABLED": "false",
-  "CLAUDE_MEM_MODE": "code--zh"
-}
-```
-
-`~/.claude-mem/.env` 放 API key（任意 OpenAI 兼容服务均可，不限于 DeepSeek）：
-
-```
-OPENROUTER_API_KEY=<你的 API key>
-```
-
-启动：
-
-```bash
-bun src/services/worker-service.ts --daemon
-```
-
-### 2. 安装插件
-
-在你的 DSH profile 的 `package.json` 里加：
-
-```json
-{
-  "dependencies": {
-    "sage-mem": "github:gezi-wen/sage-mem"
-  },
-  "dsh": {
-    "profile": {
-      "bundles": ["sage-mem"]
-    }
-  }
-}
-```
-
-或 clone 后本地 link：
-
-```json
-{
-  "dependencies": {
-    "sage-mem": "link:../sage-mem"
-  }
-}
-```
-
-然后 `pnpm install` 重启 DSH。
-
-## 验证
-
-跨会话中文记忆链路（实测）：
-
-1. 会话 A 说「记住：我的猫叫芝麻，它喜欢晒太阳」
-2. 开新会话 B 问「我的猫叫什么」
-3. agent 直接答出「芝麻」——记忆自动注入，无需 agent 自己找
-
-搭配 [sage-persona](https://github.com/gezi-wen/sage-persona)（我是谁）和 [sage-meta](https://github.com/gezi-wen/sage-meta)（我做得对吗）组成 Sage 三件套——这是三道题的第三道：**我下次应该怎么想**。
-
-## 已知边界
-
-- trigram 分词对 `<3` 字符查询无效，worker 已加 LIKE 兜底
-- worker 不可用时插件静默跳过（不阻塞 DSH），记忆功能暂缺
-- MVP 存储统一在 `project=sage` 空间，按工作区分项目是后续计划
-
-## License
-
-MIT（worker fork 为 Apache-2.0，见 [gezi-wen/claude-mem](https://github.com/gezi-wen/claude-mem)）
+# sage-mem · DSH 的文件式记忆插件
+
+给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）装上**跨会话记忆**——agent 今天记住的事，明天的新会话自动想起来。
+
+记忆存在**本地 markdown 文件**里（frontmatter + 正文），不是数据库。透明、可检查、防膨胀。
+
+## 从 Claude Code 无损迁移
+
+你已经在 Claude Code（CC）里养了一个 agent，舍不得它的记忆和人格？sage-mem 是「CC → DSH」迁移方案的一部分，**记忆与人格都能无损搬过来**：
+
+- **人格**：CC 的 `CLAUDE.md` → DSH 的 `AGENTS.md`，DSH 原生加载，纯文本一字不改就能用。
+- **记忆**：CC 沉淀的跨会话记忆 → sage-mem 的 `memory/` 目录（markdown + frontmatter，四类）。
+
+没有数据库、没有私有格式——全都是 markdown 文本，**直接拷文件就完成迁移**。agent 换了身体，但依然记得你是谁、记得你们聊过什么、记得进行中的项目。
+
+## 为什么用文件
+
+DSH 原生没有记忆系统，每个会话都是白纸。市面上的记忆方案大多走 SQLite + 常驻 worker：
+
+- 记忆写进数据库，**不透明**——想检查存了什么得查表，想清理要连数据库
+- 事件自动捕获会**膨胀**——"用户打了个招呼"这种无实质内容也被存进去
+- 需要一个**常驻 worker 进程** + 端口，多一份运维负担
+
+sage-mem 换成文件式：每条记忆一个 markdown 文件，直接用编辑器打开就能看、能改、能删。存不存由 agent 按规则判断，不是事件全捕获。没有 worker、没有 SQLite、没有端口。
+
+## 功能
+
+- **按问题检索注入**：每次提问，插件扫记忆目录，按相关性把记忆注入 system prompt，agent 第一轮就「想起来」
+- **四类记忆**：`user`（用户是谁）/ `feedback`（工作方式指导）/ `project`（项目状态）/ `reference`（外部信息指针）
+- **文件透明**：记忆就是 `*.md` 文件，frontmatter 存元数据，正文存内容
+- **防膨胀**：写入靠规则引导 agent 判断「存不存」，无实质内容、能靠代码/git 推导的不存
+- **Web 文件管理器**（v0.4）：DSH 设置页「记忆管理」，浏览/查看/编辑/删除记忆文件，添加新记忆
+
+## 架构
+
+```
+DSH（Cordis 插件）
+  └─ sage-mem 插件（按问题检索 + 注入）← 本仓库
+       │  Node fs 直读
+       ▼
+memory/ 目录（markdown 文件，4 类）
+  ├── user_*.md
+  ├── feedback_*.md
+  ├── project_*.md
+  ├── reference_*.md
+  └── MEMORY.md          ← 索引
+```
+
+没有 worker、没有 SQLite、没有 HTTP 端口、没有常驻进程。
+
+## 安装
+
+在你的 DSH profile 的 `package.json` 里加：
+
+```json
+{
+  "dependencies": {
+    "sage-mem": "github:gezi-wen/sage-mem"
+  },
+  "dsh": {
+    "profile": {
+      "bundles": ["sage-mem"]
+    }
+  }
+}
+```
+
+或 clone 后本地 link：
+
+```json
+{
+  "dependencies": {
+    "sage-mem": "link:../sage-mem"
+  }
+}
+```
+
+然后 `pnpm install` 重启 DSH。
+
+## DSH 兼容性
+
+sage-mem 是纯 DSH 插件，在 `package.json` 的 `dsh.compatibility.dshReleases` 里逐版本声明兼容状态：
+
+| DSH 版本 | 状态 |
+| --- | --- |
+| 0.1.2-rc.1 | compatible |
+| 0.1.3-alpha.1 | compatible |
+| 0.1.3-alpha.2 | compatible |
+
+Node.js 要求 `>= 18`（见 `engines.node`）。
+
+## 卸载
+
+在 profile 的 `package.json` 里删掉 `sage-mem` 依赖，并从 `dsh.profile.bundles` 移除 `"sage-mem"`；
+`pnpm install` 后重启 DSH 即可。记忆 markdown 文件留在原目录，不受影响。
+
+## 配置
+
+用环境变量 `SAGE_MEM_DIR` 指定记忆目录，默认 `~/.sage-mem/memory`：
+
+```
+SAGE_MEM_DIR=/path/to/your/memory
+```
+
+记忆文件格式：
+
+```markdown
+---
+name: 可选的短名
+description: 一句话说清这条记忆是什么（检索与列表都靠它）
+metadata:
+  type: user        # user / feedback / project / reference
+---
+
+记忆正文。
+```
+
+`feedback` 类建议带 `**Why:**`（原因）和 `**How to apply:**`（何时生效）两行，方便判断边界。
+
+## 验证
+
+跨会话记忆链路（实测）：
+
+1. 会话 A 说「记住：我的猫叫芝麻，它喜欢晒太阳」——agent 按规则写进 `memory/`
+2. 开新会话 B 问「我的猫叫什么」
+3. agent 第一轮直接答出「芝麻」——记忆自动注入，无需 agent 自己找
+
+## 相关项目
+
+- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — DSH 本体，一切皆插件
+
+## 旧版
+
+本仓库早期是 SQLite + worker 架构，已归档到 [`sqlite-worker`](../../tree/sqlite-worker) 分支。文件式是继任实现。
+
+## License
+
+Apache-2.0

package/cordis.patch.yml

@@ -1,4 +1,4 @@
-# sage-mem bundle patch — injects the memory bridge plugin into the profile tree.
-- insert:
-    - id: sage-mem
-      name: 'sage-mem'
+# sage-mem bundle patch — injects the memory bridge plugin into the profile tree.
+- insert:
+    - id: sage-mem
+      name: 'sage-mem'