dsh-claude-memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GodCC6
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+# dsh-claude-memory
+
+A read-only [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that
+surfaces **Claude Code's existing project memory** inside DSH — so a task can continue in
+DSH after a Claude Code quota runs out.
+
+中文文档：[README.zh.md](README.zh.md)
+
+```
+~/.claude/CLAUDE.md          ─┐
+  @imports inlined            │
+~/.claude/projects/<key>/     ├─► confine ─► redact ─► byte-budget ─► DSH system prompt
+  memory/MEMORY.md  (index)   │                                        + claude_memory tool
+  memory/<topic>.md (bodies) ─┘
+```
+
+## What it does
+
+- Injects the resolved project's `MEMORY.md` index into the system prompt, plus the
+  user-global `~/.claude/CLAUDE.md` with its `@path` imports inlined.
+- Registers one `claude_memory` tool so the model can open any memory, list projects, or
+  search across a project's notes — full bodies never enter the prompt by default.
+- Masks credential-shaped text **before** anything reaches the model provider.
+- Never writes, moves, or deletes anything under the Claude home.
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-claude-memory
+```
+
+Restart the profile — a new bundle in `dsh.profile.bundles` is read at boot, not live.
+
+From a checkout instead of npm:
+
+```bash
+dsh plugin --profile web add /path/to/dsh-claude-memory
+```
+
+Verify the row composed:
+
+```bash
+dsh --profile web --dump-config | grep -A 10 claude-memory
+```
+
+## Configuration
+
+Defaults live in this package's `cordis.patch.yml`; override them in your profile's patch
+layer or a `--patch` overlay.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `claudeHome` | `~/.claude` | Claude Code home. Every read is confined to this root. |
+| `cwd` | `process.cwd()` | **Fallback only.** A live session's `agent.session.header.cwd` always wins. |
+| `includeDescendants` | `true` | List sibling/child projects that have memory. |
+| `descendantLimit` | `12` | How many other projects to list. |
+| `maxIndexBytes` | `24000` | Byte budget for the injected memory block. |
+| `maxGlobalBytes` | `6000` | Byte budget for `CLAUDE.md` plus inlined imports. |
+| `enableMemory` | `true` | Inject the memory block. |
+| `enableGlobalInstructions` | `true` | Inject the user-global instructions. |
+| `enableTool` | `true` | Register the `claude_memory` tool. |
+| `redactMode` | `on` | `on` masks secrets, `report` counts only, `off` disables. |
+| `refreshMs` | `20000` | Re-read the store when a prompt is assembled and the cache is older. |
+
+## What reaches the model
+
+Two system-prompt sections (orders 10 and 11, just after the deployment persona):
+
+1. **`claude-memory:global`** — `~/.claude/CLAUDE.md` with `@path` lines inlined. DSH's own
+   instruction loader deliberately does not expand imports, and it reads
+   `$DSH_HOME/AGENTS.md` rather than `~/.claude/CLAUDE.md`, so this is the only path that
+   carries the user-global Claude Code memory.
+2. **`claude-memory:memory`** — the resolved project's `MEMORY.md` index, plus a
+   newest-first list of the other projects that have memory.
+
+Full memory bodies arrive only through the tool, one file at a time, under a 20 KB cap.
+
+## Project resolution
+
+The directory that decides which memory is relevant is the **session's** working directory,
+not the directory the `dsh` server was launched from. Those differ whenever the server is
+started from one checkout while sessions run in another.
+
+Resolution order:
+
+1. **exact** — `<home>/projects/<encoded-cwd>/memory/` exists;
+2. **git-root** — the encoded key for the enclosing git repository root has memory;
+3. **freshest** — otherwise, the most recently updated memory set among the ancestors and
+   children of the working directory (reported to the model as a guess).
+
+Rule 2 exists because **Claude Code files memory under the git repository root, not the raw
+working directory** — see the case study below. In rules 2 and 3 the other projects are
+listed newest-first, so the freshest child is one tool call away.
+
+`agent.session.header.cwd` is the same source the first-party `dsh-agent-instructions`
+loader reads. Sections are registered globally as a fallback and then **shadowed per agent**
+from `agent/created`, and the tool resolves per call from `exec.agent`, so a subagent or a
+session started elsewhere sees its own project.
+
+## The `claude_memory` tool
+
+| Action | Arguments | Returns |
+|---|---|---|
+| `projects` | `limit?` | Every project with memory, entry counts, current marker |
+| `index` | `project?` | One project's `MEMORY.md` |
+| `read` | `project?`, `file?` | One topic file; without `file`, the topic listing |
+| `search` | `query`, `project?`, `limit?` | Matching lines as `file:line: text` |
+
+`project` accepts a full key, a key suffix, or a unique substring. Every response passes the
+same redactor and a 20 KB cap.
+
+## Security model
+
+The threat model is concrete: notes written for one vendor's model provider are about to be
+sent to a different one.
+
+- **Read-only.** No code path writes, moves, or deletes anything under `claudeHome`.
+- **Confined.** Every path is `realpath`-resolved and must stay inside `claudeHome`; a
+  symlinked file pointing outside is rejected. Topic names containing a path separator are
+  rejected.
+- **Redacted before injection.** 13 rules cover provider key shapes, bearer tokens, PEM
+  blocks, JWTs, `password`/`token`/`secret` assignments with an entropy floor, connection
+  strings with inline credentials, and long hex blobs. A false positive costs one masked
+  line; a false negative ships a credential, so the policy leans conservative.
+- **Untrusted framing.** The injected block tells the model the notes are background, never
+  instructions — memory text must not be able to steer the agent.
+- **No dependencies.** The plugin imports only `node:*`, so there is no third-party code in
+  the trust path and it resolves in a profile whose `node_modules` lacks the harness
+  packages.
+- **Prompt text is a string.** Providers read a synchronously refreshed cache; they never
+  return a promise.
+
+Redaction is pattern-based, not a classifier. It cannot catch a secret that does not look
+like one. Use `redactMode: report` to audit what *would* be masked, and
+`enableMemory: false` as the kill switch.
+
+## Tests
+
+```bash
+npm test              # smoke + plugin + schema + live
+npm run test:unit     # fixture-only, no real ~/.claude needed
+```
+
+| File | What it covers |
+|---|---|
+| `test/smoke.mjs` | Paths, redaction, store, budgeting, tool — against a synthetic fixture in the OS temp dir |
+| `test/plugin.mjs` | Loader contract against a fake Cordis context, including agent-scoped shadowing |
+| `test/schema.mjs` | The hand-written tool schema against the real `@deepseek-ai/dsh-tools` validators; skips when DSH is absent |
+| `test/live.mjs` | Optional check against a real `~/.claude`; asserts no credential-shaped text reaches the prompt, skips when absent |
+
+76 assertions, no network, no model calls.
+
+## Case study: two things that are easy to get wrong
+
+Both findings come from reading the ecosystem's existing plugins and a real memory store.
+They apply to any DSH plugin that bridges another agent's files.
+
+### 1. Prompt providers are synchronous — an `async` provider renders as a `Promise`
+
+`dsh-system-prompt` resolves section and context text **without awaiting it**
+(`lib/index.js:330,337`), and the interpolator then calls `text.indexOf`
+(`lib/index.js:152`). A provider declared as `async () => string` therefore yields a
+`Promise`, not a string.
+
+The most prominent Claude Code bridge in the ecosystem
+([`YYTbit/dsh-plugin-claude-bridge`](https://github.com/YYTbit/dsh-plugin-claude-bridge),
+`src/index.ts:75,92,107`) registers async providers. Loading is not the same as rendering:
+the plugin mounts cleanly and then fails at assembly. This plugin keeps a synchronously
+refreshed cache and returns plain strings.
+
+### 2. Claude Code files memory under the git repository root
+
+Memory lives at `~/.claude/projects/<encoded-project-path>/memory/`, where the path is the
+project directory with `/` replaced by `-`. The question is *which* directory counts as the
+project. Measured on the author's machine, on a docs hub that sits inside a larger repo and
+has no `.git` of its own:
+
+| Observation | Value |
+|---|---|
+| The hub session's recorded `cwd` | the hub directory |
+| Its `Write`/`Edit` calls into a `memory/` path | 12, **all** under the enclosing repo's key |
+| References to the enclosing repo's `memory/MEMORY.md` in that session | 235 |
+| References to its own directory's `memory/` path | **0** |
+| `.git` at hub / parent / grandparent | no / no / **yes** |
+
+Session *transcripts* are stored under the cwd slug; **memory is stored under the git
+repository root**. A bridge that resolves by `process.cwd()` — or that stops at the exact
+cwd — silently reads the wrong project's notes for any hub directory. Memory directories are
+also created on demand: across 50 project directories on that machine, only 20 had a
+non-empty index and 21 had an empty `memory/`, so "no memory directory" is normal and does
+not mean the directory was unused.
+
+## Known limits
+
+- **Not a session-history reader.** It reads memory files, not transcripts. "What was I doing
+  an hour ago" needs the `*.jsonl` transcripts — out of scope here.
+- **Claude Code's own index cap is not enforced.** Claude Code loads the first 200 lines or
+  25 KB of `MEMORY.md`; an over-cap index silently drops entries there. This plugin injects
+  up to `maxIndexBytes` and does not warn about the cap.
+- **Lossy project keys.** `-` is both the separator and a legal character in a directory
+  name, so display paths are recovered by walking the filesystem and fall back to the raw
+  key tail.
+- **No watcher.** Freshness comes from `refreshMs` checked at prompt assembly, so an edit
+  made mid-turn lands on the next assembly.
+- **Index only for the resolved project.** Other projects need a tool call.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,187 @@
+# dsh-claude-memory
+
+一个只读的 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件，把
+**Claude Code 已有的项目记忆**接进 DSH —— 让 Claude Code 额度耗尽后，任务能在 DSH 里接着做。
+
+English: [README.md](README.md)
+
+```
+~/.claude/CLAUDE.md          ─┐
+  @import 已内联              │
+~/.claude/projects/<key>/     ├─► 收敛 ─► 脱敏 ─► 字节预算 ─► DSH system prompt
+  memory/MEMORY.md  (索引)    │                              + claude_memory 工具
+  memory/<topic>.md (正文)   ─┘
+```
+
+## 它做什么
+
+- 把解析到的项目 `MEMORY.md` 索引注入 system prompt，同时注入用户级
+  `~/.claude/CLAUDE.md`（其 `@path` import 会被内联展开）。
+- 注册一个 `claude_memory` 工具，让模型按需打开某条记忆、列项目、或跨主题搜索 ——
+  完整正文默认不进 prompt。
+- 在内容到达模型服务商**之前**就把凭据形状的文本打码。
+- 绝不写入、移动或删除 Claude home 下的任何文件。
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-claude-memory
+```
+
+需要重启 profile —— `dsh.profile.bundles` 里的新 bundle 是启动时读取的，不热加载。
+
+从本地目录安装：
+
+```bash
+dsh plugin --profile web add /path/to/dsh-claude-memory
+```
+
+验证配置树：
+
+```bash
+dsh --profile web --dump-config | grep -A 10 claude-memory
+```
+
+## 配置
+
+默认值在包内的 `cordis.patch.yml`；可在 profile 的 patch 层或 `--patch` 覆盖层里改。
+
+| 字段 | 默认 | 含义 |
+|---|---|---|
+| `claudeHome` | `~/.claude` | Claude Code home，所有读取都收敛在这个根下 |
+| `cwd` | `process.cwd()` | **仅兜底**。会话的 `agent.session.header.cwd` 永远优先 |
+| `includeDescendants` | `true` | 是否列出有记忆的兄弟/子项目 |
+| `descendantLimit` | `12` | 最多列出几个其他项目 |
+| `maxIndexBytes` | `24000` | 注入记忆块的字节预算 |
+| `maxGlobalBytes` | `6000` | `CLAUDE.md` 加内联 import 的字节预算 |
+| `enableMemory` | `true` | 是否注入记忆块 |
+| `enableGlobalInstructions` | `true` | 是否注入用户级指令 |
+| `enableTool` | `true` | 是否注册 `claude_memory` 工具 |
+| `redactMode` | `on` | `on` 打码、`report` 只统计、`off` 关闭 |
+| `refreshMs` | `20000` | prompt 组装时若缓存超过此值就重读 |
+
+## 实际进入模型的内容
+
+两个 system prompt 段落（order 10 / 11，紧随部署 persona 之后）：
+
+1. **`claude-memory:global`** —— `~/.claude/CLAUDE.md`，`@path` 已内联。DSH 自带的指令
+   加载器**不解析 import**，且读的是 `$DSH_HOME/AGENTS.md` 而非 `~/.claude/CLAUDE.md`，
+   所以这里是用户级 Claude Code 记忆唯一的通路。
+2. **`claude-memory:memory`** —— 解析到的项目 `MEMORY.md` 索引，外加按新鲜度排序的其他
+   项目列表。
+
+完整正文只通过工具按需返回，一次一个文件，单次 20 KB 上限。
+
+## 项目解析
+
+决定"该读哪份记忆"的是**会话的工作目录**，不是 `dsh` 服务启动的目录 —— 服务从某个
+checkout 启动、会话在另一个目录跑的时候，两者必然不同。
+
+解析顺序：
+
+1. **exact** —— `<home>/projects/<cwd 编码>/memory/` 存在；
+2. **git-root** —— 外层 git 仓库根对应的键有记忆；
+3. **freshest** —— 都没有时，在祖先与子项目里选索引更新时间最新的（并明确告知模型这是猜测）。
+
+规则 2 的存在是因为 **Claude Code 把记忆归档在 git 仓库根下，而不是原始工作目录** ——
+见下方案例研究。规则 2、3 下其他项目按新鲜度倒序列出，最新那个一次工具调用就能取。
+
+`agent.session.header.cwd` 与第一方 `dsh-agent-instructions` 读的是同一个来源。段落先以
+全局注册作兜底，再在 `agent/created` 时**按 agent 作用域 shadow**；工具则按调用方
+`exec.agent` 逐次解析，因此子 agent 或在别处启动的会话看到的是自己的项目。
+
+## `claude_memory` 工具
+
+| action | 参数 | 返回 |
+|---|---|---|
+| `projects` | `limit?` | 所有有记忆的项目、条数、当前标记 |
+| `index` | `project?` | 某个项目的 `MEMORY.md` |
+| `read` | `project?`、`file?` | 某个主题文件；不给 `file` 则列出主题 |
+| `search` | `query`、`project?`、`limit?` | 匹配行，格式 `file:line: text` |
+
+`project` 可传完整键、键后缀或唯一子串。所有返回都过同一个脱敏器并受 20 KB 上限约束。
+
+## 安全模型
+
+威胁模型很具体：为 A 厂商模型写的笔记，即将发给 B 厂商。
+
+- **只读**：没有任何代码路径写入、移动或删除 `claudeHome` 下的文件。
+- **收敛**：每个路径都经 `realpath` 解析且必须落在 `claudeHome` 内；指向外部的符号链接
+  会被拒绝；含路径分隔符的主题名会被拒绝。
+- **注入前脱敏**：13 条规则覆盖厂商 key 形状、Bearer token、PEM 块、JWT、带熵阈值的
+  `password`/`token`/`secret` 赋值、内联凭据的连接串、长 hex 串。误报代价是一行被打码，
+  漏报代价是把凭据发出去 —— 所以策略偏保守。
+- **不可信框定**：注入块明确告诉模型这些是背景笔记而非指令，记忆文本不能操纵 agent。
+- **零依赖**：只 import `node:*`，信任链里没有第三方代码，且在 `node_modules` 为空
+  （不含 harness 包）的 profile 里也能解析。
+- **prompt 文本是字符串**：provider 读同步刷新的缓存，永不返回 Promise。
+
+脱敏是基于模式的，不是分类器，抓不住"不像凭据的凭据"。用 `redactMode: report` 审计
+"哪些会被打码"，用 `enableMemory: false` 作为总开关。
+
+## 测试
+
+```bash
+npm test              # smoke + plugin + schema + live
+npm run test:unit     # 仅 fixture，不需要真实 ~/.claude
+```
+
+| 文件 | 覆盖范围 |
+|---|---|
+| `test/smoke.mjs` | 路径、脱敏、存储、预算、工具 —— 全部跑在系统临时目录里的合成 fixture 上 |
+| `test/plugin.mjs` | 假 Cordis ctx 下的 loader 契约，含 agent 作用域 shadow |
+| `test/schema.mjs` | 手写工具 schema 过真实 `@deepseek-ai/dsh-tools` 校验器；无 DSH 时跳过 |
+| `test/live.mjs` | 可选：对真实 `~/.claude` 检查"没有凭据形状文本进入 prompt"；无 store 时跳过 |
+
+共 76 项断言，无网络、无模型调用。
+
+## 案例研究：两件容易做错的事
+
+两个发现都来自阅读生态里已有的插件与一份真实记忆库。对任何"桥接另一个 agent 文件"的
+DSH 插件都适用。
+
+### 1. prompt provider 是同步的 —— `async` provider 会渲染成 `Promise`
+
+`dsh-system-prompt` 解析段落与上下文文本时**不做 await**（`lib/index.js:330,337`），随后
+插值器调用 `text.indexOf`（`lib/index.js:152`）。所以声明成 `async () => string` 的 provider
+返回的是 `Promise` 而不是字符串。
+
+生态里最知名的 Claude Code 桥接插件
+（[`YYTbit/dsh-plugin-claude-bridge`](https://github.com/YYTbit/dsh-plugin-claude-bridge)，
+`src/index.ts:75,92,107`）注册的正是 async provider。**能加载不等于能渲染** —— 插件挂载
+正常，组装时才失败。本插件用同步刷新的缓存，返回普通字符串。
+
+### 2. Claude Code 把记忆归档在 git 仓库根下
+
+记忆位于 `~/.claude/projects/<项目路径编码>/memory/`，路径编码是项目目录把 `/` 换成 `-`。
+问题在于**哪个目录算项目**。在作者机器上，对一个位于更大仓库内、自身没有 `.git` 的文档
+hub 实测：
+
+| 观察项 | 值 |
+|---|---|
+| 该 hub 会话记录的 `cwd` | hub 目录 |
+| 它写入 `memory/` 的 `Write`/`Edit` 调用 | 12 次，**全部**落在外层仓库的键下 |
+| 该会话引用外层仓库 `memory/MEMORY.md` 的次数 | 235 |
+| 引用它自己目录 `memory/` 路径的次数 | **0** |
+| hub / 父目录 / 祖父目录是否有 `.git` | 无 / 无 / **有** |
+
+**会话记录**按 cwd 编码存放，**记忆按 git 仓库根存放**。按 `process.cwd()` 解析、或只认
+精确 cwd 的桥接插件，在任何 hub 目录下都会静默读错项目的笔记。另外记忆目录是**按需创建**
+的：那台机器 50 个项目目录里只有 20 个有非空索引，21 个是空 `memory/` —— 所以"没有记忆
+目录"很正常，不代表那个目录没被用过。
+
+## 已知边界
+
+- **不读会话流水**。它读记忆文件，不读 transcript。"我一小时前在做什么"需要 `*.jsonl`，
+  不在本插件范围内。
+- **不强制 Claude Code 自己的索引上限**。Claude Code 只加载 `MEMORY.md` 的前 200 行或
+  25 KB，超限的条目在那边会被静默丢弃；本插件按 `maxIndexBytes` 注入，不对该上限告警。
+- **项目键有损**。`-` 既是分隔符也是目录名的合法字符，所以展示路径靠遍历文件系统反查，
+  失败时退回键尾。
+- **没有文件监听**。新鲜度靠 prompt 组装时检查 `refreshMs`，所以一轮对话中途的改动会在
+  下一次组装生效。
+- **只注入解析到的那一个项目的索引**。其他项目需要工具调用。
+
+## 许可证
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,21 @@
+# dsh-claude-memory — profile patch layer.
+#
+# Inserted by `dsh plugin --profile <name> add <path-to-this-package>`.
+# The row is deliberately minimal: the plugin's own module export declares
+# `inject: ['systemPrompt', 'tools']`, so no `inject` key is set here (setting
+# an empty one would shadow the declaration).
+- insert:
+    - id: claude-memory
+      name: dsh-claude-memory
+      config:
+        # System-prompt budget for the current project's MEMORY.md index.
+        maxIndexBytes: 24000
+        # Budget for the user-global ~/.claude/CLAUDE.md (with @imports inlined).
+        maxGlobalBytes: 6000
+        # List child projects that have memory (e.g. sub-repos of a hub dir).
+        includeDescendants: true
+        descendantLimit: 12
+        # 'on' masks credential-shaped text; 'report' counts only; 'off' disables.
+        redactMode: on
+        # Re-read the store when a prompt is assembled and the cache is older.
+        refreshMs: 20000

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "dsh-claude-memory",
+  "version": "0.1.0",
+  "description": "Read-only DeepSeek Harness plugin that surfaces Claude Code's project memory, redacted and byte-budgeted",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs && node test/plugin.mjs && node test/schema.mjs && node test/live.mjs",
+    "test:unit": "node test/smoke.mjs && node test/plugin.mjs",
+    "test:live": "node test/live.mjs",
+    "prepublishOnly": "npm run test:unit"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "claude-code",
+    "memory",
+    "agent-memory",
+    "context"
+  ],
+  "author": "GodCC6",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GodCC6/dsh-claude-memory.git"
+  },
+  "homepage": "https://github.com/GodCC6/dsh-claude-memory#readme",
+  "bugs": {
+    "url": "https://github.com/GodCC6/dsh-claude-memory/issues"
+  }
+}