dsh-memory

English | 中文

dsh-memory

A cross-session memory plugin for DeepSeek Harness (dsh).

The main agent decides whether this turn produced anything worth keeping across sessions: a per-turn system-prompt reminder ("when this turn has something worth keeping, you MUST use the memory tool" — off via autoMemory: false) points the timing at the single memory tool (recall = search + read, remember = create / replace / edit in place; its read/write surface is locked to the memory root, and its description carries the usage mechanics and organization rules). Retrieval (recall + keywords) is block-level search (optional vector fusion, per-day recency decay). Writes into the long-term layer FOLLOW the composition of the search results — only memory that gets searched proves worth remembering; it is never pre-judged at capture time. Bundle plugin form (dsh.bundle) — 0 patches, zero npm dependencies, zero build step; @deepseek-ai/* resolves through dsh's flat module fallback, so the runtime shares one package instance.

⚠️ Use with caution. A memory system designed around personal ideas (after studying several agents) — works well for me but may not suit everyone. The storage layout, tool interface, and config options may change frequently and WITHOUT compatibility guarantees (breaking changes are the norm). Check the commit history before upgrading, and back up your memory files under the memory root if they matter to you.

Features

No commands — the per-turn reminder tells the model when the memory tool must be used; retrieval is the recall mode of that same tool.

Storage layout

A single global memory root shared by all workspaces; project directories stay untouched. The root comes from the memoryRoot setting (empty falls back to the plugin data root $DSH_HOME/dsh-memory):

<memory root>/
├── topics/
│   ├── <topic>.md          # long-term memory: one topic per file (short kebab-case names), never decays, never windowed
│   └── ...
└── YYYY-MM-DD/
    └── <workspace-slug>.md # one file per workspace per day (diary layer, subject to the search window)

• Two-layer semantics: play-by-play events go to the diary; the long-term topic files are consolidated AT REUSE TIME ONLY — whether to write follows the search-result composition (a hit long-term block is authoritative, stale statements corrected in place, overlaps merged; daily-only hits with proved-lasting facts → write into topics/<topic>.md), never pre-judged at capture
• Rename transition (memory/ → topics/): the search index covers ANY non-date directory, so existing files under the old memory/ stay searchable and readable (their hit rows give memory/<name>, which addresses them directly); new writes always land in topics/
• No capture bookkeeping: no watermarks, turn counters, or hit counters; dates and the window are resolved at query time and roll over to the new day's file automatically at midnight. The only derived file on disk is the vector cache .vector-cache.json (only when vectors are configured; regenerable, invisible to the search corpus)
• rel paths carry the date, so every hit's age is visible at a glance

Install

dsh plugin --profile web add "github:zhouzhencheng07/dsh-memory"

The package declares dsh.bundle.patch, so it is activated as a profile bundle layer (not just an inert dependency). Restart dsh web after installing; toggle it any time from the Plugins panel in settings. To update: push to GitHub, then dsh plugin --profile web update dsh-memory + restart (git dependencies are cached per commit, so an update is required to pick up new commits).

Zero npm dependencies: @deepseek-ai/* resolves at runtime through dsh's flat module fallback ($DSH_HOME/profiles/node_modules), sharing the same package instances as the running dsh.

How it works

• src/index.js: the per-turn reminder is a systemPrompt.context contribution (dsh-memory:auto, order 200) gated on autoMemory and on subagents (delegationDepth > 0) — its text carries timing only. The single two-mode memory tool: recall runs the search on keywords or reads one note/block addressed by date/topic (+block) and records the observation; remember goes through the createIfAbsent/CAS guard with content and publishes atomically (tmp + rename), or validates the observation and unique match with old_string before a read-modify-write. The observation guard is keyed per session (mirroring @deepseek-ai/dsh-fs-observation-policy), and all file work is done by the plugin itself via node:fs (the sandbox fence lives inside the fs backend — dsh-fs-sandbox's checkedTarget; both the native pipeline and direct ctx.fs calls refuse $DSH_HOME writes under workspace-write, and the tool layer's only widening path needs per-write manual approval; a plugin writing its own data root is trusted host behavior, with path derivation/whitelisting keeping the write surface bounded). Retrieval ends its output with a composition-branched consolidation hint
• src/search.js: any heading (#–######) is a chunk boundary and subsections become standalone blocks with ancestor breadcrumbs; single-field positional keyword scoring — one keywords string split on whitespace, the first 3 terms are essential (×3 per hit) and the next 2 refining (×1), first-occurrence dedupe, over-cap drops reported back; IDF term weighting (BM25-style idf normalized over the corpus: df=1 weighs exactly 1, df=N weighs ~0 — generic words cannot carry a hit) and word-boundary counting for pure-alphabetic ASCII keywords (log ≠ catalog); partial credit per matched keyword; the weighted count is normalized by block length; each block's score is multiplied by max(0.4, 0.5^(days/30)) (per-day decay); blocks under MIN_SCORE=0.5 never return; exact dedup via rel#breadcrumb. hitAddress() renders a rel as its path-free address and findBlock() turns the printed breadcrumb into a stable cross-call read key
• src/embed.js: optional vector path — in-memory index with sha1 signature caching (unchanged files are never re-embedded), cosine ≥ 0.45 joins the fusion, RRF k=60; embedding model defaults to bge-m3
• src/store.js: pure-function vocabulary — path/slug/date derivation (both slash spellings of a cwd normalize to one slug), memory-root resolution (the memoryRoot setting first, falling back to $DSH_HOME/dsh-memory), walkMemory(windowDays, root) (the hard window applies ONLY to subdirectories whose name parses as a date — aged diaries leave the index but stay on disk; non-date dirs like topics/ are always indexed), and resolveDiary() (diary addressing: date-stamp validation plus exact or substring workspace-label matching, with an ERROR on several matches rather than a silent resolve to the wrong workspace)
• client/bundle.js: hand-written client bundle registering into the settings.plugin.item keyed slot (key: 'dsh-memory'); reads and writes go through the official client settings scope (ctx.settingsScope.bind) — revision-fenced mutations, mirror refreshes on document commits/reconnects
• New-vs-old conflicts resolve at query time: decay favors newer notes, and the tool description instructs merging multiple hits on the same topic instead of trusting only the newest one

Usage

# model-side tool: search the memory library (ONE keywords parameter, up to 5
# terms, most essential FIRST)
memory mode="recall" keywords="vector search threshold embedding"

# model-side tool: read today's memory note (recall with no address) — returns
# the full text; ABSENT means there is none yet
memory mode="recall"

# a hit row IS the read key: copy its address back to read the whole block
#   a row looks like:  - [2026-08-20 · D-Project-dsh-plugin-dsh-memory] 工具链 > pnpm (score 1.2)
memory mode="recall" date="2026-08-20" workspace="dsh-memory" block="工具链 > pnpm"

# read and write a long-term topic file
memory mode="recall" topic="windows-env"
memory mode="remember" topic="windows-env" content="# Windows environment lessons ..."
memory mode="remember" topic="windows-env" old_string="pnpm dual instance" new_string="pnpm dual instance (avoid via --allow-scripts since 2026-08)"

# today's note: absent -> create with content; just recalled -> revise with old_string
memory mode="remember" content="# Topic ..."
memory mode="remember" old_string="old sentence" new_string="new sentence"

With autoMemory: true (default) every turn carries a short reminder — when this turn produced something worth keeping across sessions, the memory tool must be used. With autoMemory: false there is no reminder — record only when asked.

Configuration

$DSH_HOME/settings.yaml (hot-reloaded, no restart needed; also editable via the settings card):

dsh-memory:
  memoryRoot: ''            # memory library root; empty = $DSH_HOME/dsh-memory. Changing it switches libraries — existing notes stay where they are
  searchLimit: 2            # number of results returned by recall (1-10); a hard cap the agent cannot override; a long-term block is still surfaced by the longtermAppend seat
  dailyWindowDays: 45       # diary hard window in days: aged diaries stop participating in search (0 = unlimited); topics/ is exempt
  embeddingBaseUrl: ''      # Ollama-compatible /api/embed base URL (e.g. http://localhost:11434); empty disables vector search
  embeddingModel: 'bge-m3'  # embedding model name
  autoMemory: true          # per-turn reminder ("worth keeping -> must use the memory tool"); false = record only when asked
  longtermAppend: true      # when no long-term block made the list, append the best-ranking one (no eviction); false = pure top-N

Requirements

• Node.js ≥ 22 (dsh requirement)
• Plain ESM, zero dependencies, zero build step; with no embedding service configured there are no network calls at all

License

MIT