# dsh-mnemon

> Integrates a three

## Metadata

- Author: [@omdsh-dev](https://github.com/omdsh-dev)
- Repo: <https://github.com/omdsh-dev/dsh-mnemon.git>
- GitHub: [omdsh-dev/dsh-mnemon](https://github.com/omdsh-dev/dsh-mnemon)
- Stars: 140
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Homepage: <https://github.com/omdsh-dev/dsh-mnemon#readme>
- Topics: `agent-memory`, `context-management`, `cross-session-memory`, `deepseek-harness`, `document-search`, `dsh-plugin`, `llm-memory`, `local-first`, `long-term-memory`, `memory-orchestration`, `memory-provider`, `multi-agent-memory`, `persistent-memory`, `pluggable-memory`, `project-documents`, `project-memory`, `runtime-memory`, `semantic-recall`, `shared-agent-memory`, `working-memory`
- Forks: 8
- Open Issues: 2
- Last push: 2026-08-20T21:44:58.000Z
- Added: 2026-08-13T00:00:00.000Z

## Install

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

## Wiki

## 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

| Dependency | Min Version | Description |
|---|---|---|
| DSH Host | 0.1.0-rc.6 | `peerDependencies` locked; Host APIs before rc.6 are incompatible |
| Node.js | >= 20 | Declared in `package.json#engines.node` |
| Platform | Cross-platform | Supported on macOS / Windows / Linux; Windows auto-discovers `mnemon.exe`; third-party Providers use HTTP or local CLI |
| External CLI | mnemon >= 0.2.3 | Recommended as default long-term memory engine; missing causes all semantic read/write to fail |
| provider named `spawn` | Required | Supervised task Agents need `toolFilter / persona / depthLimit`; missing makes semantic tasks unavailable |
| provider named `fork` | Optional | Enables background scoring review when `inheritsParentContext=true`; missing only affects background review, UI and manual flows still work |

## Installation

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

## Configuration Options

| Config | Type | Description | Default |
|---|---|---|---|
| `displayMode` | `sidebar` / `buildin` | Whether workspace attaches to Sidebar or returns to conversation tab | `sidebar` |
| `storageScope` | `global` / `workspace` / `custom` | Unified storage root for Runtime / Documents / Memory Spaces | `global` |
| `dataDir` | Absolute path or `~` / `~/...` | Required persistent directory when `storageScope: custom` | unset |
| `cliPath` | Executable path | Explicitly specify `mnemon` executable location; if empty, auto-discover via `MNEMON_CLI_PATH` → `PATH` → common directories | unset |
| `store` | `[A-Za-z0-9][A-Za-z0-9_-]*` | Legacy Store compatibility discovery hint, no longer used for runtime routing | unset |
| `timeoutMs` | 100–120000 | Hard timeout for single Mnemon CLI call (ms) | `10000` |
| `defaultRecallLimit` | 1–50 | Default recall count; shared by UI and `/mnemon recall` command | `10` |
| `recallQuality.policy` | Registered policy id | Deterministic filtering strategy for recall results before entering Agent | `strict-v1` |
| `recallQuality.lowScoreThreshold` | 0–1 | Below this score, normalized relevance is discarded in strict policy | `0.25` |
| `recallQuality.highScoreThreshold` | 0–1 | Above this score marked as high relevance, must be `> lowScoreThreshold` | `0.6` |
| `recallQuality.candidateMultiplier` | 1–5 | Expansion multiplier before recall (cap 50 candidates) | `3` |
| `recallQuality.maxMediumResults` | 0–50 | Cap on medium relevance results allowed in strict policy | `4` |
| `recallQuality.maxUnknownResults` | 0–50 | Cap on unknown-scale results allowed in strict policy | `2` |
| `routingGuidance` | boolean | Whether to register additional layered routing system prompts | `true` |
| `lifecycleEnabled` boolean | Whether to enable pre-step prompts and idle scoring review | `true` |
| `recallMode` | `guided` / `off` | Whether to inject "on-demand recall" prompts; explicit `mnemon_recall` unaffected | `guided` |
| `writebackMode` | `guided` / `off` | Whether to inject hot memory prompts and enable idle scoring review; explicit writes still work | `guided` |
| `idleReviewMs` | 5000–600000 | Continuous idle duration required to trigger background scoring review | `30000` |
| `tabEnabled` | boolean | Whether to mount the Web entry for selected `displayMode`; after disabling, Host RPC, commands, and Agent tools still registered | `true` |
| `writeEnabled` | boolean | Whether to expose semantic write tools, write RPC, `/mnemon remember|forget` | `true` |
| `taskAgentModel.mode` | `inherit` / `fixed` | Model routing for independent task Agents: AI meta-info, Agent queries, memory distillation, archiving | `inherit` |
| `taskAgentModel.provider` | string | Required in `fixed` mode for Provider ID | unset |
| `taskAgentModel.model` | string | Required in `fixed` mode for model ID | unset |
| `remoteAccess` | `read-only` / `trusted-host` | Whether remote Web pages can call privileged Mnemon RPC; locked at startup, requires Host restart | `read-only` |
| `mnemon-ui.turnBar` | boolean | Turn memory activity bar at conversation end | `true` |
| `mnemon-ui.saveAction` | boolean | "Save to memory" icon and confirmation below assistant reply | `true` |
| `persistenceStrategy` | object | Hard rules + soft preferences for selecting Memory Space Provider during supervised writes | `manual` + only `mnemon-native` |
| `customPackId` / `customPacks` | string / array | Explicitly specify multiple custom data directories (max 32), can be viewed as multi-package registry for "custom scope" | unset |

## 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

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-mnemon](https://deepseek-plugin.org/plugins/omdsh-dev/dsh-mnemon)
Wiki generated by AI (model: `MiniMax-M2.5`)