Local-only project memory with zero bundled runtime dependencies or external services: JSON as the source of truth plus generated PROJECT_MEMORY.md, token-bounded session-frozen Hot Memory for prompt-prefix cache stability, cached cross-project BM25 recall, trusted session/turn provenance, explainable pre-write duplicate/conflict governance, editable importance/pin/tags/supersede/archive lifecycle, configurable top-level turn-end distillation, and a bilingual Web GUI for search, inspection, diagnostics, and live settings.
Install
# from npm (prebuilt)
dsh plugin --profile web add dsh-memoir
# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)
dsh plugin --profile web add github:Qinling-Melon-Farmers/dsh-memoir
Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).
README
Help each new agent session pick up your project. dsh-memoir is a local-first project-memory plugin for DeepSeek Harness (DSH). It persists confirmed work, lessons and next actions, injects bounded Hot Memory into new sessions, and recalls complete history on demand with BM25.
No embeddings, vector database or cloud memory service. The npm package bundles no runtime dependencies; the host supplies DSH and Zod 4 peers. It fits personal and local development workflows, rather than raw chat backups or multi-user cloud sync.
中文 · English · Changelog · Releases
Quick installation
Current release: 0.9.6 (2026-11-19), supporting DSH 0.2.2-rc.3 / Node.js >=24.9.0. This release does not migrate memory, settings or snapshots. Back up DSH_HOME before upgrading; affected historical logs require separate recovery below.
Web: install or update the CLI, then add the plugin to the web profile:
npm install --global @deepseek-ai/dsh@0.2.2-rc.3
dsh plugin --profile web add dsh-memoir@0.9.6
Desktop: check the desktop application's bundled DSH host version first; updating the global CLI does not replace that host. Add the npm package dsh-memoir@0.9.6 through Desktop's native Plugins manager, or use a CLI pointing to the same DSH_HOME to add it to the desktop profile:
dsh plugin --profile desktop add dsh-memoir@0.9.6
Web and Desktop manage plugin installation and activation separately. They share memory and settings files when using the same DSH_HOME and data paths; different homes or machines do not sync automatically. Reload the plugin after installation or upgrade, restarting the relevant dsh web or desktop application if needed. Refreshing a page alone does not reload host plugins. If the UI is missing, check the profile and host version first.
DSH 0.2.2-rc.5 is additionally verified; the development baseline remains rc.3. The recovery CLI accepts only reviewed versions, not every backend within the runtime range.
UI preview
0.9.6: the left-side Memory entry opens the panel directly, with separate Browse, Settings, Hot Memory and Diagnostics views. Native light-theme preview with Chinese UI:

These are historical 0.9.0 previews, not new 0.9.6 screenshots. Component previews use demonstration data. Plugin information, documentation and memory settings stay at the top.

The native plugin detail page reuses Memory settings. The first image shows the actual DSH 0.2.0-rc.1 host UI; the second is a component preview with German agent copy selected in the English GUI.

Historical sources: 0.9.0 offline notice (demonstration data) · 0.7.1 snapshot diagnostics · 0.7.0 native settings · 0.6.2 distillation diagnostics.
Earlier sources: 0.6.1 global project groups · 0.6.1 settings navigation · 0.6.1 scrolling layout · 0.6.0 native view · 0.5.6 memory governance preview · 0.5.6 settings card · 0.5.6 sidebar preview. Link tags identify the release source; filenames retain the original component version.
Usage, capabilities and boundaries
- Open Memory in a project conversation or the right sidebar; memory settings are also available from native plugin details or Settings. The sidebar never opens automatically or replaces another panel; other entries remain available without the sidebar service.
- After working, ask the agent to record conclusions, lessons and next steps, or wait for an eligible distillation reminder. You can also add, edit, pin, archive, restore or supersede entries manually in the panel.
- Search project or global history in Browse, inspect injection candidates for new sessions in Hot Memory, and check the index, query cache, snapshots and write outcomes in Diagnostics.
How it works
Eligible worked turn -> Distillation reminder (separate wrap-up turn)
|
v
memoir_record / memoir_update
|
v
JSON store (single source of truth)
+--> PROJECT_MEMORY.md (readable projection)
+--> BM25 index + query LRU --> memoir_read / GUI search
`--> Hot Memory Selector --> Frozen session snapshot --> system prompt
Reminders require the AND gate; only an actual tool save confirms persistence. Manual writes do not require a reminder first. BM25 recall and Hot Memory selection read structured memory independently; the selector does not depend on BM25 search results.
Tools and memory governance
| Tool | Purpose |
|---|---|
memoir_record |
Record work / lessons / actions / note; return similar or conflicting candidates before writing |
memoir_update |
Keep the id and creation time while changing content, section, importance, tags and lifecycle |
memoir_read |
Recall within project (default) / global / all: ranked search with a query, recent entries per project without one; compact / full output |
Importance ranges from 1–5, with 3 as the neutral default; pinning adds separate Hot Memory weight. Recall defaults to active. Archived and superseded history remains inspectable and restorable, without automatic deletion. Similarity does not establish truth: explicitly choose update, history-preserving supersede, or force-record to keep both. Nothing is merged or deleted automatically.
Project memory stays anchored to the original session project when the execution directory changes. Agent writes retain trusted session/turn provenance, degrading to session-only when necessary. The panel copies identifiers and makes a best-effort jump to the source session, without promising navigation to the exact turn. Manual GUI entries cannot spoof trusted provenance.
Automatic distillation and language
Automatic distillation is observable, cancelable model work, rather than silent chat scraping or a free background task. Defaults are 1 / 0 / 1: each eligible worked turn, no extra cooldown, at least one tool call. autoDistillEvery, autoDistillCooldownMin and autoDistillMinTools use AND semantics and are isolated per agent. Idle, aborted, subagent and successfully recorded turns are skipped; cooldown advances only after a successful reminder.
Reminders queue a separate wrap-up turn with provenance pointing to the source work turn. They preserve the original task answer's turn boundary, neither advance worked-turn cadence nor trigger recursive distillation, and may increase the displayed turn count. Only persisted memoir_record / memoir_update calls suppress that turn's reminder; failed calls or unresolved similarity do not count. Turning off autoDistill leaves manual write tools available.
Diagnostics distinguish reminders, actual saves, failures, cancellation and unavailable receipts. The host may cancel a result after saving, so counts can overlap. A reminder's correlation with a later save proves neither causation nor content correctness. Manual GUI writes are excluded from Agent-tool counts. Upgrading does not rewrite old folded answers: expand the process disclosure or use normal mode to view them. See the changelog for the fix history.
language supports zh / en / de / ru, controlling tool descriptions, parameter help, distillation prompts, tool results, validation errors and Hot Memory / Markdown headings. Tool names, parameter keys and enums stay unchanged. It is independent of the Chinese/English GUI, does not infer language or translate existing memories, and affects subsequent prompts immediately without restarting. Switching alone does not rewrite JSON/Markdown; later writes use the selected language for projection headings.
Hot Memory and session snapshots
- Bounded injection: complete history stays local. Only budgeted actions, lessons and recent state enter the system prompt automatically; the whole Markdown file is never injected.
- Frozen prefixes: new writes are immediately visible to tools and the GUI, while automatic injection refreshes in the next new session. Budget changes do not rewrite existing snapshots. Languages have separate namespaces, switching back reuses the old baseline, and forks/new session ids do not inherit parent snapshots.
- Hard budget handling: skip candidates exceeding the remaining budget in favor of smaller entries. Shorten an oversized first entry's content and, if needed, title against the complete rendered block. Skip it if even the minimum block cannot fit; long titles cannot bypass the hard ceiling.
- Literal text and cache limits: emit
{{...}}and other template literals verbatim for new memories, cached old snapshots and restored disk snapshots, without deleting snapshots or rewriting original memories. Frozen prefixes can help caching but do not guarantee provider KV-cache retention, hit rates or billing savings.
0.9.6 adds Memory to the left global-panel rail, following the main conversation’s workspace. Existing conversation, Settings and right-side views remain available. Native Plugins gains a dedicated icon and bilingual metadata; the information area shows compatible stable updates.
Local recall and caching
- Tokenization: Chinese 2/3-grams, Unicode letters/combining marks/numbers and code/path identifiers. NFC normalization preserves original content, German umlauts and Russian Cyrillic.
- BM25 ranking: retain true term frequency, boost title BM25 scores by 2.5×, and apply exact-phrase, section and recency weights. Title and body lengths are normalized independently.
- Shared retrieval: the GUI and
memoir_readshare the BM25 engine. With a query, the tool takes a global Top-K forscope=global. Forscope=all, it shows the current project first, then merges global results with ID deduplication; the whole call is not guaranteed to be a single global Top-K. Without a query it takes recent entries per project; see Configuration forlimitboundaries. - Query LRU: cache keys include the data epoch, project cwd, section, status, normalized query and a one-hour time bucket, reflecting data updates. Neither
limitnor output detail enters the key, so output variants share rankings. - Diagnostics: expose the index, cache hits / misses / evictions, hit rate and latency of the most recent actual search.
- Limits: retrieval is lexical, without automatic translation, stemming or cross-language semantic matching.
Web / Desktop GUI
- Browsing and governance: project/global memory groups, status/section/keyword filters and BM25 scores; add, edit, pin, archive, restore and supersede entries.
- Provenance: copy session/turn identifiers and make a best-effort jump to the source session, without promising navigation to the exact turn.
- Previews and diagnostics: Hot Memory Inspector previews new-session candidates from current data, rather than an existing session's frozen baseline. Diagnostics cover the index, query cache, snapshots and write outcomes.
- Long lists: batches of 20 entries or projects and expandable six-line body previews. Browse, Settings, Hot Memory and Diagnostics preserve separate scroll positions, with the final item above the composer.
- Accessibility and language: arrow keys, Home/End, project disclosures and visible focus states. GUI language follows the host's Chinese/English setting; the independent
languagesetting controls four agent languages.
The first Memory Conversation opening, or left-side Memory opening in 0.9.6, shows offline release highlights without blocking chat. Acknowledging suppresses automatic display for that version in the same UI storage context; reopen from About & help. Settings and right-sidebar panels do not open it automatically. Without storage, deduplication lasts only for the current page; Web/Desktop acknowledgment need not be shared. Notices make no network requests or memory changes. The separate 0.9.6 version check asks the host for stable versions and compatibility, shares results within the page for 15 minutes, sends no memories or workspace paths, and never installs automatically.
About & help shows the plugin version, host range, SDK baseline and maintainer. Its links belong to the plugin project, rather than the current workspace repository; it does not inspect workspace Git remotes. Update through the host plugin manager after checking the target package's host requirements and prerelease channel.
Local performance reference
These fixed synthetic-corpus measurements were taken on 2026-11-13 with the 0.9.6 release candidate (Windows x64, Node 24.19.0), as a reference for this release, not an independent comparison against 0.9.5:
| Memories | Mean uncached search | Mean cached search | Mean Hot Memory build | Estimated injected tokens |
|---|---|---|---|---|
| 1,000 | 0.880 ms | 1.126 µs | 0.429 ms | 916 |
| 10,000 | 8.143 ms | 1.066 µs | 1.561 ms | 902 |
| 100,000 | 104.255 ms | 0.990 µs | 14.788 ms | 917 |
Cache statistics use actual counters: two requests for each of 20 distinct queries produced a 50% hit rate, determined by that access pattern. This is the local retrieval cache, not a model provider's KV cache. Latencies are loop averages from one run, without P95 measurements; token estimates do not measure billing savings. See the benchmark report for methodology, cold-load and index-build costs.
Configuration
Set these parameters in the memoir config row of your profile composition; see cordis.patch.yml for the mounting example. All except enabled are also live-editable from the memory panel, Settings or native plugin details, and persist in DSH_HOME.
| Parameter | Default | Purpose |
|---|---|---|
enabled |
true |
Master switch for tools, routes and prompt injection |
language |
zh |
Agent language: zh / en / de / ru, independent of the GUI |
announceToAgent |
true |
Inject memory guidance and Hot Memory; tools and GUI remain available when off |
autoDistill |
true |
Enable top-level worked-turn wrap-up reminders |
autoDistillEvery |
1 |
Remind at most once per N eligible worked turns |
autoDistillCooldownMin |
0 |
Minimum minutes between successful reminders |
autoDistillMinTools |
1 |
Minimum tool calls in the triggering turn |
hotMemoryTokens |
900 |
Target Hot Memory token budget for new sessions |
hotMemoryMaxTokens |
1200 |
Hard budget ceiling for newly created session snapshots |
readDefaultLimit |
8 |
Default limit parameter for memoir_read |
readMaxLimit |
30 |
Whole-call result cap starting with 0.9.6 |
sessionSnapshotMax |
128 |
In-memory snapshot LRU capacity; does not delete disk snapshots |
queryCacheSize |
128 |
BM25 query LRU capacity |
0.9.6 caps the whole call at limit memories. all keeps project-first order, fills remaining slots globally and deduplicates; it is not a single cross-project ranking. No-query reads still iterate by project. The older 0.9.5 applies separate branch/project limits and may exceed that count. Both retain the character budget.
Integer parameters are at least 1, with cooldown at least 0; a hard budget/recall maximum cannot be below its target/default. Shrinking caches immediately evicts the oldest entries. Budget changes affect new snapshots only. Restore startup configuration removes persistent overrides and returns to profile startup values without clearing memory.
Data safety and recovery
Files, privacy and backups
DSH_HOME defaults to ~/.dsh; use the actual configured paths when customized.
| File | Contents |
|---|---|
$DSH_HOME/dsh-memoir.json |
Complete structured history, JSON store v4, single source of truth |
$DSH_HOME/dsh-memoir.settings.json |
Persistent GUI setting overrides, settings v3 |
$DSH_HOME/dsh-memoir.json.snapshots/ |
Session snapshots loaded on demand, snapshot v1; <storePath>.snapshots/ when customized |
<project>/PROJECT_MEMORY.md |
Readable JSON projection that you may commit to Git |
- The plugin has no separate cloud memory service and makes no additional memory or workspace-path uploads. Content read through tools or injected into prompts enters the current model's context. You decide whether sensitive Markdown belongs in Git.
- Panel memory writes require a trusted active workspace or existing project bucket; submitting an arbitrary absolute path grants no write access. Cross-process memory-store writes take an exclusive lock and reread disk inside it, with conservative dead-writer lock recovery. Settings files lack cross-process refresh and conflict detection; avoid changing settings from multiple hosts at once. Windows path keys are case-normalized while display paths stay unchanged.
- Future store formats, read errors and failed corrupt-file backups fail closed, refusing further loading/overwriting. A fresh store is allowed only after preserving the damaged original. Temporary Windows rename failures receive bounded retries and still surface when exhausted.
- Before upgrades, back up memory JSON, settings, snapshots and project Markdown. Plugin upgrades or removal do not delete them automatically; 0.9.6 does not migrate their formats. DSH session migration is separate: back up all of DSH_HOME, as older hosts may not read migrated sessions.
Snapshot retention and cleanup
sessionSnapshotMax bounds RAM LRU only. Disk snapshots are partitioned by data-source/settings-file hash, language and session hash. They have no automatic TTL and survive shrinking, uninstalling or clearing RAM. To reclaim space, stop relevant DSH processes, back up, then manually remove records you no longer need to resume. Access after deletion establishes a new baseline.
Old sessions whose snapshots are already lost can only establish a baseline from current memory; the plugin never guesses original text from historical system prompts. Corrupt, inaccessible, locked or oversized records remain unchanged, with a process-local frozen fallback and degraded restart stability reported in diagnostics/logs. Text is capped at 256 KiB and each record at 2 MiB. New POSIX directories/files use 0700/0600; Windows uses directory ACLs. Snapshots contain memory text and are user data.
When an old session will not reopen (#14)
Invalid receipts written by 0.8.1–0.9.0 can prevent reopening; upgrading Memoir or DSH does not repair historical logs automatically. Prevention starts in 0.9.1 and is retained in 0.9.6. Template-literal protection does not repair arbitrary old logs either.
Follow the session recovery guide using the bundled npm dsh-memoir-repair command. Stop writes from the affected old plugin and upgrade to a compatible fixed version first. Audit one explicitly named file read-only; only after every Web/CLI/Desktop/background host exits and an independent backup exists, apply explicitly with --apply --host-stopped. Disabling automatic distillation alone does not stop manual writes.
Only matching official host/backend/SDK versions in the guide's allowlist are accepted, including 0.2.2-rc.1 / rc.2 / rc.3 / rc.5. The tool handles active native session.v4.jsonl[.zstd] files in header-matching directories only, without home scans or generation migration. It rejects superseded v4, mixed versions, path aliases/links, corruption, mixed encodings and zstd frames without checksums. Stored and expanded size are each capped at 128 MiB.
Apply holds the official session lease with hosts stopped throughout: a same-login-session Windows semaphore or POSIX flock on a stable session.lock inode. Use trusted local filesystems, not network drives or cross-login sharing. Only matching legacy receipts gain ignorable: true; events, content and order are preserved. Exact original bytes are backed up to .bak before same-directory atomic replacement, and repeating makes no change. Windows replacement inherits directory ACLs without preserving custom source-file ACLs. Follow the guide for errors, remaining .tmp/.bak, committed: true and rollback; never delete raw logs, downgrade formats or bulk-delete unknown caches.
Older-version compatibility
0.9.6's host/peer range is >=0.2.0-rc.1 <0.3.0-0 || >=0.2.1-alpha.1 <0.2.1 || >=0.2.2-rc.1 <0.2.2. It retains official 0.2.0-rc.1 / rc.2 and 0.2.1-alpha.1 / alpha.2 / rc.2 / rc.3 / rc.4 / rc.5 lines. The range does not verify every included or future build and does not admit 0.2.2-alpha. Runtime compatibility does not imply recovery of arbitrary historical logs.
| Pinned Memoir | DSH range | Notes |
|---|---|---|
0.9.6 |
Range above; development baseline 0.2.2-rc.3 |
Current release; memory/settings/snapshot formats unchanged |
0.9.5 |
Range above; development baseline 0.2.2-rc.1 |
Older release; recovery CLI does not support rc.2 / rc.3 |
0.9.4 |
>=0.2.0-rc.1 <0.3.0-0 || >=0.2.1-alpha.1 <0.2.1 |
Historical SDK baseline 0.2.1-rc.5; no 0.2.2-rc.1 adaptation |
0.8.2 |
>=0.1.7-rc.1 <0.1.8-0 |
Older 0.1.7 line, still affected by #14 |
0.7.1 |
>=0.1.5-rc.1 <0.1.6-0 |
Older 0.1.5 line; fixes snapshots after restart/RAM eviction |
0.6.2 |
>=0.1.2-alpha.2 <0.1.3 |
Older 0.1.2 line |
0.5.6 |
0.1.1-rc.2 |
Older rc.2 line |
Match the plugin version to an older host. Older lines lack all current fixes; back up and upgrade both host and plugin where possible. Select zh or en before downgrading to 0.8.2. The plugin's Node engine remains ^22.19.0 || >=24.0.0 for older hosts; the current development SDK and DSH 0.2.2-rc.3 still require Node >=24.9.0. See the changelog for full compatibility and fix history.
Development and contributing
Development uses official npm DSH SDK 0.2.2-rc.3, Node >=24.9.0 and pnpm. See CONTRIBUTING.md for setup, builds and contribution rules, and cordis.patch.yml for the composition mounting example.
Source and feedback · Issues · Changelog · Releases · Apache-2.0
Links
More in this category
vectorize-io/hindsight#coding-agents★ 62276
Hindsight, agent memory that learns: long-term project memory with auto recall and retain, knowledge pages, deep reflection, and per-repo memory banks.
volcengine/OpenViking#examples/dsh-memory-plugin★ 42543
OpenViking memory and context bundle for DeepSeek Harness: pre-step auto-recall and profile injection, session capture, `viking://` URI guarding, and recall/write memory tools backed by an OpenViking server.
MemTensor/MemOS#memos-local-plugin★ 12467
Local-first memory plugin for DeepSeek Harness: layered L1/L2/L3 memory with automatic capture, manual memos_* retrieval tools, and a built-in memory viewer.
agentscope-ai/ReMe#dsh★ 3827
Connects DeepSeek Harness to ReMe's local-first, self-evolving personal knowledge base: automatically captures completed main-agent conversations as user-owned Markdown memory, searches conversations and source material through reme_search with BM25, optional embeddings, and wikilink expansion, and schedules daily memory consolidation.
zilliztech/memsearch#MemSearch★ 2915
Shared Markdown memory for DSH and other coding agents, with automatic capture, pre-step context injection, searchable recall, and memory-to-skill self-evolution through a review panel.
vshulcz/deja-vu#extensions/dsh★ 1639
Cross-session memory and context recovery across forty-five other coding agents (45+) on this machine, reading session files they already wrote before install (Claude Code, Codex, Cursor, Windsurf, Trae, Antigravity, VS Code Copilot Chat, opencode, OpenClaw, Hermes, Kimi, Qoder, Cline, Zed, Magpie and more): six tools (deja_recall, deja_session, deja_blame, deja_fix, deja_how, deja_remember), a /deja command, and optional automatic recall injected into runtime context. Local BM25 CLI/MCP index, no LLM, no embeddings, no network (dsh plugin --profile web add dsh-deja).
Community comments
Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.