One-Line Positioning

dsh-mnemon introduces a three-layer memory control plane for DeepSeek Harness: runtime USER.md / MEMORY.md automatically injected per turn, full-text searchable project archives, and Memory Spaces that switch between 9 long-term memory Providers—the long-term memory backend doesn't need to be bound to Mnemon.

Core Capabilities

• Automatically inject minimalist Runtime memory per turn (USER.md for user preferences, MEMORY.md for project conventions), with an independent task Agent compressing and archiving when capacity is full
• Provide full-text searchable Project Documents that preserve complete long-form content such as designs, investigations, post-mortems, and handovers, created/updated/archived through dedicated tools
• Expose unified Memory Space interface for 9 long-term memory Providers (Mnemon Native, OpenViking, Honcho, Mem0, Hindsight, Holographic, RetainDB, ByteRover, Supermemory), displaying capabilities based on each Provider's actual features
• Register 12 semantic tools for Agents (mnemon_recall / mnemon_remember / mnemon_runtime_memory / mnemon_document_search / mnemon_document_manage / mnemon_link / mnemon_forget / mnemon_memory_body_create-update-merge / mnemon_status / mnemon_related / mnemon_memory_bodies), and provide /mnemon status|recall|related|remember|forget commands
• Provide four top-level pages in Sidebar / Buildin workspace: Status, Runtime, Documents, and Memory Spaces, with Turn memory and Save to memory entry points in conversation
• Support three storage scopes: global / workspace / custom, with adjustable switches for ZIP backup/restore, Provider enable/disable, remote access permission levels, and Recall quality policies

Technical Implementation

• Language: TypeScript (ESM + strict types, bundled with tsdown)
• Key Dependencies: schemastery (config schema validation), @deepseek-ai/dsh-client-runtime + dsh-client-ui-conversation + dsh-client-ui-settings + dsh-client-ui-primitives (DSH Host/Client access), markdown-to-jsx + fflate (Markdown rendering and package compression)
• Architecture Pattern: Injects five facets via Cordis plugin protocol: tools / settings / commands / agents / subagents; host loads runtime graph via apply(ctx, config); all Mnemon CLI calls go through runner.ts's spawn(command, args, { shell: false }) with process queuing; long-term memory writes supervised by MnemonSubagentCoordinator spawning independent task Agents
• Entry Point: src/index.ts (exports apply entry and name = 'dsh-mnemon'), Cordis injection config in cordis.patch.yml

Applicable Scenarios

When users want DSH Agents to remember preferences, project conventions, post-mortem conclusions, and long-term facts across sessions, this plugin enables Agents to automatically restore context in new sessions, retrieve historical project archives, and recall evidence from external memory services on demand. It's suitable for research/engineering Agents requiring long-term collaboration, team workflows needing cross-project memory sharing, and migration scenarios where the memory backend is moved from single SQLite to external services like Mem0 / OpenViking.

Prerequisites and Compatibility

Installation

dsh plugin --profile web add github:omdsh-dev/dsh-mnemon

Configuration Options

Frequently Asked Questions

Q: After installation, the plugin shows unavailable. How do I troubleshoot?

A: First check if mnemon CLI is executable in PATH (run command -v mnemon on macOS/Linux, Get-Command mnemon in PowerShell on Windows), and confirm mnemon --version is at least 0.2.3. If the CLI is in a non-standard location, fill in mnemon.cliPath in user settings or export MNEMON_CLI_PATH environment variable before restarting Host.

Q: Can I switch from "all Agents share" to "only use in current project"? Will data be moved?

A: Yes, but the plugin won't automatically migrate. storageScope of global / workspace / custom is a one-time root selection—switching only makes the new location effective. Runtime, Documents, and Memory Spaces under the old root remain unchanged. It's recommended to do a ZIP backup in the original scope before switching, then import and verify after saving to the new scope.

Q: Can I store all memories in third-party services like Mem0 / OpenViking / Holographic?

A: Yes. Third-party Providers are disabled by default; after enabling, configure endpoint, API key, etc., in the Provider service config page to register one or more Memory Spaces. Mnemon Native (local SQLite) as the default backend can coexist with third-party Memory Spaces. Switching DSH workspaces won't automatically rewrite third-party service namespaces like URI, workspace, user, project, container.

Q: What's the AI's permission boundary for writing memory? Will it automatically delete remote data?

A: No remote data is deleted. All changes are first validated for legality and path on the Host side; persistent Provider writes are supervised by independent task Agents via MnemonSubagentCoordinator, and the "Save to memory" dialog before execution allows cancellation. Provider shutdown only cleans up local directory mappings, activation state, and local metadata (title, description)—it doesn't unsubscribe or delete actual remote service data.

Q: Will uninstalling the plugin clear my memory database?

A: No. Uninstalling only unregisters the plugin. Runtime, Documents, Mnemon Native database, and state/ config stored under ~/.mnemon / <workspace>/.mnemon / custom dataDir are all preserved. After reinstalling, the plugin will rediscover this data. If you want to completely clean up, you can manually delete the corresponding directories.

Q: What are "Turn memory" and "Save to memory" in the Web UI?

A: "Turn memory" displays which memory tools the Agent used this turn (recall, write, document search, etc.), each linking to the corresponding Memory Space or Document page; "Save to memory" opens the current assistant reply as a draft in an editable confirmation dialog, and only starts the supervised write flow after user confirmation—canceling produces no changes.

Q: Can the model used by sub-Agents / task Agents be changed? Will it conflict with my conversation model?

A: No conflict. After selecting "fixed" in mnemon.taskAgentModel and filling in Provider/Model, independent task Agents for AI meta-info, archiving, Agent queries, memory distillation, etc., all use that routing; the default inherit mode follows DSH's default Provider/Model fallback when "new session" is created. Neither mode affects the main conversation Agent's model selection.

Learning Curve

Advanced — the plugin works out of the box, but introduces three layers of Runtime/Archive/Long-term memory with 9 Providers, plus 12 Agent tools and 6 sets of Slash commands; ordinary users can complete their first Recall in 5 minutes, but to leverage advanced capabilities like layered routing, Recall quality policies, and background review, understanding the three concepts "Memory Body / runtime store / Documents" and storageScope boundaries is required.

Known Issues and Limitations

• No deterministic secret scanner: Do not write API keys, tokens, private keys, or raw sensitive logs into any memory layer; both documents and status page clearly提示这一点
• Background scoring review's activity score, latest checkpoint, and retry state are not currently persistent: Host restart clears unprocessed activities, and failure fallback, circuit breaker, and manual retry are not yet implemented
• Switching storageScope does not automatically migrate, merge, or delete data from the old scope: migration can only go through "old scope export ZIP → switch save → new scope import" path
• Documents under global / custom may be shared across multiple workspaces, but records don't carry independent workspace affiliation fields; sourcePaths are only validated relative to current cwd at write time
• writeEnabled: false is functional read-only, not disk-level read-only: Runtime projection initialization, document last-access time updates, and Mnemon read-triggered database migration may still occur at startup
• Cold recall archive writes are not cross-Mnemon SQLite and file system rollback-able distributed transactions: if version conflicts exist after archiving, duplicate cold references may occur, but the plugin preserves original data rather than auto-overwriting
• No formal DSH / Mnemon support matrix: main Web UI is bilingual, but commands, tool cards, compatibility metadata, and some error prompts still have untranslated entries
• Strictly expose based on Provider-declared capabilities when handling Provider capability differences: for example, OpenViking writes are async distillation and may skip candidates; Honcho/Mem0/RetainDB don't provide graph/related/link; ByteRover doesn't support forget; shutting down external Providers doesn't delete remote data

dsh-mnemon

English · 简体中文

The three-tier, pluggable, Agent-driven memory system for DeepSeek Harness.

Three memory tiers · Nine long-term providers · One supervised workflow

Explore the capability map · Start in five minutes · Read the v0.2.9 notes · Watch the widescreen demo

dsh-mnemon gives DSH one memory control plane without forcing every kind of knowledge into one database. Runtime Memory keeps compact context available every turn. Project Documents preserve complete narratives. Memory Spaces retrieve durable evidence on demand and can use Mnemon, OpenViking, Honcho, Mem0, Hindsight, Holographic, RetainDB, ByteRover, or Supermemory.

Mnemon remains the official, prioritized native engine. The third tier is replaceable; the first two keep the same storage, workspace, and interaction model regardless of provider.

Understand the scope in 30 seconds

The tiers are not copies. A useful rule is: every-turn context goes to Runtime, complete narratives go to Documents, and cross-task evidence goes to Memory Spaces. Current instructions, repository files, and live tool results always outrank historical memory.

Clicks that start real work

These tasks do not reuse or consume the main conversation history. By default they follow DSH's new-session model route; Settings → Memory System → Background task Agent can select a dedicated Provider and model.

One Memory Space workflow, nine providers

Provider capability differences stay visible. dsh-mnemon never invents graph edges, deletion semantics, or enumerable content for an engine that does not provide them. Settings owns reusable Provider services; Memory Spaces owns concrete instances, activation, scope, and metadata. External Providers are off by default.

See the provider capability and deployment matrix.

Real WebUI walkthrough

The following roughly 55-second capture comes from a live 1600×900 DSH WebUI. It deliberately pauses on full-page scrolling, page transitions, Provider cards, dialogs, button-state changes, and a completed read-only Agent Query. Destructive confirmations are deliberately not submitted.

Watch the 1600×900 MP4 · Open the page-by-page UI guide

Start in five minutes

1. Install Mnemon Native

Mnemon is the default engine and the simplest local-first starting point:

# macOS
brew install --cask mnemon-dev/tap/mnemon

# macOS / Linux via Go
go install github.com/mnemon-dev/mnemon@latest

mnemon --version

Windows users can install the official v0.2.3-or-newer release ZIP. The expected installation path and checksum procedure are in Getting Started.

2. Install the DSH plugin

dsh plugin --profile web add dsh-mnemon
dsh --profile web

DSH profiles have independent plugin rosters. Install the same package separately for one-shot Headless tasks:

dsh plugin --profile headless add dsh-mnemon
dsh --profile headless "Check durable project context before answering this task."

For a local checkout, use an absolute path:

dsh plugin --profile web add "link:/absolute/path/to/dsh-mnemon"
dsh plugin --profile headless add "link:/absolute/path/to/dsh-mnemon"

3. Verify the first workflow

1. Open Memory System → Status and verify dsh-mnemon, Mnemon Native, Runtime, Documents, and enabled Providers.
2. Open Memory Spaces → Overview → Create Memory Space and choose an enabled Provider explicitly.
3. Submit one stable, future-useful candidate through Remember.
4. Open Recall, run a direct search, then run Agent query against the same question.
5. Return to the conversation, expand Turn memory, and follow one exact tool link.

The primary tab order is intentionally stable: Status, Runtime, Documents, Memory Spaces.

Familiar controls, expanded capability

Agent-driven memory operations

The workbench makes the task boundary explicit before dispatch and keeps the returned answer beside its evidence scope. Conversation-native Turn memory and Save to memory remain enabled by default and can be changed independently under Settings → Memory System → Conversation interface.

Manual or policy-driven placement

Manual creation always asks the user to choose. Smart selection is a distillation policy: hard rules define the eligible set, then an optional prompt guides the Agent only when several candidates remain.

Global, workspace, and custom scope

Remote Provider workspaces, users, banks, projects, containers, and URIs remain their own namespaces; switching the DSH workspace never silently rewrites them. In workspace mode, the workbench may inspect one selected workspace while the current conversation continues to execute in its own cwd. Independent task Agents launched from the workbench use the inspected workspace even when no main session is selected.

Web, conversation, and Headless share one system

Data and security boundaries

• Runtime and Documents are local deterministic stores. Mnemon Native is local by default; external Providers are explicit opt-ins.
• Provider credentials are mode 0600 under <storageRoot>/state/memory-providers.json. They are never returned to the browser, smart-selection Agent, or Mnemon Pack.
• Host calls use argument arrays with shell disabled, bounded output, timeouts, cancellation, schema validation, path boundaries, locks, and revisions.
• Disabling a Provider clears its local catalog metadata but never deletes remote data. Reconnecting rebuilds metadata from the Provider, using local defaults only when a field cannot be mapped.
• Changing scope never migrates, merges, or deletes an old root automatically.
• There is no deterministic secret scanner yet. Never store keys, tokens, private keys, or raw sensitive logs in any tier.
• Uninstalling the plugin does not remove local or remote memory data.

See Operations, security, and troubleshooting for backup, recovery, and diagnostics.

Documentation

See the documentation hub for the full map.

Development

pnpm install
pnpm run verify

verify runs TypeScript checks, Vitest, a reproducible double build, an isolated real Headless-profile activation check, and published-package validation. lib/ is generated and intentionally not tracked.

License

MIT. Report security issues privately through SECURITY.md, not a public issue.