dsh-mnemon 0.1.2 → 0.1.3

package/README.en.md

@@ -1,85 +1,33 @@
 <h1 align="center">dsh-mnemon</h1>
 
-<p align="center"><a href="./README.md">简体中文</a> | <strong>English</strong></p>
+<p align="center"><a href="./README.md">简体中文</a> · <strong>English</strong></p>
 
 <p align="center">
-  <a href="./docs/en/project-overview.md">
-    <img src="./docs/assets/dsh-mnemon-memory-system-demo-poster.jpg" alt="Mnemon Memory Spaces page with the multi-space catalog, activation state, and live relationship graph" width="720">
+  <a href="./docs/en/ui-guide.md">
+    <img src="./docs/assets/media/dsh-mnemon-memory-system-demo-poster.jpg" alt="dsh-mnemon Sidebar Memory System with Memory Space catalog and relationship graph" width="760">
   </a>
 </p>
 
-> **A deep integration of [Mnemon](https://github.com/mnemon-dev/mnemon) and DSH that gives DSH comprehensive memory capabilities.**
+<p align="center"><strong>Local, layered, supervised long-term memory for DeepSeek Harness.</strong></p>
 
-`dsh-mnemon` is a local Mnemon memory plugin for DeepSeek Harness (DSH). It organizes always-available runtime memory, readable project Documents, and on-demand long-term Memory Spaces into a supervised, searchable, maintainable three-tier system.
+`dsh-mnemon` integrates [Mnemon](https://github.com/mnemon-dev/mnemon) with DeepSeek Harness (DSH). It brings hot memory needed every turn, full project Documents, and on-demand long-term Memory Spaces into one workbench.
 
-The plugin brings Mnemon's durable Memory Space capabilities into DSH and adds Runtime Memory, Documents, lifecycle integration, bounded subagents, the WebUI, commands, and permission boundaries. Current user instructions and repository facts always take precedence over historical memory.
+- **Local first**: memory stays in local SQLite, JSON, and Markdown; no remote memory service is required.
+- **Three cooperating tiers**: Runtime Memory, Project Documents, and Memory Spaces retain information at the right granularity.
+- **Supervised writes**: isolated memory subagents make semantic decisions; the Host enforces paths, permissions, capacity, locks, and revisions.
+- **Native DSH experience**: a Sidebar workbench by default, turn memory, a Save-to-memory dialog, bilingual copy, and global themes.
 
-> **What's more?** More DSH-native capabilities are on the way. **Memory to View.**
+Current user instructions, repository files, and live tool results always take precedence over historical memory.
 
 ## Live demo
 
-![dsh-mnemon memory system walkthrough covering status, Runtime Memory, the multi-space graph, Documents, recall, entities, and supervised writeback](./docs/assets/dsh-mnemon-memory-system-demo.gif)
+![dsh-mnemon Sidebar Memory System and in-conversation interaction demo](./docs/assets/media/dsh-mnemon-memory-system-demo.gif)
 
-## Three memory tiers
+See the [Sidebar and conversation UI guide](./docs/en/ui-guide.md) for the complete visual walkthrough.
 
-| Tier | What belongs here | How it is retained | How it reaches context |
-|---|---|---|---|
-| Runtime Memory | User preferences, stable conventions, environment facts, frequently used lessons | Explicit operations or an eligible background review update `memories.json`, then generate `USER.md` / `MEMORY.md` projections | Injected directly every turn |
-| Project Documents | Designs, investigations, procedures, rationale, and handoffs | Create or update managed Markdown and `index.json`; capacity maintenance creates a Mnemon cold reference before moving the original | Search active Documents first, then read full text on demand |
-| Memory Spaces | Cross-session facts, decisions, entities, and relationships | A bounded `spawn` worker selects the narrowest space, checks duplicates, and writes four-graph memory through Mnemon `remember` / `link` | Recalled on demand from active Memory Spaces only |
+## Start in five minutes
 
-```text
-Reusable knowledge produced by current work
-          |
-          +-- Compact, stable, useful every turn
-          |      root Agent / eligible fork review
-          |                 |
-          |      add | replace | remove
-          |                 v
-          |      memories.json (source of truth)
-          |                 |
-          |      USER.md + MEMORY.md ----------> every prompt
-          |
-          +-- Complete designs, research, procedures, handoffs
-          |      root Agent / eligible fork review
-          |                 |
-          |          create | update
-          |                 v
-          |      index.json + active/*.md ------> full text after search
-          |                 |
-          |      Mnemon cold reference -> archived/*.md (maintenance)
-          |
-          `-- Cross-session facts, decisions, entities, relations
-                    root Agent
-                       |
-              spawn: route / deduplicate / write
-                       v
-              Mnemon CLI -> <space>/mnemon.db
-                       |
-              spawn: recall active spaces only -> bounded evidence
-```
-
-## Highlights
-
-- Proactive memory routing: built-in prompts, lifecycle cues, and tool descriptions encourage the LLM to use every read/write surface when useful; explicit requests to revisit, retain, correct, forget, or document are routed to the matching tier and operation.
-- One `global`, `workspace`, or `custom` storage scope for all three tiers.
-- A Memory Space directory in which each space has a stable ID, name, routing description, activation state, and its own `mnemon.db`.
-- Bounded subagents: isolated `spawn` workers handle durable recall and semantic writes; a `fork` worker inherits a completed checkpoint for background review.
-- Safe capacity maintenance: USER memory is compacted locally, MEMORY entries are archived before compaction, and Documents are cold-indexed before migration; revision conflicts preserve the original data.
-- Native DSH integration through model tools, `/mnemon` commands, a bilingual Web workspace, global light/dark themes, and diagnostics.
-- Local-first execution: the CLI is started with argument arrays and no shell, and no remote memory service is required.
-
-## Prerequisites
-
-- A working DSH Web profile.
-- A local `mnemon` CLI.
-- A subagent provider supporting `outputSchema`, `toolFilter`, `persona`, and `depthLimit`. Regular semantic work prefers `spawn`; the default background review also requires a provider named `fork` that inherits parent context.
-
-**Compatibility 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. The plugin declares no fixed minimum-version matrix. DSH moves fast: before upgrading, re-run the [Getting Started](./docs/en/getting-started.md) verification steps in an isolated profile or a backed-up data directory.
-
-## Quick start
-
-Install Mnemon:
+### 1. Install Mnemon
 
 ```sh
 # macOS
@@ -91,42 +39,66 @@ go install github.com/mnemon-dev/mnemon@latest
 mnemon --version
 ```
 
-Install the plugin and restart the DSH Web profile:
+### 2. Install the plugin
 
 ```sh
 dsh plugin --profile web add dsh-mnemon
 dsh --profile web
 ```
 
-Pre-release builds not yet published to npm can be installed from git:
+Use an absolute path for a local 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 checkout, use an absolute path:
+### 3. Open Memory System
 
-```sh
-dsh plugin --profile web add "link:/absolute/path/to/dsh-mnemon"
-```
+New installations use `sidebar` by default. Click **Memory System** in the DSH sidebar, then follow this first-run path:
 
-Open the dedicated “Settings -> Memory System” page to choose both a display mode and storage scope. The default `sidebar` mode opens a dedicated “Memory System” workbench from the sidebar; switching to `buildin` restores the original conversation-area tab. Saving switches live without mounting duplicate entries. Under the `workspace` scope, the sidebar workbench selector independently chooses which DSH workspace to inspect and maintain; agents, tools, and lifecycle hooks always continue to use the current session workspace. A global banner shows both paths when they diverge and aligns them with one click. The storage root switches atomically after the new directory initializes successfully, and changing the scope never migrates, merges, or deletes old data automatically.
+1. Confirm the Mnemon CLI, Runtime, Memory Spaces, and Documents are healthy under **Status**.
+2. Create a narrowly scoped Memory Space under **Memory Spaces → Overview**.
+3. Submit one stable, future-useful item through **Remember**.
+4. Verify it with a focused question under **Recall**.
+5. Return to the conversation and expand **Turn memory** below the answer.
 
-Upgrade and uninstall (`dsh plugin` forwards to pnpm inside the profile directory):
+See [Getting Started](./docs/en/getting-started.md) for provider requirements and complete verification.
 
-```sh
-# Upgrade
-dsh plugin --profile web update dsh-mnemon
+## One workbench, three memory tiers
 
-# Uninstall (also removes its bundle registration from the profile)
-dsh plugin --profile web remove dsh-mnemon
-```
+| Tier | Best for | How it reaches context |
+|---|---|---|
+| **Runtime** | User preferences, collaboration rules, project conventions, environment facts | Compact `USER.md` / `MEMORY.md` projections on every turn |
+| **Documents** | Designs, investigations, procedures, postmortems, and handoffs | Deterministic search of active Documents, then full text on demand |
+| **Memory Spaces** | Cross-session facts, decisions, entities, and relations | Bounded evidence recalled on demand from active spaces only |
+
+The tiers are not simple copies of the same content. Knowledge is routed by frequency, narrative length, and retrieval needs. See [Storage and the three-tier model](./docs/en/storage-model.md).
+
+## Sidebar workbench
+
+| Page | Main purpose |
+|---|---|
+| **Status** | Inspect connection, storage root, tier summaries, and Mnemon / dsh-mnemon versions |
+| **Runtime** | Inspect USER / MEMORY capacity; filter, add, edit, or remove hot memory |
+| **Memory Spaces** | Manage activation; switch among Overview, Recall, Content, and Entities; open Remember |
+| **Documents** | Search, read, create, edit, and archive managed Markdown documents |
+
+Add and edit use consistent dialogs, destructive actions require confirmation, long collections expose filters and progressive loading, and Documents use a dedicated reader.
+
+### Memory inside conversations
+
+| Turn memory | Save to memory |
+|---|---|
+| [![Expanded Turn memory with exact tool links](./docs/assets/screenshots/conversation-turn-memory.png)](./docs/assets/screenshots/conversation-turn-memory.png) | [![Confirm save to memory dialog](./docs/assets/screenshots/conversation-save-dialog.png)](./docs/assets/screenshots/conversation-save-dialog.png) |
 
-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. To pause automatic reads/writes without uninstalling, turn off `writebackMode` / `recallMode` / `lifecycleEnabled`; set `tabEnabled=false` to hide the currently selected Web entry (see the [configuration reference](./docs/en/configuration.md)).
+- **Turn memory** summarizes recalls, writes, and Document searches for the turn; expand it to jump to the matching page.
+- **Save to memory** loads an editable candidate. Only confirmation sends it to the memory subagent for qualification, deduplication, distillation, and writing.
 
-## Minimal configuration
+Both are on by default. Disable them independently under **Settings → Memory System → Conversation interface**; saved changes apply live.
 
-Configuration lives in `$DSH_HOME/settings.yaml` (commonly `~/.dsh/settings.yaml` by default):
+## Display and storage
+
+Configuration lives in `$DSH_HOME/settings.yaml` (commonly `~/.dsh/settings.yaml`):
 
 ```yaml
 mnemon:
@@ -134,23 +106,17 @@ mnemon:
   storageScope: global # global | workspace | custom
 ```
 
-- `global`: `MNEMON_DATA_DIR`, or `~/.mnemon` when unset.
-- `workspace`: `.mnemon` under each DSH workspace root; Agent execution follows the current session workspace while the Web workbench may inspect another target.
-- `custom`: an absolute or `~/...` path supplied through `dataDir`.
-
-See the [configuration reference](./docs/en/configuration.md) for every option, precedence rules, and read-only mode.
-
-## Entry points
-
-The Web workspace contains Status, Runtime, Memory Spaces, Documents, Distill, Recall, Entities, and Content pages in three divider-separated groups: “Status” stands alone; “Runtime, Memory Spaces, Documents” cover the three storage tiers; “Distill, Recall, Entities, Content” are the read/write tools. Its main interface follows DSH's global Chinese/English locale.
+| Choice | Behavior |
+|---|---|
+| `sidebar` | Default dedicated workbench aligned with official DSH panel styling |
+| `buildin` | Preserves the original conversation-area presentation and visuals |
+| `global` | Shares `~/.mnemon` (or `MNEMON_DATA_DIR`) across workspaces |
+| `workspace` | Uses `<workspace>/.mnemon`; the workbench may inspect another workspace while the Agent still follows the current session |
+| `custom` | Uses an absolute or `~/...` path supplied through `dataDir` |
 
-Memory also surfaces inside the conversation flow (conversation interface, **off by default**; enable each surface under Settings → Memory System → Conversation interface — changes apply live on save):
+Saved settings apply live without a manual refresh. Changing scope never migrates, merges, or deletes old data. If the inspected workspace differs from the session's effective workspace, the header explains the mismatch and offers one-click alignment.
 
-- **Memory tool cards**: every `mnemon_*` tool call renders as a memory-flavoured card — recalls show the query and hit count, writes show the subject summary — expandable to the raw arguments and structured result, with a one-click jump to the matching Memory view page;
-- **Turn memory bar**: completed calls are separated into successful recalls, writes, document searches, and inspections, with failures reported independently; expand it for the exact tool names;
-- **Save to memory**: every finalized assistant reply carries a “Save to memory” action; the candidate is editable, and submission routes through the isolated memory subagent (judgment, dedupe, distillation) without filling the main conversation context.
-
-Common commands:
+## Common commands
 
 ```text
 /mnemon status
@@ -160,30 +126,31 @@ Common commands:
 /mnemon forget <full memory ID>
 ```
 
-The recommended lookup order is: hot memory -> active Documents -> active Memory Spaces -> the archived original referenced by a hit. Do not persist temporary progress, raw logs, secrets, or ordinary facts that can be recovered directly from the repository.
+Recommended lookup order: Runtime Memory → active Documents → active Memory Spaces → archived original referenced by a hit.
+
+## Data and security boundaries
 
-## Permissions & data
+- The plugin reaches durable memory through the local `mnemon` CLI. The WebUI neither reads SQLite directly nor starts processes.
+- CLI calls use argument arrays with shell disabled, bounded output, timeouts, and cancellation.
+- The plugin stores no API keys. Subagent inference uses the provider already configured in DSH.
+- 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 data under `~/.mnemon`, workspace `.mnemon` roots, or custom directories.
 
-- **Files**: reads/writes data directories through the local `mnemon` CLI — `~/.mnemon` for the `global` scope, a user-chosen directory for `workspace` / `custom`. The plugin never writes those directories directly, and the WebUI never reads SQLite directly. `sourcePaths` cannot escape the originating session workspace or point into the managed Documents directory.
-- **Processes**: `mnemon` is started as an argument array with shell disabled, bounded output, and `SIGTERM` then `SIGKILL` on timeout.
-- **Network**: the plugin and Mnemon both run locally and make no remote calls; subagent model inference uses DSH's existing provider connection.
-- **Credentials**: the plugin stores and reads no credentials or API keys; model credentials are fully managed by DSH and your provider.
-- **User data**: all memory content (user profile, project Documents, long-term memory) stays in local SQLite / JSON and is never uploaded.
-- **Honest disclosure**: there is no deterministic credential/secret scanner yet — do not write keys, tokens, or private keys into hot memory, Documents, or Memory Spaces. For the full boundaries (process/file/Web/model) and backup/restore, see [Operations, security, and troubleshooting](./docs/en/operations.md).
+See [Operations, security, and troubleshooting](./docs/en/operations.md) for complete boundaries, backup, recovery, and diagnostics.
 
 ## Documentation
 
-- [Documentation hub](./docs/en/README.md)
-- [Project overview](./docs/en/project-overview.md)
-- [Getting started](./docs/en/getting-started.md)
-- [Architecture](./docs/en/architecture.md)
-- [Storage and three-tier memory model](./docs/en/storage-model.md)
-- [Lifecycle and workflows](./docs/en/workflows.md)
-- [Configuration reference](./docs/en/configuration.md)
-- [WebUI, tools, commands, and RPC](./docs/en/interfaces.md)
-- [Operations, security, and troubleshooting](./docs/en/operations.md)
-- [Development and verification](./docs/en/development.md)
-- [Roadmap](./docs/en/roadmap.md)
+| I want to… | Start here |
+|---|---|
+| Install and complete first-run verification | [Getting Started](./docs/en/getting-started.md) |
+| Learn every page and conversation entry | [Sidebar and conversation UI guide](./docs/en/ui-guide.md) |
+| Understand the three tiers and complete flow | [Project overview](./docs/en/project-overview.md) · [Lifecycle and workflows](./docs/en/workflows.md) |
+| Choose storage scope or advanced switches | [Configuration reference](./docs/en/configuration.md) |
+| Back up, update, or troubleshoot | [Operations, security, and troubleshooting](./docs/en/operations.md) |
+| Integrate tools, commands, or RPC | [Interface reference](./docs/en/interfaces.md) |
+| Develop, test, or publish | [Development and verification](./docs/en/development.md) |
+
+See the [documentation hub](./docs/en/README.md) for the full map.
 
 ## Development
 
@@ -192,8 +159,8 @@ pnpm install
 pnpm run verify
 ```
 
-`verify` runs TypeScript checks, Vitest, and the production build. Generated artifacts are written to and committed under `lib/`. See the [development guide](./docs/en/development.md) for release and real-WebUI validation procedures.
+`verify` runs TypeScript checks, Vitest, and the production build. Generated artifacts are committed under `lib/`.
 
 ## License
 
-MIT. For security issues, please report privately through the channels in [SECURITY.md](./SECURITY.md) instead of opening a public issue.
+MIT. Report security issues privately through [SECURITY.md](./SECURITY.md), not a public issue.

package/README.md

@@ -1,132 +1,104 @@
 <h1 align="center">dsh-mnemon</h1>
 
-<p align="center"><strong>简体中文</strong> | <a href="./README.en.md">English</a></p>
+<p align="center"><strong>简体中文</strong> · <a href="./README.en.md">English</a></p>
 
 <p align="center">
-  <a href="./docs/zh-CN/project-overview.md">
-    <img src="./docs/assets/dsh-mnemon-memory-system-demo-poster.jpg" alt="Mnemon 记忆体页：多记忆体目录、激活状态与实时关系图" width="720">
+  <a href="./docs/zh-CN/ui-guide.md">
+    <img src="./docs/assets/media/dsh-mnemon-memory-system-demo-poster.jpg" alt="dsh-mnemon Sidebar 记忆系统：记忆体目录与关系图" width="760">
   </a>
 </p>
 
-> **[Mnemon](https://github.com/mnemon-dev/mnemon) 与 DSH 的深度集成，为 DSH 提供完备的记忆系统能力。**
+<p align="center"><strong>让 DeepSeek Harness 拥有本地、分层、可监督的长期记忆。</strong></p>
 
-`dsh-mnemon` 是 DeepSeek Harness（DSH）的本地 Mnemon 记忆插件。它把每轮可见的运行时热记忆、可直接阅读的项目档案（Documents）和按需召回的长期记忆体（Memory Spaces）组织成一个受监督、可检索、可维护的三层体系。
+`dsh-mnemon` 将 [Mnemon](https://github.com/mnemon-dev/mnemon) 接入 DeepSeek Harness（DSH），并把每轮需要的热记忆、需要完整阅读的项目档案和按需召回的长期记忆体组织在同一个工作台中。
 
-插件把 Mnemon 的长期记忆体能力接入 DSH，并补充 Runtime Memory、Documents、生命周期、受限子 Agent、WebUI、命令和权限边界。当前用户指令和仓库事实始终高于历史记忆。
+- **本地优先**：记忆保存在本机 SQLite、JSON 与 Markdown 中，不依赖远程记忆服务。
+- **三层协作**：运行时记忆、项目档案、记忆体各自保存适合自己的信息粒度。
+- **受监督写入**：语义判断交给隔离的记忆子 Agent，路径、权限、容量、锁与 revision 由 Host 控制。
+- **DSH 原生体验**：默认 Sidebar 工作台、对话内回合记忆、存入记忆弹窗、双语界面与明暗主题。
 
-> **What's more?** 更多 DSH Native 能力支持正在路上。**Memory to View.**
+当前用户指令、仓库文件与实时工具结果始终高于历史记忆。
 
 ## 实机演示
 
-![dsh-mnemon 记忆系统实机演示：状态、运行时记忆、多记忆体图谱、档案、检索、实体与监督写回](./docs/assets/dsh-mnemon-memory-system-demo.gif)
+![dsh-mnemon Sidebar 记忆系统与对话内交互演示](./docs/assets/media/dsh-mnemon-memory-system-demo.gif)
 
-## 三层记忆
+完整逐页说明见 [Sidebar 与对话交互指南](./docs/zh-CN/ui-guide.md)。
 
-| 层级 | 适合保存 | 如何记住 | 如何进入上下文 |
-|---|---|---|---|
-| 运行时热记忆 | 用户偏好、稳定约定、环境事实、常用经验 | 显式操作或合格的后台审查更新 `memories.json`，再生成 `USER.md` / `MEMORY.md` 投影 | 每轮直接注入 |
-| 项目档案 | 设计、调查、流程、架构理由、交接材料 | 创建或更新受管 Markdown 与 `index.json`；整理容量时先建立 Mnemon 冷引用，再迁移原文 | 先检索 active Documents，再按需读取全文 |
-| 记忆体 | 跨会话的长期事实、决策、实体与关系 | 受限 `spawn` worker 选择最窄空间并查重，通过 Mnemon `remember` / `link` 写入四图 | 只从已激活 Memory Spaces 按需召回 |
+## 5 分钟开始使用
 
-```text
-当前任务产生的可复用信息
-          |
-          +-- 短小、稳定、每轮常用
-          |      主 Agent / 合格的 fork 审查
-          |                 |
-          |      add | replace | remove
-          |                 v
-          |      memories.json（权威源）
-          |                 |
-          |      USER.md + MEMORY.md ----------> 每轮 prompt
-          |
-          +-- 完整设计、调查、流程与交接
-          |      主 Agent / 合格的 fork 审查
-          |                 |
-          |          create | update
-          |                 v
-          |      index.json + active/*.md ------> 检索后按需全文
-          |                 |
-          |      Mnemon 冷引用 -> archived/*.md（容量整理）
-          |
-          `-- 跨会话事实、决策、实体与关系
-                    主 Agent
-                       |
-              spawn：选空间 / 查重 / 写入
-                       v
-              Mnemon CLI -> <space>/mnemon.db
-                       |
-              spawn：仅召回 active 空间 -------> 有界证据
-```
-
-## 核心能力
-
-- 主动记忆路由：内置 Prompt、生命周期提示与工具说明会启发 LLM 按需调用全部读写能力；用户明确要求回顾、记住、修改、忘记或建档时，会自动选择对应层级和操作。
-- 统一的 `global`、`workspace` 或 `custom` 存储范围，覆盖三层数据。
-- 多记忆体目录：每个记忆体拥有稳定 ID、名称、路由说明、激活状态和独立 `mnemon.db`。
-- 受限子 Agent：长期召回与语义写入使用隔离的 `spawn` worker；后台审查使用继承已完成 checkpoint 的 `fork` worker。
-- 可靠容量维护：USER 热记忆在本地保守合并，MEMORY 热记忆先归档再压缩，Documents 先建立冷索引再迁移；revision 冲突时保留原数据。
-- DSH 原生体验：模型工具、`/mnemon` 命令、双语 Web 工作台、全局明暗主题和诊断状态页。
-- 本地优先：CLI 以参数数组启动且禁用 shell；数据库和文档不需要远程记忆服务。
-
-## 前置条件
-
-- 可用的 DSH Web profile。
-- 本地 `mnemon` CLI。
-- 支持 `outputSchema`、`toolFilter`、`persona` 和 `depthLimit` 的子 Agent provider。常规语义操作优先使用 `spawn`；默认后台审查还需要名为 `fork`、可继承父上下文的 provider。
-
-**兼容基线**：`dsh-mnemon` 0.1.0 已在 `@deepseek-ai/dsh` 0.1.0-rc.6（2026-08-13 快照）的 live web profile 上实测通过，最后验证日期 2026-08-14。插件不声明固定的最低版本矩阵；DSH 迭代快，升级前先在隔离 profile 或已备份的数据目录中复跑[快速开始](./docs/zh-CN/getting-started.md)的验证步骤。
-
-## 快速开始
-
-安装 Mnemon：
+### 1. 安装 Mnemon
 
 ```sh
 # macOS
 brew install --cask mnemon-dev/tap/mnemon
 
-# macOS / Linux，也可通过 Go 安装
+# macOS / Linux，也可以通过 Go 安装
 go install github.com/mnemon-dev/mnemon@latest
 
 mnemon --version
 ```
 
-安装插件并重启 DSH Web profile：
+### 2. 安装插件
 
 ```sh
 dsh plugin --profile web add dsh-mnemon
 dsh --profile web
 ```
 
-未发布到 npm 的预发布版本可从 git 安装：
-
-```sh
-dsh plugin --profile web add "github:omdsh-dev/dsh-mnemon"
-```
-
 本地开发检出使用绝对路径：
 
 ```sh
 dsh plugin --profile web add "link:/absolute/path/to/dsh-mnemon"
 ```
 
-打开 DSH 的“设置 -> 记忆系统”独立配置页即可选择展示形态与存储范围。默认 `sidebar` 从左侧栏进入独立“记忆系统”工作台；切换为 `buildin` 则恢复原有的对话区内嵌标签页，保存后实时切换且不会重复挂载。`workspace` 范围下可在侧边栏工作台顶部独立切换要查看和维护的 DSH 工作区；Agent、工具和生命周期仍始终使用当前会话工作区。两者不一致时全局提示会同时显示查看目录和实际生效目录，并可一键对齐。存储根会在新目录初始化成功后原子切换，切换范围不会自动迁移、合并或删除旧数据。
+### 3. 打开记忆系统
 
-升级与卸载（`dsh plugin` 转发给 profile 目录下的 pnpm）：
+安装后默认使用 `sidebar`：点击 DSH 左侧栏的“记忆系统”即可进入。第一次使用建议按以下顺序：
 
-```sh
-# 升级
-dsh plugin --profile web update dsh-mnemon
+1. 在“状态”确认 Mnemon CLI、运行时、记忆体与档案均正常；
+2. 在“记忆体 → 概览”创建一个边界明确的记忆体；
+3. 用“沉淀记忆”提交一条稳定、未来仍有用的信息；
+4. 在“检索”用一个聚焦问题验证召回；
+5. 回到对话，展开回复下方的“本回合记忆”查看工具轨迹。
 
-# 卸载（同时从 profile 移除其 bundle 注册）
-dsh plugin --profile web remove dsh-mnemon
-```
+更完整的安装、Provider 要求与验证步骤见[快速开始](./docs/zh-CN/getting-started.md)。
 
-卸载不会删除记忆数据：`global` 范围数据留在 `~/.mnemon`，`workspace` / `custom` 范围数据留在对应目录，重新安装后即可继续使用。若只想临时停用自动读写而不卸载，可在插件配置里关闭 `writebackMode` / `recallMode` / `lifecycleEnabled`；`tabEnabled=false` 可隐藏当前展示形态的 Web 入口（详见[配置参考](./docs/zh-CN/configuration.md)）。
+## 一个工作台，三层记忆
 
-## 最小配置
+| 层级 | 适合保存 | 如何进入上下文 |
+|---|---|---|
+| **运行时** | 用户偏好、协作要求、项目约定、环境事实 | `USER.md` / `MEMORY.md` 每轮紧凑注入 |
+| **档案** | 设计、调查、流程、复盘、交接材料 | 先确定性检索 active Documents，再按需阅读全文 |
+| **记忆体** | 跨会话事实、决策、实体与关系 | 只从已激活 Memory Spaces 按需召回有界证据 |
 
-配置位于 `$DSH_HOME/settings.yaml`（默认通常为 `~/.dsh/settings.yaml`）：
+三层不是同一内容的简单复制：信息会按使用频率、叙事长度和召回方式进入最合适的层级。完整规则见[存储与三层记忆模型](./docs/zh-CN/storage-model.md)。
+
+## Sidebar 工作台
+
+| 页面 | 主要用途 |
+|---|---|
+| **状态** | 检查连接、存储根、三层数据摘要，以及 Mnemon / dsh-mnemon 版本 |
+| **运行时** | 查看 USER / MEMORY 容量，筛选、添加、编辑或移除热记忆 |
+| **记忆体** | 管理激活边界；在概览、检索、内容、实体之间切换；打开“沉淀记忆” |
+| **档案** | 搜索、阅读、新建、编辑与归档受管 Markdown 文档 |
+
+添加与编辑使用统一弹窗；危险操作需要二次确认；长列表采用筛选、计数与“加载更多”，档案正文使用独立阅读区域。
+
+### 对话内记忆
+
+| 本回合记忆 | 存入记忆 |
+|---|---|
+| [![展开本回合记忆并查看工具入口](./docs/assets/screenshots/conversation-turn-memory.png)](./docs/assets/screenshots/conversation-turn-memory.png) | [![确认存入记忆弹窗](./docs/assets/screenshots/conversation-save-dialog.png)](./docs/assets/screenshots/conversation-save-dialog.png) |
+
+- **本回合记忆**汇总本轮的召回、沉淀与档案检索；展开后可以跳到对应页面。
+- **存入记忆**先加载可编辑候选，只有确认后才交给记忆子 Agent 判断、查重、提炼并写入。
+
+这两个入口默认开启，可在“设置 → 记忆系统 → 对话界面”中分别关闭，保存后实时生效。
+
+## 展示与存储
+
+配置位于 `$DSH_HOME/settings.yaml`（通常为 `~/.dsh/settings.yaml`）：
 
 ```yaml
 mnemon:
@@ -134,23 +106,17 @@ mnemon:
   storageScope: global # global | workspace | custom
 ```
 
-- `global`：`MNEMON_DATA_DIR`，未设置时为 `~/.mnemon`。
-- `workspace`：每个 DSH 工作区各自根目录下的 `.mnemon`；Agent 执行跟随当前会话工作区，Web 工作台可独立选择查看目标。
-- `custom`：`dataDir` 指定的绝对路径或 `~/...` 路径。
-
-完整配置、覆盖优先级和只读模式见[配置参考](./docs/zh-CN/configuration.md)。
-
-## 使用入口
-
-Web 工作台提供状态、运行时、记忆体、档案、沉淀、检索、实体、内容八个页面，分为三组：「状态」独立成第一组；「运行时、记忆体、档案」对应三层存储；「沉淀、检索、实体、内容」为读写工具。主要界面随 DSH 全局语言在中文与英文间切换。
+| 选择 | 行为 |
+|---|---|
+| `sidebar` | 默认；左侧栏独立工作台，采用与 DSH 官方面板一致的极简外观 |
+| `buildin` | 保留原有对话区内嵌形态及其既有视觉 |
+| `global` | 多个工作区共享 `~/.mnemon`（或 `MNEMON_DATA_DIR`） |
+| `workspace` | 每个工作区使用自己的 `<workspace>/.mnemon`；工作台可查看其他工作区，Agent 仍跟随当前会话 |
+| `custom` | 使用 `dataDir` 指定的绝对路径或 `~/...` |
 
-记忆也会在对话流中直接体现（对话内交互，**默认关闭**，可在「设置 → 记忆系统 → 对话界面」中逐项开启，保存即实时生效）：
+设置保存后实时生效，无需手动刷新。切换存储范围不会自动迁移、合并或删除旧数据；工作区查看目标与会话实际目录不一致时，顶部会提示并提供一键对齐。
 
-- **记忆工具卡**：每个 `mnemon_*` 工具调用都以记忆风格的卡片呈现——召回显示查询与命中数、写入显示对象摘要，可展开查看参数与结构化结果，并可一键跳到记忆视图对应页面；
-- **回合记忆条**：完成的回合若触及记忆，回合尾会按成功结果区分召回、沉淀、档案检索和检查，并单独标出失败数；展开可见具体工具名；
-- **存入记忆**：每条已定稿的助手回复旁有「存入记忆」按钮，候选内容可编辑，提交后由隔离的记忆子 Agent 判断、查重并沉淀，不占用主对话上下文。
-
-常用命令：
+## 常用命令
 
 ```text
 /mnemon status
@@ -160,30 +126,31 @@ Web 工作台提供状态、运行时、记忆体、档案、沉淀、检索、
 /mnemon forget <完整记忆 ID>
 ```
 
-推荐的查询顺序是：热记忆 -> active Documents -> 已激活记忆体 -> 命中记录指向的归档原文。不要把临时进度、原始日志、秘密或可直接从仓库重新获得的普通事实写入长期记忆。
+推荐查询顺序：运行时热记忆 → active Documents → 已激活记忆体 → 命中记录指向的归档原文。
+
+## 数据与安全边界
 
-## 权限与数据
+- 插件通过本地 `mnemon` CLI 访问长期记忆；WebUI 不直接读取 SQLite，也不直接启动进程。
+- CLI 使用参数数组且禁用 shell；输出、超时和取消均有边界。
+- 插件不保存 API key；子 Agent 推理复用 DSH 已配置的 Provider。
+- 当前没有确定性的秘密扫描器。不要把密钥、token、私钥或原始敏感日志写入任何记忆层。
+- 卸载插件不会删除 `~/.mnemon`、工作区 `.mnemon` 或自定义目录中的数据。
 
-- **文件**：通过本地 `mnemon` CLI 读写数据目录——`global` 范围是 `~/.mnemon`，`workspace` / `custom` 范围是用户指定的目录；插件不直接写这些目录，WebUI 也不直接读 SQLite。`sourcePaths` 不能逃出发起会话的工作区，也不能指向受管 Documents 目录。
-- **进程**：`mnemon` 以参数数组启动且禁用 shell，输出有上限，超时先 `SIGTERM` 再 `SIGKILL`。
-- **网络**：插件与 Mnemon 均本地运行，不发起远程调用；子 Agent 的模型推理走 DSH 已有的 provider 连接。
-- **凭据**：插件不存储、不读取任何凭据或 API key，模型凭据完全由 DSH 与 provider 管理。
-- **用户数据**：记忆内容（用户画像、项目档案、长期记忆）全部落在本地 SQLite / JSON，不会上传。
-- **诚实披露**：当前没有确定性的凭据/秘密检测器，请勿向热记忆、Documents 或 Memory Spaces 写入密钥、token 或私钥。完整边界（进程/文件/Web/模型）与备份恢复见[运维、安全与故障排查](./docs/zh-CN/operations.md)。
+完整边界、备份恢复与故障排查见[运维指南](./docs/zh-CN/operations.md)。
 
 ## 文档
 
-- [文档中心](./docs/zh-CN/README.md)
-- [项目介绍](./docs/zh-CN/project-overview.md)
-- [快速开始](./docs/zh-CN/getting-started.md)
-- [架构设计](./docs/zh-CN/architecture.md)
-- [存储与三层记忆模型](./docs/zh-CN/storage-model.md)
-- [生命周期与核心流程](./docs/zh-CN/workflows.md)
-- [配置参考](./docs/zh-CN/configuration.md)
-- [WebUI、工具、命令与 RPC](./docs/zh-CN/interfaces.md)
-- [运维、安全与故障排查](./docs/zh-CN/operations.md)
-- [开发与验证](./docs/zh-CN/development.md)
-- [Roadmap](./docs/zh-CN/roadmap.md)
+| 我想要…… | 从这里开始 |
+|---|---|
+| 安装并完成第一次验证 | [快速开始](./docs/zh-CN/getting-started.md) |
+| 认识每个页面与对话内入口 | [Sidebar 与对话交互指南](./docs/zh-CN/ui-guide.md) |
+| 理解三层模型和完整流转 | [项目介绍](./docs/zh-CN/project-overview.md) · [生命周期与核心流程](./docs/zh-CN/workflows.md) |
+| 选择存储范围或高级开关 | [配置参考](./docs/zh-CN/configuration.md) |
+| 备份、更新或排查问题 | [运维、安全与故障排查](./docs/zh-CN/operations.md) |
+| 集成工具、命令或 RPC | [接口参考](./docs/zh-CN/interfaces.md) |
+| 开发、测试或发布 | [开发与验证](./docs/zh-CN/development.md) |
+
+完整目录见[文档中心](./docs/zh-CN/README.md)。
 
 ## 开发
 
@@ -192,8 +159,8 @@ pnpm install
 pnpm run verify
 ```
 
-`verify` 依次运行 TypeScript 检查、Vitest 测试和生产构建。构建产物写入并提交到 `lib/`；详细发布与真实 WebUI 验证流程见[开发文档](./docs/zh-CN/development.md)。
+`verify` 依次运行 TypeScript 检查、Vitest 和生产构建。构建产物提交在 `lib/` 中。
 
 ## License
 
-MIT。发现安全问题请通过 [SECURITY.md](./SECURITY.md) 中的渠道私下报告，不要直接开公开 issue。
+MIT。安全问题请按 [SECURITY.md](./SECURITY.md) 私下报告，不要直接创建公开 issue。