记忆流上下文 crwsr124/dsh-memflow

dsh-memflow

MEMFLOW 记忆流模式 —— DeepSeek Harness 的目录级上下文框架插件。

会话会结束，记忆不会：感知先行、边做边记、无缝续接。
目录即身份：.dsh/context.yaml 声明这个目录里「谁在工作」以及「开工前必须感知什么」。
记忆不是预设，是每个 agent loop 的基线要求。

English · 协议全文 · License

0.3.0 的前提变化

0.2.x 把记忆做成一个用户主动挑选的 preset：选了「记忆流模式」才有记忆。0.3.0 放弃了这个前提。

记忆与身份不是一种模式，而是每个 agent loop 的基线要求。

因此身份与感知的来源从「预设」下移到「目录」：每个工作目录用 .dsh/context.yaml 声明自己的 systemPrompt 与 preload，任何在该目录打开的会话都机械地获得这套上下文——web、headless、被调度的子 agent 一视同仁，不经过 preset 服务。

<工作目录>/.dsh/context.yaml systemPrompt: # 身份 / 协议 —— 作为 prompt section 注入
- AGENT.md
- ../shared/PROTOCOL.md
preload: # 感知 —— 作为会话首条 user message 注入
- memory/status.md
- memory/history.md
inherit: false # 缺省；置 true 才向上合并祖先目录的声明（外层在前）

systemPrompt 文件在每次 prompt 组装时重新读取，改文件下一轮即生效；preload 文件拼成一条固定的首条 user message，每个会话只注入一次——感知先于第一个任务，且永不重投。

未声明的目录仍按 0.2.x 行为加载 memory/ 目录（legacy fallback），存量项目无需改动。声明存在时以声明为准。

声明路径变量（0.4.0）

声明被 git 托管、跨设备共享时，设备各自的记忆文件没法用一条静态路径写死。0.4.0 起声明路径支持两个内置变量：

<工作目录>/.dsh/context.yaml preload:
- memory/${device}/status.md # 每台设备各自的分区记忆

| 变量 | 解析值 |
| ${device} | 从声明所在目录（.dsh 的上级）起向上逐级查找 .device 文件（上限 64 级），取首个命中文件的第一个非空行、trim 后的值；找不到或内容为空则回退到主机名去掉尾部 .local |
| ${hostname} | 主机名去掉尾部 .local |

解析顺序与规则：

- 替换发生在 resolveFrom 这个唯一咽喉点，对 systemPrompt 与 preload、声明来源与 DSH_CONTEXT_/config 来源的 extra 路径统一生效（extra 路径以会话工作目录为基准向上找 .device）。
- 每次组装都重新求值，不做缓存——与「声明文件每回合重读」的既有哲学一致；.device 是一行小文件，读取代价可忽略。
- 未知的 ${...} 保持字面量：不删除、不报错，下游读取时自然产生「无法读取」注记，响亮暴露拼写错误。
- 不支持 env 变量替换、glob、转义，也不引入通用 var 键——声明格式保持极小面。变量在路径上替换；文件内容不做任何替换。

一个协议、两个载具

| 载具 | 作用 |
| .dsh/context.yaml 声明 | 目录级身份与感知；显式写 inherit: true 才沿父目录向上合并（外层先注入） |
| DSH_CONTEXT_ 环境变量 | 调度方的按次通道：为某一次调度追加上下文、替换声明、或整体忽略声明 |

这里没有 {{memflow_protocol}} 变量，也是有意为之。 0.3.0 移除了「插件自带一份协议全文并注入每个 prompt」这条通道：协议属于工作目录，不属于插件。要什么身份，就在该目录的 .dsh/context.yaml 的 systemPrompt 里声明（WORKFLOW.md / AGENT.md / 你自己的协议文件）。包内 MEMFLOW.md 仅作参考实现与文档，不再进入任何 prompt——需要它就把它列进声明。

这里没有 delegate 工具，是有意为之。 被调度的子 agent 就是「在另一个目录里打开的一个会话」——调度方设定它的 cwd，它便从那个目录的声明里自己组装身份与感知，走的是与其它任何会话完全相同的代码路径。若再提供一条「把准备好的 dossier 递给子 agent」的通道，就等于用两套发散的机制说同一件事。

按次调度参数

目录声明的是默认身份，调度方还需要能收窄某一次运行。进程外（ACP）provider 无法下推 persona / outputSchema / toolFilter（subagent 服务在 start 之前就会拒绝），唯一能穿过进程边界的通道是子进程环境变量：

| 变量 | 作用 |
| DSH_CONTEXT_IGNORE=1 | 忽略所有声明（纯 headless，连 legacy memory/ 也不注入） |
| DSH_CONTEXT_FILE=<abs> | 用指定声明文件替代目录发现 |
| DSH_CONTEXT_SYSTEM_PROMPT=<paths> | 追加身份文件（换行或路径分隔符分隔） |
| DSH_CONTEXT_PRELOAD=<paths> | 追加感知文件 |
| DSH_CONTEXT_PARAMS=<json\|text> | 本次调度参数，原文注入，排序在所有身份 section 之后（因此可收窄它们） |
用 DSH_ 前缀是有意为之：harness 的 scrubbedParentEnv() 会从环境继承中剥掉所有 DSH_ 名称，而显式 env 层在剥离之后合并——所以交给某个子代理的参数不会泄漏到它自己的孙代理。按次调度真的只作用一次。

快速开始

安装（bundle 自动注册，首次需重启 dsh 进程加载）
dsh plugin --profile web add github:crwsr124/dsh-memflow
dsh plugin --profile headless add github:crwsr124/dsh-memflow

在项目里声明身份与感知
mkdir -p .dsh && cat > .dsh/context.yaml <<'YAML'
systemPrompt:
- AGENT.md
preload:
- memory/status.md
- memory/history.md
YAML

任何会话在该目录打开即生效
dsh --profile headless "你的任务"

配置

插件行（row）config（在 profile cordis.patch.yml 按 id 覆盖）：

| 键 | 默认 | 说明 |
| declarationFile | .dsh/context.yaml | 声明文件相对路径 |
| discover | nearest | nearest = 从 cwd 向上找最近声明并按 inherit 续走；cwd = 只认 cwd 自己的声明 |
| inherit（声明内键） | false | 由声明文件自身控制是否继续向上合并；缺省不继承——一个目录的身份默认只由它自己说清楚，需要叠加祖先声明时显式写 true |
| sectionOrderBase | 10 | 身份 section 起始 order（在 DEPLOYMENT_PERSONA 0 之后、PLAN_POLICY 500 之前） |
| maxSections | 16 | 身份 section 槽位数上限（注册期固定，空槽渲染为空） |
| systemPrompt / preload | [] | row 级追加文件，等价于 DSH_CONTEXT_ 的静态形式 |
| ignoreDeclaration | false | 整个 profile 忽略声明（纯 headless profile 用） |
| allowEnvOverride | true | 是否接受 DSH_CONTEXT_ 环境通道 |
| legacyMemoryFallback | true | 无声明目录回退加载 memory/（0.2.x 行为） |
| memoryBootstrap | true | 注入首条感知消息 |
| memoryPriority | ['history','brick_index','notes','status','tasks'] | legacy fallback 的文件优先序 |
| perFileBytes | 不限 | 单文件 UTF-8 字节上限；仅显式设置时截断并标为受限快照 |
| totalBytes | 不限 | 快照总 UTF-8 字节上限；同上 |
| skipDelegated | false | 设 true 则不给 delegationDepth > 0 的进程内子代理注入感知；默认注入，因为子代理与其它会话一样只是「某个目录里的一个会话」（旧名 includeDelegated: false 等价） |
| suppressRoots | [] | 抑制目录：这些项目根（按 .git 向上发现）完全不注入 |

0.3.0 移除了 protocolFile 与 rosterlessProtocol（协议全文通道已废，见上文）；配置里残留这两个键无害，会被忽略。

memoryPerFileBytes / memoryTotalBytes 作为 perFileBytes / totalBytes 的旧名仍被接受。

目录结构

<工作目录>/ ├── .dsh/ │ └── context.yaml # 身份与感知声明（0.3.0 起的入口） ├── AGENT.md # 该目录的 agent 身份 / 协议（由声明引用） └── memory/ # 持久记忆 ├── tasks.md # 任务清单与状态 ├── status.md # 项目现状快照 ├── history.md # 工作记录 ├── notes.md # 实操笔记与陷阱 ├── brick_index.md # 可复用技能索引 └── bricks/ # 可复用技能文档

实现说明

- 零 @deepseek-ai 依赖（有意为之）：profile 插件若携带与组合 row 重名的依赖（dsh-tools/dsh-subagent 等），会遮蔽 host row 的模块解析导致 Symbol 分裂、首次工具调用即崩。本插件全部走注入服务（ctx.tools / ctx.subagents / ctx.get('jobs') / ctx.systemPrompt），工具定义与 YAML 子集解析器均手写。
- stdout 属于协议：ACP 部署下 stdout 是 JSON-RPC 帧通道，插件从不写 stdout，诊断只走 ctx.logger。
- 感知是框架保证，不是模型自觉：感知消息由 agent/pre-step 瀑布机械注入（与 agent-instructions 同通道），去重依据是会话持久事件日志而非单轮 step。
- 声明解析出错不杀 loop：YAML 子集解析器带行号报错，loadDeclaration 捕获后告警并退化为「无声明」，不影响会话启动。
- 社区项目，与 DeepSeek 官方无隶属关系。

MEMFLOW — per-directory context composition for DeepSeek Harness (dsh). 0.3.0 改变了前提。 记忆与身份不再由用户挑选的预设决定，而是每个智能体循环的基线要求。目录声明谁在这里工作、开工前必须先感知什么；在这个目录里打开的任何会话都会自动获得这套组合——web、headless、派发的子代理都一样，不涉及名单。

<dir>/.dsh/context.yaml
systemPrompt: [AGENT.md] # identity → ordered prompt sections, re-read per assembly
preload: [memory/status.md] # perception → ONE fixed first user message, once per session
inherit: false # default: do not merge ancestors; set true to opt in

0.4.0 新增声明路径变量，用于 git 共享、多设备的声明：

preload:
- memory/${device}/status.md

${device} 从声明所在目录向上查找，直到找到第一个 .device 文件（最多 64 层），取其中第一行非空内容并去掉首尾空白；文件缺失或内容为空时，回退到主机名去掉 .local 后缀。${hostname} 始终是这个短主机名。无法识别的 ${...} 保持原样，下游会以「路径不可读」的提示暴露出来。替换发生在 resolveFrom 中——声明路径与环境/配置提供的路径都只经过这一个入口——每次组装都会重新求值（不缓存）。不做环境变量展开，不做 glob，不做转义。

调度器通过子进程的环境变量微调单次运行——这是唯一能跨进程边界传递的通道，因为进程外的服务商可能无法推送 persona：

DSH_CONTEXT_IGNORE=1 ignore declarations (pure headless)
DSH_CONTEXT_FILE=<abs> use this declaration instead of discovery
DSH_CONTEXT_SYSTEM_PROMPT=<paths> extra identity files
DSH_CONTEXT_PRELOAD=<paths> extra perception files
DSH_CONTEXT_PARAMS=<json|text> this run's parameters, injected verbatim

DSH_ 是有意选定的命名空间：harness 会从环境继承中剥离所有 DSH_* 名称，再在清理之后合并显式传入的环境层，因此交给某个子进程的参数不会泄漏到该子进程自己的孙进程。

没有声明的目录仍会按机制加载 memory/（0.2.x 行为），现有项目无需改动即可继续工作。

安装：

dsh plugin --profile <name> add github:crwsr124/dsh-memflow

社区项目，与 DeepSeek 无隶属关系。