dsh-memory-delta
English | 中文
Layered, auto-injected cross-session memory for AI coding agents.
A DSH (DeepSeek Harness) plugin, plus a
zero-dependency standalone CLI. It borrows the spec / change / archive discipline from
OpenSpec — but pushes instead of pulls.
Canonical repository: GitHub ·
Gitee is a read-only mirror —
please file issues and pull requests on GitHub.
Status: M1–M4 done; M3/M4 (differential injection, both tools, the distillation nudge) were
verified inside a real DSH session, and the later improvements are covered by 1283 assertions
plus a real-machine preflight. See Verification.
Questions? → FAQ — "is the whole memory re-sent on every turn?", "what happens when a
store goes over budget?", "archive vs withdraw vs supersede", "does this duplicate AGENTS.md?".
中文版：常见疑问。
Why
AI coding assistants have two recurring problems:
- A new session remembers nothing. You re-explain the background, your preferences, and every
conclusion you already reached.
- What does get remembered is unmanaged. Everything piles into one or two Markdown files that grow
without bound, cost more every session, and — worst of all — stale conclusions are never removed.
Existing spec-driven tools (OpenSpec and friends) solve "the code drifts away from the plan". But they
are pull-based: the agent has to be told to go read the specs, so a fresh session does not
spontaneously remember anything. dsh-memory-delta is push-based: at session start the agent is handed what
it should know — but only the distilled part, and only what changed. Details stay retrievable on demand.
Design
┌─ PUSH: injected automatically at session start (hard byte budget)
│ T0 identity & conventions user preferences / machine facts / accounts
│ T1 index & next actions what to pick up
store ──┤
└─ PULL: retrieved on demand (costs nothing by default)
inbox/ candidate entries — **the only layer the model may write**
facts/ current truth (only status=active is injected)
decisions/ choices plus their reasons (append-only)
archive/ superseded entries
journal.md activity log (never injected)
Read the directory names along two axes (this was unclear before — facts especially invites the wrong
guess: it is a kind of content, not a stage of the flow):
| Directory | Stage in the flow | What it holds | Who may write | Injected? |
|---|
inbox/ | candidate (unconfirmed) | conclusions the model thinks are worth keeping | only the model (memory_write) | ❌ never |
facts/ | standing | pitfalls hit + how to avoid them: environment limits, tool behaviour, real failures and their fixes | only the human (promote) | ✅ every turn |
decisions/ | standing | conventions you decided: business / process / taste calls — so you never have to answer twice | only the human (promote) | ✅ every turn |
archive/ | archived | retired entries: superseded, or no longer applicable | moved on supersede/archive | ❌ never (still searchable, restorable) |
The main flow: the model may only write inbox/ → the human promotes into facts/ or decisions/ →
retired entries move to archive/. Unsure which side an entry belongs to? Ask: "if the world changes
tomorrow, does this stop being true?" Yes → facts/; only you can invalidate it → decisions/.
Two writing habits that make these layers actually useful: a facts/ entry should say when it applies
(a pitfall is worth recording so it is not hit twice, not because it once happened); a decisions/ entry should
say why it was decided — with the reason, the agent can judge by itself instead of asking you again.
mem init writes the full explanation of these four directories (plus journal.md / index.md /
memory.config.json) into the store's own README.md — open the memory directory and it is right there.
Seven rules:
- The pushed part must be tiny. Everything in the injected layer is paid for on every session, so the
journal and design docs stay out of it. Measured on a real store (31 standing entries): 4369 bytes total
for 31 entries — about 141 bytes per entry, so a 5 KB budget holds a store of this size. Two things are
deliberately left out of the text: entry ids (diff metadata, kept in a side-car state file and never
sent to the model at all; inlining them used to eat 34% of the budget) and keys that are identical to the id
(
createEntry names the file after the key, so on a real store 30 of 31 keys were byte-identical to the id —
repeating them cost 15% of the budget for nothing). Each line is also clipped at 90 characters.
- Only the delta is pushed. Every entry carries a 12-char content hash; the plugin remembers the
previous round's state and next round pushes only added / updated / removed. When nothing changed it
injects nothing at all. (The upstream
dsh-agent-instructions plugin has no diffing: any file
change re-injects the whole file — measured at ~58k wasted tokens for 15 edits of one 8.5 KB file.)
- State lives in a side-car file,
<harness home>/storages/dsh-memory-delta/inject-state/<session-id>.json
(the directory resolves through config.stateDir → the kernel's ctx.dshHomePath service → $DSH_HOME →
~/.dsh. Fixed 2026-10-01: it used to read $DSH_HOME only, but the official desktop build's home is
the default ~/.dsh, so that variable is absent in its host process — the side-car was silently never
written and every restart re-injected the full memory).
⚠️ Changed 2026-09-30: the {id: hash} map used to ride inside the injected message's source, which
violates the DSH session-format v0 whitelist (a plugin source may only carry
kind/plugin/form/sections/summary). The format migration then refuses the whole session, leaving it
permanently unreadable (14 sessions were lost that way on the author's machine and had to be repaired by
hand). The state is also written only after the message has actually entered the context, so a queued
message that gets dropped again cannot silently advance the baseline.
- The model may only write to the inbox. A wrong conclusion that silently reaches the standing layer
gets re-injected forever. Promotion is an explicit
promote.
- One key, one truth. Facts and decisions carry a semantic , and only one entry may
exist per . A new conclusion must explicitly the old one — that gate is what
keeps memory rot out of the injected layer.
Install (as a DSH plugin)
⚠️ This section is the result of real trial and error — both wrong turns below are silent failures:
❌ Adding the package to package.json's dsh.profile.bundles
→ DSH regenerates that list from the market registry (.generations/desired.json) at boot;
entries it does not know about are dropped.
❌ Writing a bare entry in cordis.patch.yml
→ silently ignored (a patch entry only targets an existing id for config/disable).
✅ Wrapping it in `- insert:` inside cordis.patch.yml
Steps (DSH_HOME is usually %APPDATA%\dsh-desktop\harness):
-
Copy this package into the profile's node_modules:
<DSH_HOME>\profiles\web\node_modules\dsh-memory-delta\
package.json
bin\mem.mjs
src\plugin.mjs src\hook.mjs src\planner.mjs
-
Append to <DSH_HOME>\profiles\web\cordis.patch.yml:
- insert:
- id: dsh-memory-delta
name: dsh-memory-delta
config:
root: '' # empty = <session cwd>/memory
# maxBytes: 4096 # optional. Omit = the store's memory.config.json#injectBudget decides (then 3072)
enabled: true
dueWithin: 0 # remind this many days before verify_when (0 = only when due)
panel: true # the memory tab's state/action routes
allowWrite: true # let panel buttons write the store (promote / rename)
skill: true # register the bundled skill (/dsh-memory-delta documents usage + boundaries)
-
Save. The patch layer is watched (watchUserPatches) — it hot-reloads, no restart needed.
Uninstall: remove that - insert: block and delete node_modules\dsh-memory-delta.
Listed in the plugin market (lpf20200901/dsh-memory-delta) — installing from there goes through the
bundle patch shipped in this package, which deliberately does not set maxBytes (the store's own
config decides). The manual steps above remain the local-development path.
Also published on npm as dsh-memory-delta: npm i -g dsh-memory-delta gives you the mem CLI
(same store, same ranking code as the plugin), and DSH can install straight from the registry with
cd ~/.dsh && dsh plugin --profile web add dsh-memory-delta.
⚠️ Known hazard: installing or removing another plugin through the market rewrites the profile's
cordis.patch.yml, and a hand-written - insert: block — comments included — is dropped. Observed
2026-10-08: installing a third-party plugin silently removed this plugin's block, leaving it in a
"files present, never loaded" state — the files were still in node_modules, but nothing was injected
any more and /dsh-memory-delta had vanished from the skill catalog, with no log line anywhere.
Check: does cordis.patch.yml still contain - id: dsh-memory-delta?
Fix: paste the - insert: block back and save — it hot-reloads (refresh the page for the client tab).
What the plugin provides
| Capability | Detail |
|---|
| Differential injection | First round injects every active entry (baseline); afterwards only added / updated / removed; nothing at all when unchanged |
memory_search | Relevance-ranked search across facts / decisions / inbox / archive / journal / session index. Field weights (key/id > tags > conclusion > body), a whole-phrase bonus, and Chinese matched by bigram so a query like 沙箱禁管道 hits 沙箱禁止命名管道 without spaces. Each hit carries a score, a snippet from its best-matching line, its tags/date, and the path of its file (read it for the full conclusion and reason, since the snippet is clipped); truncated tells the model when limit cut the list short. Every hit is rendered into the tool's text output — DSH only ever shows the model what render returns (see the regression note below), and the tool's default limit is 10 because each rendered hit costs ~300 bytes |
memory_write | Record a candidate into the inbox — the model cannot touch the standing layer |
| Distillation nudge | Once a session has run a few steps and memory is already current, it reminds the model to record conclusions with memory_write; one nudge per session, and the nudge message carries no state, so it cannot corrupt the diff baseline |
| Due-for-review reminder | verify_when is no longer a dead field: when an entry reaches its review date, the session is told once — "this conclusion may be stale, re-check it" — with the commands the user should run to supersede or expire it — retiring a standing entry is a human action, so the model is told to hand it over (it may only add the new conclusion to the inbox as a candidate). Prose values (等换机器时) never trigger it, so the reminder can always be resolved; it fires only on a step that injects nothing else, and it carries no state either |
| Bundled skill | On apply the plugin registers a skill named dsh-memory-delta through ctx.skills.register() — runtime registration, so nothing is written into your skill directories and uninstalling/reloading the plugin removes it again. In any workspace that has the plugin, typing brings up the usage rules and the permission boundary (the model may only write the inbox; promoting/archiving is a human action), and the model itself can load it when the description matches. Set if you do not want that extra line in the skill catalog |
The plugin never spawns the CLI: the DSH sandbox forbids named pipes (capturing a child's output fails
with EPERM), and there is no need — it imports the same store module directly (bin/mem.mjs only runs
the CLI when executed as the entry point). It also never requires the sidebar or the skill service:
webServer and skills are optional capabilities, registered through ctx.inject([...], cb) so the
callback runs once the service is ready — reading them with ctx.get at apply time silently yields
nothing (a real bug here: the tab opened to an HTTP 405). A headless or CLI-only composition therefore loads
the plugin unchanged and simply skips the panel routes and the bundled skill.
The 记忆 tab in the sidebar
The 记忆 tab, opened from the sidebar's + menu: collapsible groups (the monospace text after a
title is the directory on disk), standing entries with their keys/tags/dates/file names, the
due-for-review section, the inbox candidates, and how many bytes the current store costs per session.
Clicking an entry opens it in the editor; the panel's own writes all go through one
whitelisted POST /dsh-memory-delta/action route (promote / withdraw / archive / restore / delete
candidate / safe rename / assign topic / rename topic / batch) — there is no generic edit back door,
and allowWrite: false turns the whole route off.
Two defaults that keep the tab calm: the archived stage is collapsed by default (retired conclusions
should not push the live entries out of view) and the archive reads in three levels —
archived → category → topic → entries. The category is why it left (the category field). Three of them
are always there (an empty one still shows 0): 已蒸馏 (distilled into the docs / superseded),
已废弃 (useless for good) and 暂时不用 (not needed right now, but this workspace or another business need
may want it again — restore → promote brings it back). Archiving lets you pick one or type a new one
(single or batch). 已蒸馏 is set automatically when an entry is superseded / distilled into the
docs, and the row's 分类 button changes it later. Below a category, topic rows (the entry's own topic)
are collapsed — click one to see its entries; entries without a topic are listed right under the category.
The archive still follows the header axis: switching to type / tag / date re-groups it too.
The old default name 已过期 (v1.2.x) is grouped as 已废弃 on read and write, so no migration is needed.
Topics have one level: the topic name is just a string (same name = same group; a / in it is an ordinary
character). Earlier versions split parent/child into two levels — that was dropped in favour of the simpler model.
CLI usage
# init (defaults to <cwd>/memory; override with --root or $DSH_MEMORY_ROOT)
mem init --root ./memory --scope "workspace:/path/to/project"
# record a candidate (lands in inbox, never injected)
# --id prefer an explicit short id; otherwise derived from the conclusion (capped at 20 chars)
# --key semantic key: only one active truth per scope+key
mem new --type fact --id win-update-cache --key disk-cleanup \
--conclusion "Cleaning the update cache reclaimed nothing measurable" \
--reason "Directory emptied but free space did not move" --tags windows,disk --source session-abc
# with --key but no --id, the key *is* the id (and the file name): sandbox-no-pipe.md
# without a key the id falls back to "<date>-<truncated conclusion>" — prefer giving a key
# promote it once confirmed; when the key already has an active entry you must say who supersedes whom
mem promote win-update-cache
mem promote win-update-cache-v2 --supersedes win-update-cache
mem set <id> --key k --tags a,b --conclusion "…" # edit an entry (add a key, reword, mark expired)
mem set <id> --topic "DSH plugin dev" # assign the topic the panel groups by ("" clears it → 未归类)
mem rename <old-id> <new-id> # safe rename: frontmatter id + file name + supersedes refs together
# (never rename through the file tree — id must match the file name)
mem list --status active --tag windows
mem list --topic "DSH plugin dev" # or --untopic for the not-yet-classified ones
mem topics [--json] # which topics exist, how many entries each, and how many are unclassified
mem topic-rename <old> <new> # rename a topic across the whole store (the archive too)
mem recall <keywords> --topic "DSH plugin dev" # search inside one topic only
mem show <id>
mem validate [--fix] # format / ids / bidirectional links / cycles / same-key conflicts / index / budget
mem index # rebuild index.md
mem inject [--json] [--budget 3072] # render what should be injected; --json adds per-entry hashes
mem recall <keywords> [--where all|facts|decisions|inbox|archive|journal|sessions|index] [--limit N] [--json]
# relevance-ranked: Chinese is matched by bigram, no spaces needed
mem due [--within N] [--json] # entries whose verify_when is due (--within N also warns N days ahead)
mem journal add "one line"
verify_when takes either a date (2027-03-01) or a relative phrase measured from the entry's own
date (3个月后, 2周后, 立即); anything else is treated as prose and simply never auto-fires.
Verification
Checked item by item inside a real DSH session:
| Capability | Live evidence |
|---|
| baseline injection | the session received every active entry |
| no change → zero injection | the next step injected nothing, only the one-time nudge |
| delta · added | "新增：", explicitly noting "the other N entries are unchanged" |
| delta · updated | after editing one entry, only "已更新：" was pushed |
| due-for-review reminder | adding an entry whose verify_when was 16 days overdue produced a one-time review reminder on the next no-change step, and the step after it injected nothing (the reminder did not reset the diff baseline) |
| sidebar 记忆 tab | the tab opened on a live store and showed the real root, the entry count, "注入 1792 / 3072 字节", the facts/decisions split and the (empty) inbox |
memory_search / memory_write | memory_write called successfully in a live session; memory_search failed — see the tool-output-contract entry below |
| tool output contract | test/preflight-import.mjs now replays the runtime's own step (validateJsonSchemaValue over each tool's declared output.schema) against the values both tools actually return |
| writes land only in the inbox | the written candidate did not enter the injection payload; it appeared as a delta only after promotion |
Development
npm test # 1283 assertions, zero dependencies
| Suite | Assertions | Covers |
|---|
test/run-tests.mjs | 295 | CLI end-to-end (incl. a non-ASCII path regression, ranked recall, mem due, mem rename with reference sync, key-as-file-name, the topic lifecycle, reserved topic names, injection-text slimming, hand-written frontmatter fidelity, and reference cleanup on restore) |
test/planner-tests.mjs | 53 | the diff algorithm, the injected-text rendering, and the source shape having to pass DSH's session-format admission (from v4 the kind must be a producer-owned kind, never plugin) |
test/search-tests.mjs | 56 | tokenizing / per-layer weighting / scoring / snippet selection (pure logic) |
test/due-tests.mjs | 93 | verify_when parsing (dates, relative phrases, prose) and due collection (pure logic) |
test/session-format-tests.mjs | 17 | the session-format contract, checked against the kernel's own admission function (the written source passes v4 admission, the retired plugin wrapper is still refused by it, all four historical read shapes are recognised, and no file hand-writes a kind literal outside memorySource()) |
test/peer-range-tests.mjs | 28 | the peer contract: the declared host ranges must cover every kernel we claim to support — written as one prerelease-tagged caret per supported line (a ^0.1.x caret cannot cross a minor, and the prerelease tuple rule makes a single wide range fail every checker that leaves includePrerelease off); also pins the vendor pairings, the version boundaries, and two corrected-causality controls (both kernel generations do pass includePrerelease, so the old range actually satisfied the real preflight — "the official build was disabled by peers" was a misdiagnosis of mine). SKIPs its 23 semantic assertions without semver; with DSH_REQUIRE_SEMVER=1 a SKIP becomes a failure (used by the release checklist) |
test/hook-tests.mjs | 66 | plugin wiring (fake agent / decision): diff injection, when the side-car state is committed, nudge, due reminder |
|
test/plugin-tests.mjs replaces the four @deepseek-ai/* packages with the stubs in test/stubs/
(via test/stub-loader.mjs) and actually apply()s the plugin, so its behaviour is verifiable
without a DSH installation. test/preflight-import.mjs goes one step further: run it from inside a
profile and it exercises the real @deepseek-ai/* modules (does the real defineTool accept our
tool definitions, does the real schemastery accept our config schema, does each tool's return value
satisfy its own declared output.schema under the real validateJsonSchemaValue, and does its render
text actually carry the hits the model needs).
Regression tests baked in from real bugs:
- With a non-ASCII path, Node's
fs.rmSync fails silently (and can crash the process with
recursive) — unlinkSync must be used instead;
- The DSH sandbox forbids named pipes, so
spawnSync with the default stdio: 'pipe' hits EPERM —
tests must redirect child output to a file;
- An entry written by the tool must carry the session workspace scope, not the harness process cwd;
new URL(import.meta.url).pathname percent-encodes a non-ASCII user name
(C:\Users\李鹏飞 → C:\Users\%E6%9D%8E%E9%B9%8F%E9%A3%9E), which turns "write into my plugin folder"
into "write into a path that does not exist" — always use fileURLToPath;- A field added to some early-return paths of an internal planner function (
due) was destructured
into undefined and threw on every step, which the outer try/catch silently reported as
"failed to load memory" — hence the defensive read and the zero-warning assertion;
- An injected message's
source was tightened in opposite directions by two session-format
generations, and getting either wrong makes a session unusable:
from v4 on (DSH 0.1.7) the kind must be a producer-owned kind — a nonempty string that is
not plugin. The canonical form is {kind:'plugin:<package>'} (exactly what the v3→v4 migration
assigns to a third-party plugin). Writing the old {kind:'plugin', plugin:'<package>'} makes the
encoder throw format v4 message requires a producer-owned source kind on every session-log
write, so every session fails on its first turn.
v3 and earlier still constrain the historical log: a plugin wrapper may carry only
kind/plugin/form/sections/summary (the v0→v1 whitelist), and a custom source.kind (the older
'memory') is refused by the v2→v3 stage (cannot safely transform unclassified message source).
The migration leaves the source artifact unchanged, so every older session that ever received such
a message is permanently unreadable. The diff state therefore lives in a side-car file instead of
the source.
memory_search never worked in a live session, and no test could see it. The tool's declared
omitted / / while attaches to
hit, and DSH validates a tool's return value in with
— so any call that matched at least one entry came back as
(only "no matches" looked healthy). Both test layers had the same blind spot: the stub
is an identity function that validates nothing, and the preflight only called while the
check lives in the runtime, . Fixed by declaring the fields, and pinned from both
sides — a structural contract check in () and the real
in . — the tests now fail loudly if it does not.
Roadmap
- M1 ✅ CLI + structured entries + validate + index/injection budget
- M2 ✅ explicit short ids, semantic keys and "one key one truth",
inject --json diff payload,
validate --fix, mem set
- M3 ✅ DSH plugin: differential injection + both tools + the distillation nudge (verified live)
- M4 ✅ published (GitHub primary / Gitee mirror)
- M5 ✅ the memory got usable at scale: index-style injection (id-free text, ~159 bytes per
entry), relevance-ranked search with Chinese bigrams, and
verify_when turned into a real
due-for-review reminder
- Next keep the store small as it grows; publish to npm
Prior art & acknowledgements
The spec / change / archive discipline — a human-readable current truth, plus a staged change set
that gets archived once it lands — is borrowed from OpenSpec
(MIT).
dsh-memory-delta is an independent implementation: it contains and calls no OpenSpec code, its store
format and CLI are its own, and the direction is inverted — memory is pushed into the session instead
of the agent being told to pull it.
"OpenSpec" is its authors' name/trademark; the mentions here are attribution only, and imply no
affiliation with or endorsement by that project.
License
MIT
