dsh-mnemon 0.1.2 → 0.1.4

package/docs/en/README.md

@@ -1,40 +1,48 @@
 # dsh-mnemon Documentation
 
-[简体中文](../zh-CN/README.md) | **English** | [Back to project home](../../README.en.md)
+[简体中文](../zh-CN/README.md) | **English** | [Project home](../../README.md)
 
-These documents use the current implementation as the source of truth. The root README provides a quick overview; this section expands on design rationale, boundaries, transactional workflows, configuration, and operations.
+This hub is organized by what you need to accomplish. New users should follow Getting Started, then use the visual guide for the interface. Reference documents are for deployment, integration, and development work.
 
-## Recommended Reading Path
+## New-user path
 
-1. [Project Overview](./project-overview.md): project positioning, the Mnemon-to-DSH integration boundary, the three-tier model, system architecture, and good fits.
-2. [Getting Started](./getting-started.md): installation, initial configuration, and basic verification.
-3. [Architecture](./architecture.md): boundaries between the DSH Host, Web Client, control layer, subagents, and the Mnemon CLI.
-4. [Storage and the Three-Layer Memory Model](./storage-model.md): semantics and directory layout of Runtime Memory, Documents, and Memory Spaces.
-5. [Lifecycle and Core Workflows](./workflows.md): recall, writes, background review, capacity maintenance, and archiving.
-6. [Configuration Reference](./configuration.md): all settings, defaults, precedence, and provider requirements.
-7. [WebUI, Tools, Commands, and RPC](./interfaces.md): all user-facing and model-facing entry points.
-8. [Operations, Security, and Troubleshooting](./operations.md): locks, permissions, backup, recovery, and known limitations.
-9. [Development and Verification](./development.md): module structure, tests, builds, and release checks.
-10. [Roadmap](./roadmap.md): unfinished reliability, operations, and internationalization work.
-11. [Security Policy](../../SECURITY.md): supported versions, private vulnerability-reporting channels, and scope.
+1. [Getting Started](./getting-started.md): install Mnemon and the plugin, choose storage, and complete first-run verification.
+2. [Sidebar and conversation UI guide](./ui-guide.md): learn Status, Runtime, Memory Spaces, Documents, and in-conversation entry points.
+3. [Project overview](./project-overview.md): understand the three-tier model, cross-agent sharing boundary, read/write boundaries, and complete flow.
 
-## Terminology
+## Find a task
 
-| 中文 | English | Meaning |
+| I want to… | Document |
+|---|---|
+| Decide which tier should retain something | [Storage and the three-tier model](./storage-model.md) |
+| Share durable memory between DSH and other Mnemon-enabled agents | [Project overview: Cross-agent sharing](./project-overview.md#cross-agent-sharing-boundary) · [Configuration: Sharing scope](./configuration.md#choose-a-cross-agent-sharing-scope) |
+| Learn when injection, recall, remembering, and archiving happen | [Lifecycle and workflows](./workflows.md) |
+| Switch Sidebar / Buildin or global / workspace / custom storage | [Configuration reference](./configuration.md) |
+| Understand workspace inspection versus the Agent's effective directory | [UI guide: Workspace mode](./ui-guide.md#workspace-mode-separating-inspection-from-execution) |
+| Check or update Mnemon and dsh-mnemon | [Operations: Version checks and updates](./operations.md#version-checks-and-updates) |
+| Back up, restore, or migrate the complete memory root | [Operations: Backup and recovery](./operations.md#backup-and-recovery) |
+| Troubleshoot empty recall, misalignment, CLI, or provider errors | [Operations and troubleshooting](./operations.md#troubleshooting) |
+| Use model tools, `/mnemon` commands, or internal RPC | [Interface reference](./interfaces.md) |
+| Understand Host, workers, control plane, and data plane | [Architecture](./architecture.md) |
+| Modify code, screenshots, tests, or releases | [Development and verification](./development.md) |
+| See planned work | [Roadmap](./roadmap.md) |
+
+## Core terms
+
+| Term | Code / alternate name | Meaning |
 |---|---|---|
-| 记忆体 | Memory Space | A native named Mnemon Store with its own `mnemon.db` |
-| 运行时热记忆 | Runtime Memory / hot memory | Compact user profile and working memory injected directly into every turn |
-| 项目档案 | Project Documents | Complete Markdown project knowledge managed by the plugin |
-| 活跃档案 | Active Document | A Document included in default near-field search |
-| 归档 | Archive | Original text that has a long-term index and does not count toward active capacity |
-| 沉淀 | Distill / supervised writeback | Persistent writes after LLM judgment, deduplication, and routing |
-| 召回 | Recall | Reading historical evidence from active Memory Spaces |
-
-Brand names, commands, tool names, configuration keys, RPC endpoints, and code symbols remain untranslated.
-
-## Documentation Boundaries
-
-- Current user instructions and repository facts take precedence over historical memory.
-- `state/` is currently reserved; background review watermarks still exist only in Host process memory.
-- The main Web workspace is available in Chinese and English; command output, tool cards, and some backend diagnostics are not yet fully internationalized.
-- `docs/sedimentation-research.md` is a historical research record, not a specification or user guide.
+| Memory System | 记忆系统 | The complete dsh-mnemon entry in DSH |
+| Runtime Memory | USER / MEMORY | Hot memory projected into every turn |
+| Project Documents | Documents / 档案 | Managed, searchable project knowledge that keeps full Markdown structure |
+| Memory Space | 记忆体 | An independent, activatable, on-demand Mnemon Store |
+| Cross-agent memory sharing | 跨 Agent 共享 | Mnemon-enabled agents use the same root and Store to share durable memory, not the complete DSH context |
+| Remember | Distill / 沉淀 | Submit a candidate to a supervised subagent for qualification, dedupe, and writing |
+| Recall | 召回 | Retrieve bounded evidence from active Memory Spaces |
+| Archive | 归档 | Create a cold reference before moving an infrequently used Document out of active storage |
+
+## Documentation boundaries
+
+- User documentation targets the v0.1.4 Sidebar-default experience while covering the compatible Buildin presentation.
+- Architecture diagrams describe stable execution boundaries, not live monitoring. Use Status for current counts and versions.
+- RPC is an internal Host-to-client protocol, not a promised stable external API.
+- There is no formal fixed DSH / Mnemon version matrix yet. Back up and validate in an isolated root before upgrading.

package/docs/en/architecture.md

@@ -8,14 +8,16 @@
 
 - DSH provides the root Agent, lifecycle events, subagent providers, tools, commands, settings, and Web extension points;
 - the plugin provides the control plane for three knowledge layers, routing policies, transactional barriers, and UI;
-- the local `mnemon` CLI provides named Stores, SQLite persistence, four graph types, recall, relationships, and soft deletion.
+- the local `mnemon` CLI provides named Stores, SQLite persistence, four graph types, recall, relationships, and soft deletion, and defines the durable-data boundary shared with other Mnemon-enabled agents.
 
 ## Component Diagram
 
-[![dsh-mnemon runtime architecture](./assets/project-architecture.svg)](./assets/project-architecture.svg)
+[![dsh-mnemon runtime architecture](../assets/diagrams/en/project-architecture.svg)](../assets/diagrams/en/project-architecture.svg)
 
 Solid lines show deterministic data or control paths; purple dashed lines show LLM-supervised paths. Runtime Memory and Documents use managed files directly. Only Memory Spaces call the local Mnemon CLI through `MnemonRunner`. Click the image to open the original SVG.
 
+Cross-agent interoperability therefore applies only to Memory Spaces in the diagram: agents share durable memories and relations inside Mnemon Stores, not DSH conversation context, Runtime projections, or the Documents control plane. The plugin never pushes data to another agent; participants share by aligning their local Mnemon root and Store.
+
 ## Host Composition Root
 
 `src/index.ts::apply()` assembles the plugin in this order:
@@ -51,6 +53,8 @@ root Agent calls mnemon_recall
 
 Long-term semantic writes, relationships, soft deletion, and Memory Space creation, updates, and merges use the same pattern. Ordinary Runtime Memory and Document mutations first pass through the coordinator but are usually committed directly by the deterministic control layer; only capacity maintenance or archiving requires an additional worker.
 
+Physical Memory Space deletion is a separate deterministic destructive action. The WebUI must show a second confirmation, then invoke native Mnemon `store remove` through the loopback write RPC; the directory registration is removed only after the CLI deletion succeeds.
+
 ## Two Types of Subagent
 
 ### `spawn`

package/docs/en/configuration.md

@@ -12,7 +12,7 @@ $DSH_HOME/settings.yaml
 
 The default is commonly `~/.dsh/settings.yaml`. All current settings are marked `live`; after Save, the Host initializes a candidate runtime graph and then switches to it atomically.
 
-The Web settings card edits `displayMode`, `storageScope`, and `dataDir`. Other advanced settings must be changed directly in YAML.
+The Web settings page edits `displayMode`, `storageScope`, and `dataDir`, plus the Turn memory and Save-to-memory switches under `mnemon-ui`. The same page also imports or exports a ZIP for the effective root. Other advanced settings must be changed directly in YAML.
 
 ## Complete Example
 
@@ -52,9 +52,8 @@ mnemon:
 | `idleReviewMs` | `30000` | 5000–600000 ms | Required continuous idle time after the threshold is reached |
 | `tabEnabled` | `true` | boolean | Whether to mount the Web entry selected by `displayMode`; Host RPC, commands, and Agent tools remain registered when off |
 | `writeEnabled` | `true` | boolean | Whether to expose semantic write tools, write RPC, and write commands |
-| `mnemon-ui.toolviews` | `false` | boolean | In-conversation memory tool cards for `mnemon_*` calls; off by default (opt-in), **applies live after saving** |
-| `mnemon-ui.turnBar` | `false` | boolean | Turn-tail memory activity bar; off by default (opt-in), **applies live after saving** |
-| `mnemon-ui.saveAction` | `false` | boolean | “Save to memory” action on finalized assistant replies; off by default (opt-in), **applies live after saving** |
+| `mnemon-ui.turnBar` | `true` | boolean | Turn-tail memory activity bar; on by default, **applies live after saving** |
+| `mnemon-ui.saveAction` | `true` | boolean | “Save to memory” icon and confirmation on finalized assistant replies; on by default, **applies live after saving** |
 
 Both the `mnemon` Host/storage namespace and the `mnemon-ui` browser-presentation namespace apply live. The storage root switches atomically only after the new runtime graph initializes successfully. Legacy `mnemon.conversationInteraction` values remain a migration default, but new saves write only to `mnemon-ui`.
 
@@ -67,7 +66,7 @@ MNEMON_DATA_DIR when non-empty
   otherwise ~/.mnemon
 ```
 
-Suitable for users who want Runtime, Documents, and Memory Spaces shared across multiple workspaces.
+Suitable for users who want Runtime, Documents, and Memory Spaces shared across multiple workspaces. Other Mnemon-enabled agents can also share the Mnemon Memory Spaces when they use the same root.
 
 ### `workspace`
 
@@ -88,6 +87,16 @@ mnemon:
 
 `~` and `~/...` are also allowed. Relative paths are rejected.
 
+### Choose a Cross-Agent Sharing Scope
+
+| Goal | Recommended scope | Notes |
+|---|---|---|
+| Share durable memory among local agents | `global` | Every participant uses `~/.mnemon` or the same `MNEMON_DATA_DIR` |
+| Share one explicit data root | `custom` | Every participant configures the same absolute directory for isolation and backup |
+| Share only inside one project | `workspace` | Every participant aligns its Mnemon root to that project's `<workspace>/.mnemon` |
+
+Only the Mnemon durable tier under `data/<store>/mnemon.db` has native cross-agent interoperability. Runtime, Documents, DSH activation state, and UI metadata remain managed by dsh-mnemon.
+
 ## CLI Discovery Precedence
 
 ```text
@@ -173,7 +182,7 @@ routingGuidance=false
 
 ## Display Mode and the `tabEnabled` UI Switch
 
-`displayMode=sidebar` (the default) mounts the “Memory System” sidebar entry and its dedicated center-column workbench. `displayMode=buildin` instead registers the original DSH `conversation.view` tab. Saving first disposes the active entry and then mounts the target, so the two modes never appear simultaneously.
+`displayMode=sidebar` (the default) mounts the “Memory System” sidebar entry and its dedicated center-column workbench with a minimal, logo-free skin aligned with official DSH panels. `displayMode=buildin` instead registers the original DSH `conversation.view` tab and preserves its existing visuals. The modes share the functional workbench while keeping appearance definitions isolated. Saving first disposes the active entry and then mounts the target, so the two modes never appear simultaneously.
 
 `tabEnabled=false` removes the currently selected Web entry live. Host RPC, commands, and tools remain registered across display-mode and enablement changes so an Agent or command already in progress stays valid.
 

package/docs/en/development.md

@@ -106,10 +106,29 @@ Recommended scenarios:
 7. Documents: create, retrieve, update, manually archive, and leave original project files unchanged.
 8. Score-based review: light tasks do not trigger it; after reaching the threshold it waits for idle; a new turn can cancel it while preserving the watermark.
 9. Read-only: write tools, write commands, and write RPC are rejected while reads remain available.
-10. Status and browser console: no unhandled errors or warnings.
+10. Sidebar: all four primary tabs, four Memory Space secondary tabs, stable headings, filters, and progressive loading work.
+11. Conversation UI: Turn memory appears only for completed turns with activity; links land correctly; canceling Save to memory performs no write.
+12. Settings: Sidebar / Buildin, storage scopes, and both conversation switches apply live without refresh.
+13. ZIP: export can be previewed and merged into an isolated custom root; damaged checksums are rejected.
+14. Versions: checking never installs; link/manual sources offer no unsafe update; successful updates trigger a fresh status check.
+15. Status and browser console: no unhandled errors or warnings.
 
 Capacity limits, CLI timeouts, revision conflicts, and Host restarts should be verified in a dedicated fault-injection environment.
 
+## Maintaining Documentation Visuals
+
+Public UI screenshots live under `docs/assets/screenshots/`, shared by both language editions. Language-specific architecture diagrams live under `docs/assets/diagrams/zh-CN/` and `docs/assets/diagrams/en/`. When layout, primary copy, or defaults change:
+
+1. Use a real DSH Web profile, but first check that the frame contains no token, credential, or private personal data.
+2. Limit capture to inspection, filtering, expansion, and opening dialogs. When showing a write flow, stop before final confirmation.
+3. Replace screenshots with the same responsibility instead of accumulating versioned filenames. Add an asset only for a new user task.
+4. Refresh the README poster, GIF / MP4 demo, and both `ui-guide.md` files.
+5. Confirm PNG / JPEG extensions match actual encoding and that text is readable at original resolution.
+6. Remove unreferenced assets, stale Buildin layouts, and obsolete terminology.
+7. Run link/image checks, then open both READMEs and UI guides manually.
+
+README demo assets are `docs/assets/media/dsh-mnemon-memory-system-demo.*`. The demo should cover Status, Runtime, Memory Spaces, Documents, and in-conversation confirmation without actually submitting memory, updating components, or changing settings through automation.
+
 ## Modifying Subagent Schemas
 
 DSH structured output supports only a compact JSON Schema subset:
@@ -142,7 +161,8 @@ There is currently no formal schema-migration framework, so persistent formats m
 - keep commands, configuration keys, paths, and code symbols exactly the same;
 - cross-link corresponding language pages with relative paths;
 - prefer accessible SVGs with no scripts or external resources for architecture overviews; keep directory trees, commands, formulas, and short protocols as copyable `text` / ASCII;
-- keep only summaries in the root READMEs and place details on one authoritative docs page.
+- keep only summaries in the root READMEs and place details on one authoritative docs page;
+- for every user-visible interface change, also inspect `ui-guide.md`, `getting-started.md`, `configuration.md`, and `operations.md`.
 
 When the Web locale changes, the Chinese key set remains the type source of truth. The English dictionary must satisfy `Record<MnemonKey, string>` and preserve the same placeholders.
 
@@ -151,7 +171,7 @@ When the Web locale changes, the Chinese key set remains the type source of trut
 ```text
 [ ] pnpm run verify
 [ ] review source and generated lib diffs
-[ ] validate package file list includes README.en.md and docs
+[ ] validate package file list includes README.md, README.zh-CN.md, docs/assets, and bilingual docs
 [ ] install the built/local bundle into an isolated Web profile
 [ ] run real Mnemon CLI and WebUI smoke tests
 [ ] verify Chinese and English workspaces
@@ -160,7 +180,7 @@ When the Web locale changes, the Chinese key set remains the type source of trut
 [ ] back up any data root used for upgrade testing
 ```
 
-`package.json.files` currently publishes `lib`, the patch, both root READMEs, the public bilingual docs, and the License; the historical research ledger is excluded from the installed package.
+`package.json.files` currently publishes `lib`, the patch, both root READMEs, centrally managed documentation visuals, the public bilingual docs, and the License.
 
 ## Publishing to npm
 

package/docs/en/getting-started.md

@@ -1,44 +1,30 @@
 # Getting Started
 
-[简体中文](../zh-CN/getting-started.md) | **English** | [Documentation Center](./README.md)
+[简体中文](../zh-CN/getting-started.md) | **English** | [Documentation hub](./README.md)
+
+This guide goes from a blank environment to the first verified recall. It uses Sidebar and global storage by default. If installation is complete, jump to [First verification](#6-complete-first-verification).
 
 ## 1. Prerequisites
 
 You need:
 
-- a DSH Web profile that can start successfully;
+- a DSH Web profile that starts successfully;
 - a locally executable `mnemon` CLI;
-- a DSH subagent provider available for bounded subtasks.
-
-The exact provider requirements are:
+- a DSH subagent provider for isolated memory tasks.
 
-```text
-regular semantic operations
-  -> prefer provider named "spawn"
-  -> may fall back to another compatible provider
-
-scored background review
-  -> requires provider named "fork"
-  -> inheritsParentContext = true
-
-both paths require
-  -> outputSchema
-  -> toolFilter
-  -> persona
-  -> depthLimit
-```
+Regular semantic work prefers a provider named `spawn` with `outputSchema`, `toolFilter`, `persona`, and `depthLimit`. 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 plugin does not declare a fixed minimum-version matrix for DSH and Mnemon in its code. **Verified baseline**: `dsh-mnemon` 0.1.0 has been verified end-to-end on a live web profile running `@deepseek-ai/dsh` 0.1.0-rc.6 (2026-08-13 snapshot); last verified 2026-08-14. Before upgrading, run the verification steps on this page against an isolated data directory.
+The project does not declare a fixed minimum DSH / Mnemon matrix. This guide and its screenshots target dsh-mnemon v0.1.4. Back up and repeat this verification against an isolated root before upgrading.
 
 ## 2. Install Mnemon
 
-On macOS, the recommended installation method is Homebrew Cask:
+Homebrew Cask is recommended on macOS:
 
 ```sh
 brew install --cask mnemon-dev/tap/mnemon
 ```
 
-On macOS or Linux, you can also install it with Go:
+On macOS or Linux, Go is another option:
 
 ```sh
 go install github.com/mnemon-dev/mnemon@latest
@@ -50,116 +36,120 @@ Verify the binary:
 mnemon --version
 ```
 
-To inspect an upstream Store directly, you can also run `mnemon status`. This command opens the effective Store and may initialize default data or run migrations; do not treat it as a completely side-effect-free installation probe.
+If DSH cannot find it on `PATH`, set `MNEMON_CLI_PATH` or configure an absolute `mnemon.cliPath`. `mnemon status` opens the effective Store and may initialize data or run upstream migrations, so it is not a side-effect-free installation probe.
 
-If DSH cannot find it on `PATH`, set `MNEMON_CLI_PATH` or configure an absolute path in `mnemon.cliPath`.
+## 3. Install dsh-mnemon
 
-## 3. Install the Plugin
-
-Install it into the Web profile:
+Install into the Web profile:
 
 ```sh
 dsh plugin --profile web add dsh-mnemon
 ```
 
-Pre-release builds not yet published to npm can be installed from git:
+Use an absolute path for a development checkout:
 
 ```sh
-dsh plugin --profile web add "github:omdsh-dev/dsh-mnemon"
+dsh plugin --profile web add "link:/absolute/path/to/dsh-mnemon"
 ```
 
-For a local development checkout:
+Then start or restart the profile:
 
 ```sh
-dsh plugin --profile web add "link:/absolute/path/to/dsh-mnemon"
+dsh --profile web
 ```
 
-The plugin package's `cordis.patch.yml` mounts the Host plugin; the Web client bundle registers the session workspace and plugin settings card.
-
-### Upgrade and uninstall
-
-`dsh plugin` is a pnpm forwarder that runs inside the profile directory:
+Upgrade and uninstall:
 
 ```sh
-# Upgrade
 dsh plugin --profile web update dsh-mnemon
-
-# Uninstall (also removes its bundle registration from the profile)
 dsh plugin --profile web remove dsh-mnemon
 ```
 
-Uninstalling never deletes memory data: `global` data stays in `~/.mnemon`, and `workspace` / `custom` data stays in their directories, so reinstalling picks up where you left off.
+Uninstall removes the plugin registration, not memory data in global, workspace, or custom roots.
 
-To pause automatic reads/writes without uninstalling, turn off `writebackMode` / `recallMode` / `lifecycleEnabled` in the plugin configuration (see the [configuration reference](./configuration.md), “Toggle interactions”). To hide only the Web workspace, set `tabEnabled=false`; Host RPC, commands, and Agent tools remain available.
+## 4. Choose entry point and storage
 
-## 4. Choose a Storage Scope
+Open **Settings → Memory System**:
 
-Start the DSH Web profile:
+[![Memory System settings for display, storage, conversation UI, and backup](../assets/screenshots/settings-memory-system.png)](../assets/screenshots/settings-memory-system.png)
 
-```sh
-dsh --profile web
-```
+### Display mode
 
-On the dedicated “Settings -> Memory System” page, first choose a display mode: the default `sidebar` uses a dedicated sidebar workbench, while `buildin` uses the original conversation-area tab. Saving switches live. Then choose a storage scope:
+- **Sidebar** (default): a dedicated workbench opened from the DSH sidebar; recommended for most users.
+- **Buildin**: the original conversation-area tab with its established visuals.
 
-| Scope | Root directory | Best suited for |
+### Storage location
+
+| Scope | Root | Best suited for |
 |---|---|---|
-| `global` | `MNEMON_DATA_DIR` or `~/.mnemon` | Sharing one memory set across multiple workspaces |
-| `workspace` | `.mnemon` under each DSH workspace root | Project isolation and cross-workspace inspection |
-| `custom` | `dataDir` | An explicit disk, mounted volume, or dedicated data directory |
+| **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 |
 
-Settings are written to `$DSH_HOME/settings.yaml` and apply live after Save. Switching scopes does not move existing data; to preserve it, stop writes first and migrate with a complete ZIP backup.
+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.
 
-After selecting `workspace`, the workbench header can switch the workspace being inspected. This choice controls only which memory set the workbench displays and maintains; Agent execution always follows the current session. A global warning appears when the two differ and offers one-click alignment.
+In Workspace mode, the workbench selector changes only what data is being inspected. Agents, tools, and lifecycle hooks always use the current conversation's effective root. The header reports a mismatch and offers one-click alignment.
 
-## 5. Create Your First Memory Space
+## 5. Open the Sidebar workbench
 
-With the default `sidebar` mode, click “Memory System” in the DSH sidebar. With `buildin`, open the “Memory System” tab in the conversation area:
+Click **Memory System** in the sidebar, then start on **Status**:
 
-1. Open the “Memory Spaces” page.
-2. Create a narrowly scoped Memory Space, such as “Project Decisions.”
-3. Its description should explain what belongs there and which tasks should recall it.
-4. Enable its read toggle, or let the plugin activate it automatically after the first write.
+[![Status with CLI, versions, Runtime, Memory Spaces, Documents, and storage root](../assets/screenshots/status-overview.png)](../assets/screenshots/status-overview.png)
 
-An empty Memory Space may remain inactive by default. Activation controls only the read scope; writes may target any registered Memory Space, and a successful write automatically activates the target.
+Confirm that:
 
-## 6. Verify the Complete Path
+- the top right says Connected;
+- Mnemon and dsh-mnemon show installed versions;
+- the storage root matches your chosen scope;
+- Runtime, Memory Spaces, and Documents report no errors.
 
-First inspect deterministic status:
+If Mnemon is unavailable, run `command -v mnemon` and `mnemon --version`. See [Troubleshooting](./operations.md#troubleshooting) for other symptoms.
 
-```text
-/mnemon status
-```
+## 6. Complete first verification
 
-Then submit a stable, self-contained item that will remain useful in the future on the “Distill” page. The worker selects a Memory Space, checks for duplicates, and returns a structured receipt. Then verify recall:
+### Create a Memory Space
 
-```text
-/mnemon recall <a focused query that should match the new item>
-```
+1. Open **Memory Spaces → Overview**.
+2. Select **Create Memory Space**.
+3. Use a narrow name such as “Project Decisions.”
+4. Describe what belongs there and which tasks should recall it.
+5. Enable read activation.
+
+### Remember one test item
 
-Finally, check that:
+Open **Remember** and enter something stable, self-contained, future-useful, and secret-free. Leave advanced options collapsed so the memory subagent can select a target, deduplicate, and distill.
 
-- the “Memory Spaces” page shows the active Memory Space and graph;
-- “Content” shows the new item and its Memory Space;
-- CLI, runtime memory, Memory Space catalog, and subagent status are all healthy under “Status”;
-- the recall result includes a complete `memoryBodyId` and memory ID.
+Writing starts only after confirmation. Canceling the dialog changes no state.
 
-## 7. Recommended First Real Conversation
+### Verify recall
 
-Choose a question that genuinely depends on a historical decision instead of instructing the model to invoke memory tools unconditionally. The expected flow is:
+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:
 
 ```text
-user asks a history-dependent question
-  -> pre-step adds a short optional cue
-  -> main Agent decides whether history matters
-  -> recall worker selects active Memory Spaces
-  -> only useful evidence returns to the main Agent
+/mnemon status
+/mnemon recall <focused query>
 ```
 
-Ordinary conversation should not force recall. The current request, existing source files, and live tool results should take precedence over historical content.
+## 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.
+
+[![Turn memory and exact tool navigation](../assets/screenshots/conversation-turn-memory.png)](../assets/screenshots/conversation-turn-memory.png)
+
+Ordinary conversation should not force recall. Current requests, repository files, and live tool results outrank historical content.
 
-## 8. Next Steps
+## 8. Next steps
 
-- Read the [storage model](./storage-model.md) before choosing `storageScope`.
-- Read the [configuration reference](./configuration.md) to configure read-only mode or disable lifecycle cues.
-- Read the [operations guide](./operations.md) to establish backup and pre-upgrade verification procedures.
+- Use the [Sidebar and conversation UI guide](./ui-guide.md) to learn every page.
+- Use the [storage model](./storage-model.md) to choose Runtime, Documents, or Memory Spaces.
+- Use the [configuration reference](./configuration.md) for Workspace scope, read-only behavior, and lifecycle switches.
+- Use the [operations guide](./operations.md) to export your first ZIP backup and establish a pre-upgrade checklist.