yehuioc/dsh-memory-pack

dsh-memory-pack

面向 skill 驱动的 agent 运行时（DeepSeek Harness / Claude Code / Codex 等）的文件式分层记忆插件包。

它是一套「目录约定 + 元数据契约 + 导航规则」，不是数据库。agent 把记忆写成普通 Markdown 放进约定目录，用 frontmatter 标注来源和审查状态，进入记忆时先读索引层。你能看得见 agent 到底记了什么、从哪来的、有没有被外部内容污染、能不能一键用 git 回滚。

核心特性

- 11 层分层模型：00-Inbox → 10-Raw → 20-Distilled → 25-Candidates → 30-Writing → 40-Concepts → 50-Action → 60-Achievement → 80-Maps → 90-Attachments → 99-Archive
- Maps-first：进记忆先读索引，不全量扫描
- 元数据契约：producer / review_state / canonical_status / contains_third_party_source，审查责任归属人
- 污染防护：外部来源材料强制标记并隔离，未经人工审查不进正式记忆
- 最小闭环：recall → 做 → capture → promote
- 零依赖脚本：scaffold 生成骨架，audit 检查元数据合规

目录结构

dsh-memory-pack/
├── AGENTS.md                        # workspace instructions 模板（注入分层规则）
├── docs/
│   └── layered-memory-spec.md       # 方法论内核规范（给作者/维护者读）
├── skills/                          # 5 个去耦合 skill（DSH 标准格式）
│   ├── memory-pipeline/             # 路由：内容进哪一层
│   ├── experience-capture/          # 记：沉淀可复用经验
│   ├── experience-recall/           # 取：召回相关经验
│   ├── distilled-memory-promotion/  # 晋级：候选 → 正式记忆
│   └── raw-dialogue-ingress/        # 原始对话入库（只保全，不蒸馏）
└── scripts/
├── memory_scaffold.py           # 生成 memory/ 骨架
└── memory_audit.py              # 审计元数据合规

安装

DSH 按以下根目录扫描 skill（rank 从高到低）：/.dsh/skills/、/.agents/skills/、~/.dsh/skills/、~/.agents/skills/。skill 格式为 //SKILL.md，frontmatter 只需 name（kebab-case）+ description。

用户级安装（全局可用，推荐）

把 5 个 skill 复制到用户 DSH skill 根
Copy-Item -Recurse -Force .\skills\* "$env:USERPROFILE\.dsh\skills\"

项目级安装（仅当前项目）

复制到项目 .dsh skill 根
New-Item -ItemType Directory -Force .\.dsh\skills | Out-Null
Copy-Item -Recurse -Force .\skills\* .\.dsh\skills\

注入 workspace 规则（可选但推荐）

把本仓库的 AGENTS.md 复制到你的项目根目录，让 agent 自动获得分层记忆规则：

Copy-Item .\AGENTS.md \AGENTS.md

使用

1. 在你想要持久化记忆的项目根目录生成骨架
python scripts\memory_scaffold.py

2. 之后 agent 对话中直接说「记一下」「存入记忆」，agent 会调用 memory-pipeline 路由
说「按过去经验」会触发 experience-recall

3. 审计元数据合规
python scripts\memory_audit.py

方法论内核

完整规范见 docs/layered-memory-spec.md。要点：

1. 分层路由：按内容语义选层，不按「能不能写」选层。
2. 审查责任在人：review_state: reviewed 与 canonical_status: formal 必须由人明确确认，agent 不能自我批准。
3. 来源可追溯：source_paths 缺失要显式说明，不编造。
4. 外部内容隔离：网页、第三方账号、外部导入一律标 contains_third_party_source: true，停在 Raw/Candidates 等人工审查。
5. 晋级是复制不是移动：候选晋级为正式记忆是「复制/重写进正式层」，候选原文保留为 provenance，不删除。

与向量记忆的区别

| | 向量记忆 / 自动记忆 | dsh-memory-pack |
|---|---|---|
| 存什么 | 隐向量、自动提取 | 普通 Markdown 文件 |
| 可见性 | 黑盒 | 每个文件可读、可 git diff |
| 审查 | 通常无 | 强制 review_state 门禁 |
| 污染防护 | 弱 | 强制 contains_third_party_source 隔离 |
| 回滚 | 难 | git checkout 即回滚 |

两者互补，不互斥。本方法适合「想完全掌控 agent 记忆、要审计、要 git 管理」的场景。

许可

MIT，见 LICENSE。

面向未来的说明
本包是从一个私有 agent 运行时的方法论中抽取去耦合而来：刻意去掉了多 agent 角色分工（Codex/Claude Code/OpenClaw）、私有路径、私有审计脚本和 LLM Wiki 依赖，只保留分层模型、Maps-first、元数据契约、污染防护和最小闭环这五个可移植内核。欢迎提 issue / PR 一起演进。