dsh-claude-memory
A read-only 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
~/.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
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:
dsh plugin --profile web add /path/to/dsh-claude-memory
Verify the row composed:
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):
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.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:
- exact —
<home>/projects/<encoded-cwd>/memory/ exists;
- git-root — the encoded key for the enclosing git repository root has memory;
- 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
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,
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
