dsh-workspace-memory

Durable, approval-gated workspace instructions and project memory for DeepSeek Harness.

English | 简体中文

dsh-workspace-memory lets conversations opened in the same workspace share two kinds of durable context:

File	What belongs there
AGENTS.md	Reusable instructions for how agents should work, write, format, validate, and use tools
.dsh-memory.md	Stable project facts, decisions, terminology, constraints, and unresolved risks

Both are ordinary Markdown files in the workspace root. They remain readable, reviewable, and versionable without a database, embeddings, or a cloud service.

See it in one minute

The demo follows the complete workflow: save a reusable working rule to AGENTS.md, record a stable project decision in .dsh-memory.md, then open another conversation in the same workspace and verify that it receives both. Every inferred update is shown as a focused diff and written only after approval.

Try the same flow after installing:

1. Workspace instruction: “Whenever you change files here, finish by summarizing what changed and what you verified. Apply this rule to future conversations too.”
2. Project memory: “This project prioritizes backward compatibility over adopting new APIs. Preserve this decision for future conversations.”
3. New conversation: “What instructions should you follow here, and what project decisions should you keep in mind?”

Rules the agent should repeatedly follow belong in AGENTS.md; stable facts and decisions it should remember belong in .dsh-memory.md. One-off requests are not stored.

Install

Requires DeepSeek Harness 0.1.1-rc.2 and Node.js ^22.19.0 || >=24.0.0.

dsh plugin --profile web add dsh-workspace-memory
dsh --profile web

That is all. This package declares dsh.bundle, so DSH adds its configuration layer to the web profile automatically. No profile file needs to be edited by hand. Restart an already running profile after installing or updating the package.

# Update
dsh plugin --profile web update dsh-workspace-memory@latest

# Remove
dsh plugin --profile web remove dsh-workspace-memory

Why use it?

• Cross-session context — a new conversation sees the same workspace rules and decisions as existing conversations.
• Instructions and knowledge stay separate — behavioral rules go to AGENTS.md; project knowledge goes to .dsh-memory.md.
• No silent inferred writes — when the model identifies durable feedback, it shows a focused diff and asks before writing.
• Purpose-built Web review — DSH Web shows line numbers, colored additions and removals, and collapsed unchanged sections; other clients retain a Markdown fallback.
• Fresh on every step — both files are reread before each accepted model step, so existing conversations observe later edits.
• Conflict-aware — a proposal based on an older file version cannot overwrite a newer edit from another conversation.
• Sandbox-aware — writes use the calling session's workspace policy and cwd, not the directory where the DSH server was started.
• Local and inspectable — no network requests, telemetry, database, or hidden memory store.

How it works

durable user feedback
        |
        +-- reusable agent behavior ----------> AGENTS.md
        |
        +-- stable project knowledge ----------> .dsh-memory.md
        |
        `-- one-off request or progress --------> not stored

candidate -> complete-file merge -> user confirmation -> version-guarded write

Before every accepted model step, the plugin injects one current snapshot of the two files. Unchanged visible content is not appended repeatedly; empty and deleted files are represented explicitly so stale content is superseded.

The model decides whether feedback appears durable and which file it belongs in. Before proposing, it is instructed to review the complete Markdown document, integrate the smallest coherent edit into the relevant section, remove affected-section duplication, and preserve unrelated content and structure. The workspace_memory tool enforces the write boundary: inferred feedback must use propose, and a proposal is written only after the user approves it. The observed file version must still match at write time.

The npm Bundle contains both plugin halves. The Host half keeps the complete proposed replacement and performs the guarded write. The optional Web half receives only a bounded structured diff and renders the review card through DSH's client module system, so installing the Bundle does not require rebuilding the DSH Web application.

This mechanism improves continuity; it does not guarantee that a model will always classify, remember, or follow every instruction correctly.

Defaults and configuration

The Bundle installs this configuration:

memoryFile: .dsh-memory.md
instructionFile: AGENTS.md
suggestUpdates: true
maxBytes: 32768

To override it, add a later row to $DSH_HOME/profiles/web/cordis.patch.yml. DSH replaces the complete config value, so restate every field:

- id: workspace-memory
  config:
    memoryFile: .dsh-memory.md
    instructionFile: AGENTS.md
    suggestUpdates: false
    maxBytes: 65536

The filenames must be distinct, same-directory names without path separators. maxBytes applies separately to each complete file and to the proposal rationale. Existing files must be regular UTF-8 files; symbolic links at the final path component are rejected.

Safety model

Boundary	Behavior
Storage scope	Only the two configured files in the exact session cwd
Model-inferred changes	Require interactive confirmation
Concurrent changes	Stale whole-file replacements are rejected
Sandbox boundary	The calling session's policy and cwd are enforced; read-only remains read-only
Failed or declined proposal	The agent is instructed not to bypass workspace_memory with another write tool
Symbolic links	Rejected at the final path component
Network and telemetry	None
Database and embeddings	None

See SECURITY.md for the complete authority and write-safety model.

Compatibility and limitations

Environment	Status
DSH Web 0.1.1-rc.2	Tested
Windows x64	Tested
Ubuntu with Node.js 22 and 24	CI target
macOS	Not yet verified
Headless profile	Use suggestUpdates: false; an interactive confirmation provider is normally unavailable

• Workspace identity is the session's exact cwd. Parent directories and sibling or child directories do not automatically share a memory file.
• This plugin synchronizes only the cwd-level AGENTS.md. Global, ancestor, and nested instruction discovery remains the responsibility of DSH's standard agent-instructions plugin.
• Classification is model-based and can miss or misclassify feedback. Confirmation prevents silent inferred writes; it does not guarantee perfect classification or instruction compliance.
• Whole-file replacement is intentional. The caller merges complete content, while the plugin rejects stale writes instead of attempting an unsafe automatic merge.

Troubleshooting

The Bundle does not appear in the profile

dsh --profile web --dump-config

Look for a # == dsh-workspace-memory layer and an entry with id: workspace-memory. If both are present, restart the profile.

No update question appears

Check that suggestUpdates is true and that the feedback is durable rather than a one-off task. For a deterministic test, explicitly say that the rule or decision should apply to future conversations.

A confirmed write fails

Another conversation may have changed the file while the confirmation dialog was open. Read the current content, merge the candidate again, and submit a new proposal.

Development

pnpm install
pnpm run verify
pnpm pack

Install a local checkout into DSH:

pnpm run build
dsh plugin --profile web add "link:/absolute/path/to/dsh-workspace-memory"
dsh --profile web

Release history is maintained in CHANGELOG.md. Contributions and reproducible bug reports are welcome.