lpf20200901/dsh-memory-delta

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:

1. A new session remembers nothing. You re-explain the background, your preferences, and every conclusion you already reached.
2. 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):

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 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.
• Entries have state: active / superseded / expired. Superseded entries get bidirectional links and are archived, never appended forever.
• Plain Markdown + frontmatter: human-readable, diffable, reviewable, committable like code.

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):

1. 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
   

2. 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)
   

3. 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

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, 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:

Development

npm test        # 1283 assertions, zero dependencies