dsh-memory-delta
面向 AI 编程代理的分层、自动注入式跨会话记忆：DSH 插件加独立的零依赖 CLI。借鉴 OpenSpec（MIT）的规范/变更/归档机制，但采用推送而非拉取。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:lpf20200901/dsh-memory-delta#a0736c74dfdb77eb61c9edf56e15163ca9ded42eMemory Delta 以 dsh-memory-delta 发布，当前版本为 1.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
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 M5 improvements below are covered by 825 assertions plus a real-machine preflight. See Verification.
AI coding assistants have two recurring problems:
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.
┌─ 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 initwrites the full explanation of these four directories (plusjournal.md/index.md/memory.config.json) into the store's ownREADME.md— open the memory directory and it is right there.
Seven rules:
source.entries); inlining them used to eat 34% of the budget.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.){id: hash} map from the message it previously injected, so session resume, replay and compaction all
stay correct.promote.key, and only one active entry may
exist per scope+key. A new conclusion must explicitly --supersedes the old one — that gate is what
keeps memory rot out of the injected layer.active / superseded / expired. Superseded entries get bidirectional links
and are archived, never appended forever.⚠️ 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: 3072 # byte budget for the baseline injection
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)
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.
The market/registry publishing flow was not investigated yet; the above is the local install path.
| 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 and a snippet from its best-matching line |
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 exact command to supersede or expire it. 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 |
| Sidebar memory tab | With dsh-better-sidebar installed, a 记忆 tab groups entries by stage in the flow (待你确认 → 已在用 → 已归档, each with one plain-language line plus a flow strip on top), collapsible (a drawn caret), with a search box (entries and the journal, Chinese run-together queries included — the same scoring as mem recall and the model's memory_search). The standing layer can be viewed along three axes: type (facts/decisions — "which side does it belong to"), tag (by topic) and date (when it was recorded, labelled today / yesterday / weekday). Clicking an entry opens its .md through better-sidebar's official openFile (preview/edit in the sidebar editor). : candidates can be promoted, standing entries can be (back to candidates) or , archived ones , candidates — every destructive action goes through an (never , which blocks the page and would hang headless screenshots). The standing layer also shows the (, injected by DSH into every workspace — read-only preview, collapsed by default) and the ( / , with an button that opens them in the sidebar editor). The client half is a (a wrapper, no bundler); its data comes from this plugin's own read-only and routes — loopback-only, JSON in / JSON out, reading nothing but the memory store. The one route that is (promote / withdraw / archive / restore / delete candidate / safe rename); turn it off with |
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: webServer is read
through ctx.get('webServer') (an optional capability), so a headless or CLI-only composition loads the
plugin unchanged and simply skips the panel route.
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 itself never writes to the store; the only
writes are the two inbox buttons (promote / tidy file name).
# 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 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 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.
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 form='due' 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, "常驻 12 条", "注入 1792 / 3072 字节", the facts/decisions split and the (empty) inbox |
memory_search / memory_write | both called successfully in the real runtime |
| writes land only in the inbox | the written candidate did not enter the injection payload; it appeared as a delta only after promotion |
npm test # 825 assertions, zero dependencies
| Suite | Assertions | Covers |
|---|---|---|
test/run-tests.mjs | 180 | CLI end-to-end (incl. a non-ASCII path regression, ranked recall, mem due, mem rename with reference sync, key-as-file-name) |
test/planner-tests.mjs | 43 | the diff algorithm (pure logic) |
test/search-tests.mjs | 51 | tokenizing / scoring / snippet selection (pure logic) |
test/due-tests.mjs | 93 | verify_when parsing (dates, relative phrases, prose) and due collection (pure logic) |
test/hook-tests.mjs | 63 | plugin wiring (fake agent / decision): diff injection, nudge, due reminder |
test/plugin-tests.mjs | 217 | plugin integration (stubbed DSH modules, real apply() + both tools + both panel routes + promote/rename actually writing the store + whitelist/origin checks) |
test/client-tests.mjs | 178 | the sidebar panel bundle (fake React + fake fetch: grouping/collapse, entry click → openFile, promote/tidy, failure states) |
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).
Regression tests baked in from real bugs:
fs.rmSync fails silently (and can crash the process with
recursive) — unlinkSync must be used instead;spawnSync with the default stdio: 'pipe' hits EPERM —
tests must redirect child output to a file;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;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.inject --json diff payload,
validate --fix, mem setverify_when turned into a real
due-for-review reminderThe 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.
MIT
window.confirm~/.dsh/AGENTS.mdAGENTS.mdAGENTS.local.mdwindow.__ModuleLoader__.load({id, factory})POST /dsh-memory-delta/statePOST /dsh-memory-delta/searchPOST /dsh-memory-delta/actionallowWrite: false| Why editing/deleting memory is not built into the panel | The sidebar already ships an editor (opening an entry is enough) and a file tree with confirmed rename/delete. Re-implementing full CRUD in the panel would be duplication plus a permanent maintenance tax, so the panel offers entry points plus the two actions that genuinely need human judgement: open file, one-click promote of an inbox candidate (the human-confirmation step finally has a UI) and tidy the file name (mem rename: id + file name + references together). Pure "jump to the folder" buttons are deliberately not built — a caret to expand plus clicking an entry for detail is enough, and an extra button only adds noise plus a route that launches an external process. ⚠️ Do not rename memory entries through the file tree — the id lives in the frontmatter and must match the file name, or mem validate reports id 与文件名不一致; that is exactly why renaming is a dedicated safe operation instead of free-form editing |