# dsh-memory-ga

**给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的门控式、文件型长期记忆**——纪律来自 GenericAgent：**No Execution, No Memory（没有行动验证，就不要进长期记忆）**。

> Agent 通常已经有 Skills。  
> 缺的往往是：**可信的短索引 + 红线**、**会话便签**，以及一套把实战教训沉成 Skill / 事实的**结算仪式**——而不是把每句对话静默写进「永久记忆」。

**语言：** [English](./README.md) · 中文

---

## 为什么需要它

写代码的 Agent 会忘事。向量「自动记忆」产品又容易记太多——草稿、走弯路、猜测。

**dsh-memory-ga** 走另一条路：

| 原则 | 你得到什么 |
|------|------------|
| **只记已验证** | 长期写入须来自工具成功结果或用户确认 |
| **L1 硬注入** | 每轮 ≤约 30 行索引 + RULES，不是「也许永远不会去读的指针」 |
| **Working 便签** | 本会话 `key_info`，非空则持续注入 |
| **门控结算** | `start_long_term_update` 打开协议；**不会自动改你的文件** |
| **Skills 归 Skills** | 可复用流程 → DSH Skills；记忆**不是**第二套 SOP 仓库 |
| **本地可审计** | `$DSH_HOME/memory` 下明文 UTF-8——可 diff、备份、手改 |

不需要 embedding，不需要云端 bank，没有静默 retain。

---

## 架构（有意做小）

```
$DSH_HOME/memory/
  L0_memory_management.md   # 宪法（怎么记）
  global_mem_insight.txt    # L1：导航 + RULES → 硬注入
  global_mem.txt            # L2：已验证事实 → 按需 read（每节 ≤9 行 + 指针）
  l3/<topic>.md             # L3：长篇事实档案（L2 节内指针直达）
  .working/<session>.txt    # 可选：会话便签落盘

DSH 平台（不在本目录）
  Skills / 技能目录           # 流程
  Sessions                  # 完整对话（用 DSH 查，不是 memory 里的「L4 树」）
```

**没有 notes 式散记库，也没有 memory 树里的 L4。**`l3/` 只收**事实档案**——流程归 Skills（Skill=怎么做，L3=是什么）。  
Skill 错了 → **直接改 Skill**，不要在 memory 里留一份勘误影子。

```
已验证 + 值得跨会话保留？
  ├─ 可复用工作流     → DSH Skill（+ 可选 L1 一行导航）
  ├─ 环境 / 配置事实  → L2（± L1 指针）
  ├─ 篇幅很长的档案   → l3/<topic>.md（+ L2 指针）
  ├─ 一句全局规则     → L1 RULES
  └─ 仅本任务         → Working（或丢弃）
```

---

## 工具

| 工具 | 作用 |
|------|------|
| `update_working_checkpoint` | 整页替换本会话便签（`key_info`） |
| `start_long_term_update` | 返回 L0 + 结算协议（**不自动写盘**） |
| `memory_status` | 路径、L1/L2 体量、l3 档案数、working 是否为空、催促计数 |

可选 **软催促**（默认开）：步数够了温和提醒 checkpoint / 结算。从不强制调工具，从不自动写 L1/L2。

---

## 安装（DeepSeek Harness profile）

兼容 DSH Cordis 插件（`dsh.bundle.patch`）。

### A. 从 Git 安装（发布后推荐）

在 profile 目录（例如 `$DSH_HOME/profiles/web`）：

```bash
pnpm add dsh-memory-ga@github:DiligenceLai/dsh-memory-ga
```

确保 profile 会加载该包（写入 `dsh.profile.bundles`，或依赖包内 `cordis.patch.yml` 的 insert——与其它社区插件相同）。

### B. 本地路径（开发）

```bash
pnpm add dsh-memory-ga@file:../path/to/dsh-memory-ga
```

> **注意：** 部分包管理器对 `file:` 是**拷贝**而非实时链接。改插件源码后需重装/重链 profile 依赖，并重启 DSH（或等待 profile HMR）。

### C. Skill 助手（可选）

把附带 Skill 拷到用户 skills 根，便于加载 `memory-management`：

```text
skills/memory-management/SKILL.md  →  $DSH_HOME/skills/memory-management/SKILL.md
```

重启或等待 skill 文件系统重新扫描。

---

## 快速验证

1. 重启 DSH / 重载 profile。  
2. 会话中调用 **`memory_status`** → 应看到 `$DSH_HOME/memory`。  
3. **`update_working_checkpoint`** 写一句 → 下一模型步应出现 `### [WORKING MEMORY]`。  
4. **`start_long_term_update`** → 协议 + 完整 L0；在你手动 edit 之前磁盘不变。

首次启动只 **创建缺失** 的 L0/L1/L2 模板，**永不覆盖**已有文件。

---

## 配置

插件 id `memory-ga` 的 Cordis 配置（可选）：

```yaml
- id: memory-ga
  config:
    # root: null            # 默认: $DSH_HOME/memory
    bootstrap: true
    injectL1: true
    injectWorking: true
    l1MaxChars: 1200
    workingMaxChars: 1200
    persistWorkingFile: true
    nudge:
      enabled: true
      workingEvery: 12
      settleAfterSteps: 15
      maxWorkingNudges: 3
      maxSettleNudges: 2
```

**硬依赖：** 插件声明 `inject: ["tools", "systemPrompt", "llm"]`。宿主组合须包含 `@deepseek-ai/dsh-llm`（提供 `createUserMessage`），working 记忆与 nudge 注入都依赖它。若缺失，插件仍可加载，但 `memory_status` 会警告 "working/nudges 未注入"，而非静默失败。

`workingMaxChars` 是存储与注入 working 便签的**同一上限**，因此 `memory_status.workingChars` 始终等于模型实际看到的长度。

---

## 它不是什么

- 不是向量库 / TEMPR / 自动 git retain 产品  
- 不是 DSH Skills 的替代品  
- 不会自动生成 Skill  
- 不会把完整聊天记录倾倒进 `memory/`

若你要跨工具的最大自动召回，请看其它方案。  
若你要 **可控结晶** 与 **git 友好的真相源**，这里合适。

---

## 隐私

本仓库只带 **通用模板**。  
你的真实 L1/L2 在本机 **`$DSH_HOME/memory`**，**从不**属于本包装内容。  
请勿把个人记忆文件、token、本机绝对路径提交到 fork。

---

## 开发

```bash
git clone <this-repo>
cd dsh-memory-ga
pnpm install   # schemastery 等，便于本地冒烟
```

入口：`lib/index.js`（Cordis 的 `name` / `inject` / `Config` / `apply`）。

---

## 贡献

欢迎 Issue / PR：更多 profile 安装说明、更强 nudge 钩子、项目级 memory 覆盖、会话检索 Skill 示例等。

---

## 许可证

MIT — 见 [LICENSE](./LICENSE)。

GenericAgent 是独立项目；本插件只 **借用记忆纪律**，并非移植 GA 全套运行时。