dsh-memory

Codex-like persistent memory for DeepSeek Harness. The plugin gives every session a durable, auto-injected memory: a distilled global summary is injected into each prompt, agents can read/write/search memories with dedicated tools, and each finished turn is automatically distilled into per-session rollout summaries that periodically re-consolidate the global memory file.

How it works

$DSH_HOME/memories/
├── memory_summary.md           distilled, versioned, bounded memory — injected into every prompt
├── raw_memories.md             append-only dated entries written by the memory tools
├── rollout_summaries/<sid>.md  per-session turn summaries (auto)
├── journal.jsonl               mutation journal consumed by consolidation
├── summary_history/<v>.<ts>.md previous summary versions kept for rollback
├── archive/raw-YYYY-MM.md      oldest raw entries archived past the byte budget
├── scopes/ws-<hash>/...         per-workspace stores (when scopedMemory is enabled)
├── scopes/project-<hash>/...    per-git-root project stores (when scopedMemory is enabled)
└── state.json                  version + journal/rollout cursor bookkeeping

• Injection — systemPrompt.context re-reads memory_summary.md at every prompt assembly, so a memory_add call surfaces in the very next model step.
• Tools — memory_read, memory_add, memory_update, memory_delete, memory_search, memory_review, memory_merge, memory_export, memory_import, memory_stats, memory_browse, memory_history, memory_rollback, memory_sync (see below).
• Auto memory — on each finished turn of a root agent, the new conversation text is distilled with the default model into a rollout summary. Every consolidateEvery summaries, the scope's summary is re-merged (atomic write, version bump). With scopedMemory, rollouts and consolidation route to the session's workspace or project scope. All LLM work is queued, timed out, and never blocks a turn.
• Seeding — on first run the plugin seeds the summary from $DSH_HOME/AGENTS.md (the Codex-synced global memory) without modifying it.

Current release: 0.2.4 — see CHANGELOG.md for the release history.

Install

The one-command path is scripts/sync-install.ps1 (see Deploy / update); the manual path is below. Either way, restart DeepSeek Harness afterwards.

1. Put the package under the profile's external plugins:

   Copy-Item -Recurse E:\git\github\dsh-Plugin "$env:USERPROFILE\.dsh\profiles\web\node_modules\@dsh-external\dsh-memory"

2. Add a loader row to ~/.dsh/profiles/web/cordis.patch.yml (must be an insert entry — a standalone - id: row only overrides existing bundle entries and will not mount the plugin):

   - insert:
       - id: dsh-memory
         name: '@dsh-external/dsh-memory'
         config:
           maxBytes: 8000
           autoSummarize: true

3. Restart DeepSeek Harness. The plugin mounts as dsh-memory; its settings namespace is memory.

Configuration

The Web settings card (see below) edits maxBytes, consolidateEvery, autoSummarize, and seedFromAgentsMd live; all other keys are configured through the loader row or the memory: section of settings.yaml.

Tools

Standalone MCP server

bin/dsh-memory-mcp.mjs exposes the same Markdown memory store over stdio JSON-RPC (MCP) with no DeepSeek Harness runtime dependency. Environment: DSH_MEMORY_DIR (default ~/.dsh/memories), DSH_MEMORY_REDACT=1 (default). Scope arguments: global (default), workspace/project with a cwd argument.

It serves 9 tools with the same store semantics as the DSH tools: memory_read, memory_add, memory_update, memory_delete, memory_search, memory_stats, memory_history, memory_merge, memory_review. An example client config lives in examples/mcp-config.json.

Deploy / update

scripts/sync-install.ps1 copies runtime files into a DSH profile external-plugin directory and verifies SHA-256 hashes. It never touches memory data and does not restart DSH; restart is required after sync. Usage:

powershell -ExecutionPolicy Bypass -File scripts/sync-install.ps1 -DryRun
powershell -ExecutionPolicy Bypass -File scripts/sync-install.ps1 -Backup

Scripts

Web settings page

The plugin ships a Web client bundle that registers a "Memory (dsh-memory)" card on the plugin configuration page (Settings → Plugins → Plugin config) automatically — no extra step is required beyond the deploy sync. The card edits maxBytes, consolidateEvery, autoSummarize, and seedFromAgentsMd through the plugin's own same-origin endpoint (/_dsh/memory/settings, registered by the host half). The card copy is localized (English/Chinese) and follows DSH's language setting.

Optionally, the memory namespace can also be exposed to the generic Web settings API (whose allowlist lives in the dsh-host-apiproxy package, one level above plugins):

powershell -ExecutionPolicy Bypass -File scripts/patch-web-settings.ps1 -WhatIf
powershell -ExecutionPolicy Bypass -File scripts/patch-web-settings.ps1

The patch is idempotent, backs up the target, and re-checks syntax. scripts/verify-after-restart.ps1 checks the deployed plugin files, the client bundle, and this allowlist. The card was verified end-to-end on this deployment (2026-08-15): edit → save → "Settings saved and applied." → the memory: section persisted in settings.yaml (changes apply live).

Automatic memory & the auto-memory skill

Two complementary layers keep memory current without manual tool calls:

1. Host pipeline (automatic) — every finished turn of a root agent is distilled into a rollout summary (debounced via summarizeDebounceMs), and summaries are periodically re-consolidated into the injected global summary. The summarization model resolves through summarizeProvider/summarizeModel, then the selected agent model, then the agent-default-model settings namespace. memory_stats reports summarizeSkipCounts / lastSummarizeSkip so skipped distillations are observable. Since 0.2.3 the distillation reads both user/message and assistant/message text (assistant replies were previously dropped), user settings apply at boot (not only after the first live edit), and the internal distill/consolidate LLM calls run with reasoning off so they cannot hit the output-token cap. End-to-end verified 2026-08-16: turn → rollout file → consolidation bumped the global summary v1 → v2.
2. auto-memory skill (agent-driven) — the plugin registers a runtime skill that instructs agents to proactively recognize key facts (preferences, decisions, conventions, fixes, facts), write them with memory_add (tags + dedup), query memory with memory_search / memory_read when a task depends on history, and correct stale entries. The skill appears in every session's skill catalog after restart.

Scope

Memory is stored in three scopes:

• global — shared by all sessions (the Codex-style default);
• workspace — per working directory (ws-<hash>), active when scopedMemory: true;
• project — per nearest git root (project-<hash>), active when scopedMemory: true.

Tools accept a scope argument (global | workspace | project); the project scope resolves the session's cwd. Write access can be restricted per scope via readOnlyScopes.

Development & testing

npm test runs 59 tests (node:test):

• test/store.test.js — store semantics, journal, history, archiving, scopes;
• test/automation.test.js — the auto-memory skill definition, the model-route fallback chain, and extractMessageText (user/assistant event shapes);
• test/browser.test.js — the interactive HTML browser snapshot rendering;
• test/web-settings.test.js — the settings endpoint lifecycle (GET/POST, 403/409, body limits) plus a VM-sandbox load of the client bundle asserting the settings.plugin.item card registration;
• test/embedding.integration.test.js — fake /embeddings server + local hashed vectors;
• test/mcp.integration.test.js — real MCP child-process round-trips.

The architecture and mechanism notes live in docs/DESIGN.md; deployment status in docs/STATUS.md.

License

MIT