deepseek-harness-memory

Readme

# deepseek-harness-memory

Claude Code 风格长期记忆插件（dsh 版）：跨会话持久记忆，会话启动自动注入。

- 存储：纯 markdown 记忆文件 + `MEMORY.md` 索引 + YAML frontmatter，**与 Claude Code 格式 1:1 兼容**（可直接读取/导入 `~/.claude` 下的既有记忆）。
- 自动注入：每次 prompt 组装时，用户级 + 当前工作区级的记忆索引出现在系统提示词中（`MEMORY.md` 前 200 行 / 25KB + 最新 200 个记忆文件，与 Claude Code 计量一致）。
- 工具：`memory`（add / update / delete / list / read / import-claude）。

## 存储布局

```
~/.dsh/memory/                          # 用户级记忆
├── MEMORY.md                           # 索引（一行一条：- [标题](文件.md) — 描述）
└── <name>.md                           # 记忆文件（frontmatter + 正文）
~/.dsh/memory/projects/<key>/           # 工作区级记忆
├── MEMORY.md
└── <name>.md
```

- `<key>` 由工作区路径变换得到（`: \ _` → `-`），与 Claude Code 的 `~/.claude/projects/<key>/memory/` 一一对应，例如 `C:\work\my-project` → `C--work-my-project`。
- 记忆文件格式：

```markdown
---
name: <记忆名>
description: <一行描述——用于将来判断相关性>
type: <feedback | reference | project>
modified: <ISO 时间戳，自动维护>
---

<事实；feedback/project 型按「事实 + **Why:** + **How to apply:**」结构>
```

## 记忆纪律（写入系统提示词，引导模型）

- **保存**：用户明确要求记住、给出偏好/修正、或学到将来有用的事实（构建命令、调试洞见、约定、外部系统位置）。
- **不保存**：代码模式/结构（可从项目读取）、git 历史、调试解法、AGENTS.md 已记录内容、临时任务细节；**绝不保存 API 密钥/密码**。
- **验证**：记忆里提到的具体文件/函数在推荐前先确认其仍存在（记忆是写入时的快照）。

## 配置（cordis.patch.yml 覆盖 `memory` 行的 config）

| 键 | 默认 | 说明 |
|---|---|---|
| `memoryRoot` | `~/.dsh/memory` | 记忆根目录 |
| `scope` | `auto` | `auto`（有工作区用 workspace，否则 user）/ `user` / `workspace` |
| `maxIndexLines` | `200` | 注入的 MEMORY.md 行数上限 |
| `maxIndexBytes` | `25000` | 注入的 MEMORY.md 字节上限 |
| `maxList` | `200` | 注入/列出的记忆文件数上限 |
| `includeInPrompt` | `true` | 是否注入系统提示词 |
| `importClaudeMemory` | `true` | list/注入时若 dsh 侧为空，回退只读 Claude Code 同 key 目录 |
| `projectAliases` | `{}` | 路径 key → 统一 key 的映射（见下） |

### projectAliases：同一项目的多 checkout 归一

Claude Code 按工作区路径切分记忆，同一项目（不同分支/多个 checkout）的记忆会散落在多个目录。`projectAliases` 把这些路径 key 映射到一个统一 key，使**记忆属于项目而非路径**——在任何 checkout 里工作，读写同一份记忆：

```yaml
projectAliases:
  C--work-my-project-a: my-project
  C--work-my-project-b: my-project
```

新增 checkout 时，把它的路径 key 加一行映射即可。别名配置应写在 profile 的 `cordis.patch.yml` 覆盖层（该行 config 为整行替换，需同时重述其他字段）。

## 安装 / 升级 / 回滚

```bash
# 前置：安装 pnpm（dsh plugin 依赖）
npm install -g pnpm

# 安装（在本插件目录执行；dsh.bundle 声明会自动加入 profile bundles 层）
dsh plugin --profile web add .

# 升级（重新修改代码后）
dsh plugin --profile web update deepseek-harness-memory

# 回滚（记忆文件保留不删）
dsh plugin --profile web remove deepseek-harness-memory
```

重启 `dsh web` 后生效。无 pnpm 的兜底：把 `deepseek-harness-memory` 目录复制到 `~/.dsh/profiles/node_modules/deepseek-harness-memory/`，并在 `~/.dsh/profiles/web/cordis.patch.yml` 追加：

```yaml
- insert:
    - id: memory
      name: 'deepseek-harness-memory'
```

## 迁移 Claude Code 记忆

两个途径：

1. **自动回退**：`importClaudeMemory: true`（默认）时，若 dsh 侧无记忆，注入会回退读取 `~/.claude/projects/<同key>/memory/` 与 `~/.claude/memory/`（只读，不改原文件）。
2. **正式导入**：对模型说「用 memory 工具 import-claude 导入记忆」，或让模型调用 `memory` action=import-claude——把 Claude Code 既有记忆复制到 `~/.dsh/memory/`（原文件不动）。

## 开发

插件本体为纯 ESM JS（零运行时依赖，仅 node:fs/path/crypto），`lib/index.js` 依赖 `@deepseek-ai/dsh-tools` 与 `@deepseek-ai/schemastery`（从 profile 的 node_modules 解析）。

## 已知限制

- 无自动记忆提取（Claude Code 的 turn-end 记忆子代理）：模型按系统提示词纪律主动 add/update，与用户明确要求「记住」时等效。
- 无 `/memory`、`/toggle-memory` 命令（dsh 无对等命令体系）。
- 记忆明文存储，勿存密钥/PII。