dsh-tiered-memory

Readme

# dsh-tiered-memory

分层记忆 + 预算管理(Tiered memory with per-tier budgets)。
移植 Hermes Agent 的记忆纪律:dsh 生态约 65 个记忆插件全是单层存储,本插件是
**分层 + 预算**概念的首个实现。

## What it does

三个 tier(user / env / project)+ 每层 char 预算:

- **mem_set** — 写稳定事实到层(tier + key + content)。同 key upsert。层满拒绝写。
- **mem_get** — 按 key 精确读。
- **mem_query** — 语义查询:自动路由到对应层(用户特征词→user,环境词→env,项目词→project),只在档案真有时返回。
- **tier_summary** — 各层用量 + 驱逐候选(冷/旧条目)。
- **mem_delete** — 显式删除(淘汰权交模型,不自动删)。

## Hermes 纪律的移植点

| Hermes | 本插件 |
|---|---|
| 四层记忆(user/memory/wiki/skills) | 三层 tier(user/env/project),每层预算 |
| 满层拒绝 → 替换/合并 | add 返回 `tier full — delete or merge first` |
| 只写稳定事实(不写过程) | content 声明式事实,单条 cap(默认 400) |
| 查询时机:只在真有用时查 | mem_query 无命中返回 `[]`,不编造 |
| 淘汰:满了替换/合并 | tier_summary 列候选,mem_delete 显式删 |

## 验证

单测 `node --test`(tiers.js 行覆盖 98.5%);真实 headless e2e:
- 三层写入 + 跨层查询路由正确(user→user / env→env,未跨层)
- 预算拒绝闭环:第二写被拒 → tier_summary 看候选 → mem_delete 冷条目 → 重写成功

## 安装/开发

```bash
# from GitHub (requires dsh CLI)
dsh plugin --profile web add "github:leetom314/dsh-tiered-memory#main"

# or clone and verify locally first
git clone https://github.com/leetom314/dsh-tiered-memory.git
cd dsh-tiered-memory && ./setup.sh && npm test && ./verify.sh   # e2e 隔离 DSH_HOME,不碰真实记忆
```

`verify.sh` 动态生成临时 overlay(`$HERE/index.js` 路径),不需要仓库内 overlay 文件——`overlay*.yml` 已 gitignore(含本机绝对路径,不随版本库分发)。