Skip to content

getting-started.md

Latest commit

 

History

History
232 lines (156 loc) · 12.4 KB

getting-started.md

File metadata and controls

232 lines (156 loc) · 12.4 KB
Raw

Getting Started

简体中文 | English | Documentation hub

This guide goes from a blank environment to the first verified recall. It uses Sidebar, global storage, and the default default-three-tier composition. You do not need to configure View, Strategy, or generation concepts for normal use.

If installation is complete, jump to First verification. When upgrading from v0.3.x or v0.4.0–v0.4.1, read the v0.4.2 entry-placement compatibility notes, including automatic normalization of retained buildin preferences. If you are upgrading from v0.2.x, also read the v0.3.0 upgrade notes.

1. Prerequisites

You need:

  • Node.js ^22.19.0 || >=24.0.0 for the DSH 0.1.2-rc.1 baseline;
  • a DSH Web or Headless profile that starts successfully;
  • a locally executable mnemon CLI;
  • a DSH model route capable of creating independent task Agents.

Regular semantic work prefers a provider named spawn with toolFilter, persona, and depthLimit. Mnemon supplies a schema-validated, one-run result tool instead of depending on the Provider's outputSchema path. Optional score-based background review additionally requires a provider named fork with inheritsParentContext=true. Missing fork does not block deterministic pages or regular manual actions.

The current stable release is the composable v0.5.1 distribution: one Starter and sixteen version-locked official plugins. Read the v0.5.1 patch and upgrade notes. The pinned DSH baseline is 0.1.2-rc.1; Native integration is also tested with Mnemon 0.2.5. Some retained screenshots come from dsh-mnemon v0.2.0. The complete DSH rc.1 profile requires Node ^22.19.0 || >=24.0.0, while the Mnemon package retains its Node 20 public-entry compatibility for older compatible Hosts. Back up and repeat verification against an isolated root before upgrading.

Install and verify the tested DSH release with:

npm install -g @deepseek-ai/dsh@0.1.2-rc.1
dsh --version
npm view @deepseek-ai/dsh dist-tags

2. Install Mnemon

Homebrew Cask is recommended on macOS:

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

Go works on macOS and Linux:

go install github.com/mnemon-dev/mnemon@latest

Verify the binary:

mnemon --version

On Windows, the official release provides ZIP archives for AMD64 and ARM64. The following PowerShell installs v0.2.3 under the auto-discovered per-user Programs directory and verifies it against the published checksum:

$version = '0.2.3'
$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture -eq 'Arm64') { 'arm64' } else { 'amd64' }
$archiveName = "mnemon_${version}_windows_${arch}.zip"
$releaseBase = "https://github.com/mnemon-dev/mnemon/releases/download/v${version}"
$archive = Join-Path $env:TEMP $archiveName
$checksumFile = Join-Path $env:TEMP "mnemon_${version}_checksums.txt"
Invoke-WebRequest "${releaseBase}/${archiveName}" -OutFile $archive
Invoke-WebRequest "${releaseBase}/checksums.txt" -OutFile $checksumFile
$line = Get-Content $checksumFile | Where-Object { $_.EndsWith("  $archiveName") } | Select-Object -First 1
if (-not $line) { throw "Checksum entry not found for $archiveName" }
$expected = (($line -split '\s+')[0]).ToLowerInvariant()
$actual = (Get-FileHash -Path $archive -Algorithm SHA256).Hash.ToLowerInvariant()
if ($actual -ne $expected) { throw "Checksum mismatch for $archiveName" }
$installDir = Join-Path $env:LOCALAPPDATA 'Programs\mnemon'
New-Item -ItemType Directory -Force -Path $installDir | Out-Null
Expand-Archive -Path $archive -DestinationPath $installDir -Force
$mnemon = Join-Path $installDir 'mnemon.exe'
& $mnemon --version

Go remains an alternative when a Go toolchain is already available:

go install github.com/mnemon-dev/mnemon@latest
$mnemonBin = go env GOBIN
if (-not $mnemonBin) {
  $mnemonBin = Join-Path (((go env GOPATH) -split ';')[0]) 'bin'
}
$mnemon = Join-Path $mnemonBin 'mnemon.exe'
& $mnemon --version

On Windows, dsh-mnemon discovers native mnemon.exe from PATH, an exported GOBIN or GOPATH, the default %USERPROFILE%\go\bin, %LOCALAPPDATA%\Programs\mnemon, and Program Files. .cmd and .bat wrappers are not accepted because CLI calls deliberately run without a shell.

If DSH still cannot find the binary, set MNEMON_CLI_PATH or add an absolute path to the user settings file instead of replacing the plugin's profile patch:

mnemon:
  cliPath: 'C:\Users\alice\AppData\Local\Programs\mnemon\mnemon.exe'

mnemon status opens the effective Store and may initialize data or run upstream migrations, so it is not a side-effect-free installation probe.

3. Install dsh-mnemon

Install into the Web profile for the complete workbench:

dsh plugin --profile web add dsh-mnemon

Use an absolute path for a development checkout:

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

Then start or restart the profile:

dsh --profile web

If the Web profile is reached through a cloud hostname, do not publish port 3080 directly. Stable DSH 0.1.2-rc.1 authenticates every Mnemon RPC and stream through a browser session established from the one-time URL printed at Host startup. Configure the HTTPS reverse proxy or access gateway and trusted authority together, then open that launch URL, by following Cloud-hosted WebUI. The same section preserves the different remoteAccess procedure required when rolling back to DSH 0.1.1-rc.2.

Upgrade and uninstall:

dsh plugin --profile web update dsh-mnemon
dsh plugin --profile web remove dsh-mnemon

Uninstall removes the plugin registration, not memory data in global, workspace, or custom roots.

Profiles have independent plugin rosters. Install the package separately into Headless when one-shot tasks also need memory:

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

For a development checkout, replace the package name with "link:/absolute/path/to/dsh-mnemon". Headless mounts the same Runtime context, Documents, Memory Space tools, lifecycle guidance, and supervised write path as a Web Agent. It does not mount the workbench, conversation buttons, RPC channels, or an interactive slash-command surface.

With storageScope=workspace, Headless resolves <invocation cwd>/.mnemon; no Web workspace registry is required. The one-shot runner exits when its Agent becomes idle, so shutdown cancels any delayed score-based background review that has not started. Explicit or model-guided writes that finish during the task are durable.

4. Configure storage and the interface

Open Settings → Memory System:

Memory System settings: entry placement, memory scope and layers

Workbench entry

By default, open the dedicated workbench from Memory System in the DSH sidebar. Choose Builtin in Settings, or set displayMode: builtin, to show the same Source pages as a conversation tab instead. Save switches the entry live without changing stored data.

Storage location

Scope Root Best suited for
Global (default) MNEMON_DATA_DIR or ~/.mnemon Sharing one memory set across workspaces
Workspace <workspace>/.mnemon Project isolation with cross-workspace inspection in the workbench
Custom dataDir A dedicated disk, mounted volume, or explicit directory

Save initializes a candidate runtime graph before atomically switching the Host. The page clears stale state and reloads automatically—no browser refresh is needed. Changing scope never migrates, merges, or deletes old data.

Default Source composition

A first installation should show Runtime, Documents, and Memory Spaces enabled. Each Source has one master switch. Enabling only permits on-demand use; it does not force recall on every turn. Disabling stops that Source's context, tools, background work, and data-plane Web/RPC together without deleting data. Its Sidebar tab is marked Off, and re-enabling restores the existing data. Keep all three defaults on for the first workflow.

In Workspace mode, conversation Agents, tools, and lifecycle hooks use the current conversation's effective root. Independent task Agents launched by Sidebar use the inspected workspace explicitly, including when no main session is selected. Its header reports a mismatch and offers one-click alignment. Builtin uses its owning conversation's scope for reads, writes and tasks, with no storage-mode badge, workspace picker or alignment control.

5. Open the Sidebar workbench

Click Memory System in the sidebar, then start on Status:

Status with CLI, versions, Runtime, Documents, Memory Spaces, and storage root

Confirm that:

  • the top right says Connected;
  • Mnemon and dsh-mnemon show installed versions;
  • the storage root matches your chosen scope;
  • Memory System reports default-three-tier, with the three default Sources matching Settings;
  • Runtime, Documents, and Memory Spaces report no errors.

If Mnemon is unavailable, run command -v mnemon and mnemon --version on macOS/Linux, or Get-Command mnemon and Test-Path "$env:LOCALAPPDATA\Programs\mnemon\mnemon.exe" on Windows PowerShell. See Troubleshooting for other symptoms.

6. Complete first verification

Create a Memory Space

  1. Open Memory Spaces → Overview.
  2. Select Create Memory Space.
  3. The default Choose manually path preserves the existing flow. Keep Mnemon Native for the official local-first default, or select and configure a third-party engine from the same panel.
  4. With a connected conversation, Smart selection adds data-boundary, required-capability, soft-preference, strategy-prompt, and multi-provider candidate controls.
  5. Use a narrow name such as “Project Decisions.”
  6. Describe what belongs there and which tasks should recall it, then enable read activation.

In an empty storage root, the first Memory Space uses Mnemon's native default Store ID while keeping the name and description you supplied. Its activation toggle affects DSH only.

Smart selection first has the Host enforce the provider allowlist, data boundary, and required capabilities. One remaining candidate is selected deterministically; only an ambiguous eligible set reaches an independent task Agent, which considers the soft preference and strategy prompt. Provider credentials never enter model context, and the resulting card retains the source, reason, and confidence.

See Long-term memory providers before connecting an external service or CLI.

Remember one test item

Open Remember and enter something stable, self-contained, future-useful, and secret-free. Leave advanced options collapsed so the independent task Agent can select a target, deduplicate, and distill.

Writing starts only after confirmation. Canceling the dialog changes no state.

Verify recall

  1. Open Memory Spaces → Recall.
  2. Ask a concrete question that should match the item.
  3. Use Direct recall first to inspect raw evidence.
  4. Confirm the result retains its Memory Space, category, importance, score, and ID.

You can also use conversation commands:

/mnemon status
/mnemon recall <focused query>

7. Verify memory inside a conversation

Ask a question that genuinely depends on history and allow the Agent to decide whether recall helps. After completion:

  • Turn memory appears below the reply if the turn used memory tools.
  • Expanding shows exact tools and links to their pages.
  • Save to memory opens an editable confirmation; canceling performs no write.

Ordinary conversation should not force recall. Current requests, repository files, and live tool results outrank historical content.

8. Next steps