dsh-mnemon 0.1.2 → 0.1.3

package/docs/en/project-overview.md

@@ -1,249 +1,133 @@
 # Project Overview: Local Three-Tier Memory for DSH
 
-[简体中文](../zh-CN/project-overview.md) | **English** | [Documentation Center](./README.md)
+[简体中文](../zh-CN/project-overview.md) | **English** | [Documentation hub](./README.md)
 
-> **`dsh-mnemon` deeply integrates [Mnemon](https://github.com/mnemon-dev/mnemon) with DSH, giving DSH comprehensive memory capabilities.**
+`dsh-mnemon` integrates [Mnemon](https://github.com/mnemon-dev/mnemon) Memory Spaces with DeepSeek Harness, then adds Runtime hot memory, Project Documents, lifecycle routing, bounded subagents, a deterministic control layer, and native DSH interfaces.
 
-It separates what must be visible every turn, project knowledge that should remain readable as a whole, and long-term history recalled across sessions into three clear tiers. DSH then supplies routing, lifecycle integration, bounded subagents, and the user interface.
+Its goal is not to store more text. It balances long-term continuity, current-fact priority, context cost, and recoverable writes.
 
-The central goal is to give an Agent long-term continuity while keeping the current task authoritative, context compact, writes auditable, and original data protected when maintenance fails.
+[![Memory Space overview with catalog, activation boundary, and multi-space graph](../assets/screenshots/overview-memory-graph.png)](../assets/screenshots/overview-memory-graph.png)
 
-[![Mnemon Memory Spaces page showing the Memory Space catalog, activation state, and live multi-space relationship graph](../zh-CN/assets/screenshots/overview-memory-graph.png)](../zh-CN/assets/screenshots/overview-memory-graph.png)
+## Why three tiers
 
-*The overview brings the Memory Space catalog, activation state, statistics, and live multi-space graph into one workspace. Select the image for its original resolution. The screenshot uses the Chinese locale; the workspace also supports English.*
+One memory tier cannot serve frequent injection, full-document reading, and cross-session recall equally well:
 
-## Why It Exists
-
-With only the current conversation, an Agent cannot reliably carry forward user preferences, project conventions, and historical decisions. Injecting the entire history into every prompt causes context growth, stale-information interference, and additional cost. One memory tier also cannot satisfy all of these needs well:
-
-| Need | Limit of one memory tier | dsh-mnemon approach |
+| Need | With one memory tier | dsh-mnemon's choice |
 |---|---|---|
-| Make stable preferences and conventions available next turn | Retrieval adds latency and can miss | Runtime Memory injects compact projections every turn |
-| Read a complete design, investigation, or procedure quickly | Fragmentation destroys narrative structure | Documents preserve searchable Markdown originals |
-| Find cross-session facts, decisions, and relationships | Loading everything pollutes current context | Memory Spaces recall graph-enhanced evidence on demand |
-| Keep infrequently used long-form material traceable | Keeping it hot consumes capacity forever | Create a durable cold reference before moving the original |
-| Let a model judge value without delegating system safety | LLM output cannot guarantee paths, concurrency, or transactions | The LLM owns semantic judgment; the Host owns hard boundaries |
-
-Whichever tier produces a hit, current user instructions, live tool results, and repository facts always take precedence over historical memory. The plugin supplies reviewable evidence and continuity; it does not let old content override current facts.
-
-To satisfy immediate visibility, complete reading, and durable recall together, the plugin establishes a layered, supervised memory architecture between DSH and local persistence.
-
-## Architecture at a Glance
-
-DSH provides the root Agent and extension surfaces, `dsh-mnemon` owns three-tier control, routing, and safety boundaries, and [Mnemon](https://github.com/mnemon-dev/mnemon) supplies the Memory Space capabilities for the durable tier. The plugin manages Runtime projections and Document originals; durable Memory Spaces and archive references are stored and retrieved through Mnemon.
-
-[![dsh-mnemon runtime architecture connecting DSH Web, the root Agent, the supervised control layer, and three local storage tiers](./assets/project-architecture.svg)](./assets/project-architecture.svg)
-
-The architecture has four useful boundaries:
-
-1. **Interaction boundary**: users reach memory through DSH conversations, `/mnemon` commands, model tools, and the Web workspace.
-2. **Supervision boundary**: lifecycle hooks provide only short cues; durable recall, semantic writes, and maintenance run in bounded subagents.
-3. **Deterministic control boundary**: the Host validates inputs, paths, permissions, revisions, UTF-8 capacity, locks, timeouts, and process arguments.
-4. **Local data boundary**: Runtime, Documents, and Memory Spaces share the selected `storageRoot`; memory persistence does not depend on a remote memory service.
-
-See [Architecture](./architecture.md) for detailed module ownership, root/worker dual paths, and RPC trust boundaries.
-
-Architecture boundaries determine who may execute an operation, the built-in prompt determines when the LLM should use a capability proactively, and the three-tier model determines the granularity of retained information and when it reaches context.
-
-## Built-in Prompt and Proactive Memory
-
-Through the system prompt, dynamically injected `USER.md` / `MEMORY.md`, lifecycle cues, and tool descriptions, the plugin presents every read and write capability across Runtime Memory, Documents, Memory Spaces, relationships, and directory maintenance. This encourages the LLM to invoke the relevant capability whenever the current task may benefit instead of waiting for the user to name individual tools.
-
-“Proactive” does not mean unconditional reads and writes on every turn. The current task remains authoritative, work continues without a memory call when none is useful, and a write is complete only with a valid tool receipt. When the user states an explicit intent, the LLM selects a path by information granularity and goal:
-
-| User intent or task signal | Preferred capability |
-|---|---|
-| Revisit earlier work, find historical evidence, or recover an exact old detail | Search active Documents first, then use `mnemon_recall` / `mnemon_related` when needed |
-| Remember a preference or stable convention, or correct old information | `mnemon_runtime_memory` with `add` / `replace` / `remove` |
-| Preserve a complete design, investigation, procedure, or handoff | Search Documents, then create or update a managed Document; archive when needed |
-| Retain durable facts or decisions, create relations, forget content, or adjust a Memory Space | Let a bounded worker deduplicate and route before using Memory Space write or maintenance capabilities |
-
-Even without the literal words “remember this,” an explicit new reusable fact can justify proactive hot-memory writeback. After completed work reaches the activity-score gate and the root Agent remains idle, a `fork` background review can also conservatively inspect hot memory and project Documents. See [Lifecycle and Core Workflows](./workflows.md) and the [Interface Reference](./interfaces.md) for the complete prompting strategy, gates, and tool permissions.
-
-## The Three-Tier Memory Model
-
-### 1. Runtime Memory: Hot Context Visible Every Turn
-
-Runtime Memory contains compact, frequently used stable information:
-
-- `target=user`: identity, role, long-term preferences, habits, communication style, and explicit collaboration requirements;
-- `target=memory`: project conventions, environment facts, decisions, tool behavior, and reusable lessons.
-
-`runtime/memories.json` is the only source of truth. `USER.md` and `MEMORY.md` are deterministic projections injected into every prompt. USER is limited to 4 KiB, MEMORY to 10 KiB, and a single entry to 8 KiB, all measured as UTF-8 bytes.
-
-Ordinary `add`, `replace`, and `remove` operations are handled by the deterministic control layer. Maintenance starts only when an `add` overflows: USER is conservatively compacted by a no-tool local worker, while MEMORY is semantically archived by a bounded worker before hot candidates are compacted. An overflowing `replace` is rejected and does not trigger automatic maintenance.
+| Know stable preferences and rules on the next turn | Retrieval adds latency and may miss | Inject compact Runtime projections every turn |
+| Read a complete design, investigation, or procedure | Fragmentation loses narrative and provenance | Keep managed Markdown Documents |
+| Find cross-session facts, decisions, and relations | Full loading pollutes context | Recall bounded graph-enhanced evidence on demand |
+| Preserve traceability for cold long-form material | Keeping it hot consumes capacity forever | Create a cold reference before moving the original |
+| Let a model judge value without owning system safety | An LLM cannot guarantee paths, locks, or transactions | Workers own semantics; the Host owns hard boundaries |
 
-[![Runtime Memory page showing USER and MEMORY hot context, capacity, and edit actions](../zh-CN/assets/screenshots/runtime-memory.png)](../zh-CN/assets/screenshots/runtime-memory.png)
+Priority always remains: **current user instructions → live tools and repository facts → historical memory**.
 
-*The Runtime page places the USER and MEMORY projections side by side with their capacity, importance, categories, and per-entry edit controls.*
+## The three-tier model
 
-### 2. Project Documents: Complete, Readable Project Knowledge
+### 1. Runtime Memory
 
-Documents preserve knowledge that is larger than one memory item but still needs fast, complete reading: architecture rationale, investigation findings, operating procedures, incident reviews, and implementation handoffs. Bodies remain Markdown and are searched deterministically by title, description, and content.
+Runtime retains compact, high-frequency information useful on many turns:
 
-A body is limited to 2 MiB, and rendered active Documents are limited to 10 MiB in total. When capacity is insufficient or a user archives manually, a bounded worker first writes a Mnemon cold reference containing a summary and SHA-256. The original moves to `archived/` only if its Document revision is still current. This ordering protects the active original, but it is not a rollback-capable distributed transaction across SQLite and the filesystem.
+- `USER.md`: identity, roles, preferences, habits, and explicit collaboration requirements;
+- `MEMORY.md`: project conventions, environment facts, decisions, tool behavior, and reusable lessons.
 
-Document sharing follows `storageScope`. Under `global` or `custom`, several workspaces may share one Document index. The live session workspace constrains new `sourcePaths`; it does not create separate ownership.
+`runtime/memories.json` is the source of truth; both Markdown files are deterministic projections. USER is capped at 4 KiB and MEMORY at 10 KiB, measured in UTF-8 bytes. Regular mutations are deterministic; only capacity maintenance may start a worker.
 
-[![Project Documents page showing the Document list, metadata, and rendered Markdown original](../zh-CN/assets/screenshots/documents-markdown.png)](../zh-CN/assets/screenshots/documents-markdown.png)
+### 2. Project Documents
 
-*The Documents page preserves both metadata and Markdown structure, combining list selection, search, and complete reading in one view.*
+Documents preserve complete designs, investigations, procedures, postmortems, and handoffs. Title, retrieval description, and body participate in deterministic search; the body keeps Markdown structure.
 
-### 3. Memory Spaces: Isolated Long-Term Recall
+One body may be up to 2 MiB and active rendered content up to 10 MiB. Before manual or capacity archiving, a bounded worker writes a Mnemon cold reference containing a summary and SHA-256. The original moves only if its revision is unchanged. Failure or conflict preserves active content.
 
-Each Memory Space corresponds to a native named Mnemon Store with its own `mnemon.db`. The plugin adds a stable ID, a human-readable name, a routing description, and an active state.
+### 3. Memory Spaces
 
-- Reads cover active Memory Spaces only.
-- Writes may target any registered Memory Space.
-- A successful write to an inactive target activates it automatically.
-- When creating a space, the model proposes the semantic name and boundary while the Host generates its stable ID.
-- Merge uses non-destructive import; source databases remain and are inactive by default afterward.
+Each Memory Space maps to an independent Mnemon Store and `mnemon.db`, with a stable ID, name, routing description, and activation state.
 
-The long-term layer retains `temporal`, `semantic`, `causal`, and `entity` relationships. Recall results include their Memory Space provenance and memory ID so the root Agent can traverse related context.
+- Reads cover active spaces only.
+- Writes may target any registered space and activate it after success.
+- Durable memory preserves temporal, semantic, causal, and entity relations.
+- Recall retains Memory Space provenance and memory IDs for related traversal.
 
-See [Storage and the Three-Tier Memory Model](./storage-model.md) for directory layouts, capacity details, and data authorities.
+See [Storage and the three-tier model](./storage-model.md) for authoritative files, capacities, and directories.
 
-The tiers are not isolated repositories. Together they form a near-to-far lookup path that expands only when needed, while explicit writes and controlled maintenance retain information at the appropriate frequency and granularity.
+## Architecture
 
-## From the Current Request to Durable Retention
+[![dsh-mnemon runtime architecture with DSH Web, Root Agent, supervised control, and three local tiers](../assets/diagrams/en/project-architecture.svg)](../assets/diagrams/en/project-architecture.svg)
 
-### Read: Start Near and Escalate Only When Needed
+Four boundaries shape the system:
 
-The plugin follows a near-to-far lookup gradient:
+1. **Interaction**: conversation, Sidebar / Buildin workbench, `/mnemon` commands, and model tools.
+2. **Supervision**: durable recall, semantic writes, and archiving run in bounded workers; lifecycle hooks provide short cues and scheduling signals.
+3. **Deterministic control**: the Host enforces schema, paths, permissions, capacity, locks, revisions, CLI arguments, timeouts, and cancellation.
+4. **Local data**: Runtime, Documents, and Memory Spaces share the effective `storageRoot` and require no remote memory service.
 
-1. Prefer the current request, live tool results, and repository facts.
-2. The root Agent can already see Runtime Memory injected for the turn.
-3. Search active Documents deterministically when complete project knowledge is needed.
-4. Use supervised recall for historical decisions, cross-session facts, or relationships.
-5. Follow a cold reference to an archived Document only when the complete original is required.
+### Memory System flow
 
-When the root Agent calls `mnemon_recall`, the coordinator starts an isolated worker. The worker may only inspect the Memory Space catalog, recall, and traverse related items. It selects active spaces by name and description and returns bounded structured evidence. Raw routing reasoning and the complete catalog do not enter the main conversation.
+This diagram describes stable execution boundaries, not a live status dashboard. Solid lines are deterministic Host paths; dashed lines require supervised LLM judgment.
 
-Direct Web search uses the deterministic service. “Agent search” performs the same retrieval first, then starts a no-Mnemon-tool evidence-only worker that can answer solely from the supplied hits and return only valid citations.
+[![Memory System flow across per-turn context, on-demand semantics, maintenance, and archive](../assets/diagrams/en/memory-system-flow.png)](../assets/diagrams/en/memory-system-flow.png)
 
-[![Recall page showing an Agent answer, source memory IDs, and raw recall results](../zh-CN/assets/screenshots/recall-agent-answer.png)](../zh-CN/assets/screenshots/recall-agent-answer.png)
+The three major flows are:
 
-*Agent search restricts evidence to the current hits while retaining source memory IDs and raw recall entries so the answer remains reviewable.*
+- **Per-turn context**: Runtime projections enter the prompt; the Root Agent searches active Documents deterministically when needed.
+- **On-demand semantics**: the Root Agent dispatches a `spawn` worker through the Host Bridge to active Memory Spaces; only bounded evidence or receipts return.
+- **Maintenance and archive**: the Host applies ordinary mutations atomically; idle review uses `fork` from a completed checkpoint; Document archive verifies a cold index before moving the original across a revision fence.
 
-In a real conversation, the root Agent can inspect the Memory Space catalog and project Documents before recalling from active spaces. If the current task genuinely needs an inactive space, a controlled workflow can activate it temporarily and restore its prior state after reading. The tool trace keeps lookup order, space selection, and provenance observable.
+See [Lifecycle and workflows](./workflows.md) for thresholds, cancellation, and failure semantics.
 
-[![Memory recall in a DSH conversation with Document search, multi-space recall, and state restoration](../zh-CN/assets/screenshots/conversation-recall.png)](../zh-CN/assets/screenshots/conversation-recall.png)
+## Read path: near to far
 
-### Write: Separate Semantic Judgment from System Guarantees
+A history-dependent request expands in this order:
 
-The read path determines when memory is useful. The write path must also define who judges value, who persists data, and how original data is protected when an operation fails.
+1. current request, live tool results, and repository files;
+2. Runtime Memory already in the prompt;
+3. deterministic search and on-demand full text from active Documents;
+4. supervised recall from active Memory Spaces;
+5. archived originals only after following a cold-reference hit.
 
-The plugin separates semantic judgment from system guarantees:
+`mnemon_recall` starts an isolated worker. It selects the narrowest spaces from names and descriptions and can use only allowed recall/related tools. The complete catalog and routing trace do not fill the root conversation.
 
-| LLM / worker responsibility | Hard Host guarantee |
-|---|---|
-| Decide whether content deserves long-term retention | Input schema and operation permissions |
-| Select the narrowest suitable Memory Space | Paths cannot escape workspace boundaries |
-| Identify duplicates, conflicts, and semantic clusters | CLI uses argument arrays with no shell |
-| Produce summaries, routing decisions, and relationship reasons | Timeouts, cancellation, output limits, and process serialization |
-| Decide whether complex work produced a reusable Document | File locks, temporary files, rename, and revision fences |
-| Perform conservative maintenance within its persona | UTF-8 capacity accounting and preservation on failure |
-
-Durable recall, semantic writes, and capacity maintenance use isolated `spawn` workers. Background review uses a checkpoint-inheriting `fork` worker only after a completed turn crosses the activity-score gate and the root Agent remains idle. A new turn cancels pending or active review. Worker context, tools, and output remain bounded while the Host retains deterministic validation; see the workflow guide for complete provider requirements and review boundaries.
-
-See [Lifecycle and Core Workflows](./workflows.md) for recall, writes, capacity maintenance, archiving, and the scoring formula.
-
-When the user explicitly asks to retain stable information, the root Agent selects structured tools by content type and writes individual items while the Host continues to validate the target, capacity, and revision. The final response reports what was actually stored instead of treating internal reasoning as persistence.
-
-[![Memory writeback in a DSH conversation with structured Runtime Memory tool calls and receipts](../zh-CN/assets/screenshots/conversation-writeback.png)](../zh-CN/assets/screenshots/conversation-writeback.png)
-
-### Three-Tier Example: Retaining an Architecture Decision
-
-Suppose a substantial task establishes that “every external CLI must be launched with an argument array and without a shell,” and also produces a complete threat analysis and migration guide:
-
-1. The frequently used operating rule can enter `MEMORY.md` as a compact fact and become visible from the next turn.
-2. The complete analysis and migration procedure belong in an active Document, preserving headings, code excerpts, and source files.
-3. If the decision should remain recallable across projects, a bounded worker selects a suitable Memory Space, checks for duplicates, writes a self-contained decision, and may link it to related security principles.
-4. When someone later asks why shell command concatenation is forbidden, the Agent sees the hot rule first, searches the Document for rationale, and recalls Mnemon evidence only when cross-session relationships matter.
-5. If the Document becomes infrequently used and active capacity is needed, the plugin writes a cold reference with its summary and hash before moving the original. The full analysis remains traceable through that reference.
-
-The same knowledge can therefore retain complementary expressions at different frequencies and narrative granularity, without copying the entire Document into every prompt or stretching one short rule into a long record.
-
-These workflows can be initiated proactively through Agent tools and can also be inspected, verified, and maintained in DSH's Memory workspace.
-
-## User and Integration Surfaces
-
-### Web Workspace
+Direct recall in the Web returns raw evidence. Agent query retrieves the same evidence, then gives it to an evidence-only worker with no Mnemon tools.
 
-The default `sidebar` mode opens a dedicated center-column workspace from the “Memory System” sidebar entry. Settings can switch to `buildin`, which restores the original conversation-area tab. Both modes reuse the same functional interface and are mounted mutually exclusively. It contains eight 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:
+## Write path: semantics versus guarantees
 
-Under the `workspace` storage scope, the header selector is an independent inspection context: it can display and maintain another registered DSH workspace without changing the current conversation. The execution context used by agents, tools, and lifecycle hooks always follows the current session cwd. When inspection and execution differ, the whole workbench shows both paths and a one-click alignment action; operations that need to start an Agent do not run while misaligned.
-
-| Page | Primary purpose |
+| Memory worker | Host guarantees |
 |---|---|
-| Status | CLI, runtime hot memory, storage scope, lifecycle, and subagent diagnostics |
-| Runtime | USER / MEMORY hot context, capacity, and deterministic maintenance |
-| Memory Spaces | Memory Space catalog, activation controls, metadata editing, and a live multi-space graph |
-| Documents | Search, read, edit, and archive managed Documents |
-| Distill | Give a candidate to a bounded worker for deduplication, routing, and writing |
-| Recall | Direct recall, related traversal, and evidence-only Agent search |
-| Entities | Frequent entities and their cross-graph context |
-| Content | Browse, copy, clone, or soft-delete durable memories |
-
-The primary Web workspace and settings card support Chinese and English and follow DSH's global light/dark theme. Commands, tool cards, and some backend diagnostics are not yet fully internationalized.
-
-[![Entities page showing frequent entities, hit counts, and entity-linked context](../zh-CN/assets/screenshots/entities-context.png)](../zh-CN/assets/screenshots/entities-context.png)
-
-*The Entities page ranks names by hit count and retains related memories, category, importance, score, and Memory Space provenance on the right.*
-
-[![Content page showing durable-memory filters, tags, relationships, and maintenance actions](../zh-CN/assets/screenshots/memory-content.png)](../zh-CN/assets/screenshots/memory-content.png)
-
-*The Content page supports filtering and inspection, then exposes relationship lookup, create-from-current, ID copy, and soft-delete actions.*
-
-### Model Tools and Commands
-
-The plugin registers read and write groups of `mnemon_*` model tools and provides:
-
-```text
-/mnemon status
-/mnemon recall <query>
-/mnemon related <full memory ID>
-/mnemon remember <stable, self-contained durable insight>
-/mnemon forget <full memory ID>
-```
-
-Web RPC is an internal bridge between the DSH Host and the plugin client: reads require `trusted-host`, while memory writes and settings require `loopback`. These channels are not a stable external HTTP SDK. See [WebUI, Tools, Commands, and RPC](./interfaces.md) for the complete interface matrix.
-
-## Local-First Reliability Design
+| Decide whether a candidate is durable | Input schema and operation permissions |
+| Select the narrowest space and deduplicate | Workspace and path confinement |
+| Distill self-contained content and relation rationale | Shell-free CLI, bounded output, timeout, and cancellation |
+| Decide when long-form work belongs in Documents | Locks, temporary files, rename, and revision fences |
+| Maintain conservatively within its persona | UTF-8 capacity and original-data preservation on failure |
 
-Beyond visibility, deterministic boundaries constrain paths, capacity, concurrency, and failure recovery.
+Durable recall and writes prefer isolated `spawn`. Score-based background review uses `fork` only after a completed turn crosses its threshold and remains idle. A new turn cancels pending or running review.
 
-- **Local data**: SQLite, the registry, Runtime JSON, and Documents live under the user-selected root.
-- **No-shell execution**: the Mnemon CLI uses `spawn(command, args, { shell: false })`.
-- **Bounded processes**: each call has a timeout, cancellation, and a 2 MiB combined stdout + stderr limit.
-- **Concurrency control**: Runtime and Documents use in-process queues and cross-instance lock files; CLI calls are serialized within one Runner.
-- **Original-first protection**: revision conflicts, worker failures, and invalid receipts never use stale results to overwrite current hot memory or move an active Document.
-- **Recoverable projections**: a valid `memories.json` can rebuild `USER.md` and `MEMORY.md`.
-- **Least-privilege workers**: every worker has a fixed persona, tool allowlist, structured output, and `maxDepth: 1`.
+## What users see
 
-These boundaries are not a secret scanner or a complete backup system. There is no deterministic credential detection, cross-system rollback, built-in consistent snapshot, or general corruption repair tool yet. Production data needs independent backup and recovery rehearsals; see [Operations, Security, and Troubleshooting](./operations.md).
+The default Sidebar has four primary pages: Status, Runtime, Memory Spaces, and Documents. Memory Spaces adds Overview, Recall, Content, and Entities. Add, edit, and Remember use consistent dialogs; long collections use filters and progressive loading.
 
-“Local-first” describes persistence location and CLI execution. It does not guarantee that selected content never leaves the device. If the DSH root model or subagent provider runs remotely, relevant prompts, candidates, or recalled evidence may still be sent to that provider; the actual data-processing boundary depends on the configured DSH model providers.
+Two additive entries surface memory in conversations:
 
-## Scope and Version Status
+- **Turn memory** summarizes this turn's memory tools and links to matching pages.
+- **Save to memory** loads a finalized reply into an editable confirmation; supervised writing starts only after confirmation.
 
-`dsh-mnemon` is useful when:
+See the [Sidebar and conversation UI guide](./ui-guide.md) for screenshots and workspace inspection/execution semantics. See [Interfaces](./interfaces.md) for tools, commands, and RPC.
 
-- long-running collaboration needs stable user preferences and working conventions;
-- a large project needs design rationale, investigation records, and handoff knowledge;
-- several knowledge domains need isolated storage, selective activation, and cross-space recall;
-- data should remain local while an LLM handles semantic judgment;
-- users need a visible, editable, diagnosable memory experience native to DSH.
+## Local-first reliability
 
-It is not intended for bulk persistence of secrets, raw logs, short-lived progress, or ordinary facts that can be reconstructed from the repository. It should not be treated as the source of truth, an authorization system, a backup system, or a proactive notification daemon.
+- CLI calls use argument arrays with `shell=false`, bounded output, timeout, and cancellation.
+- Runtime and Documents use in-process queues, cross-instance locks, temporary files, and rename.
+- Runtime revisions block stale compaction; Document revisions block movement of updated originals.
+- Subagents use persona, tool allowlists, structured output, and depth limits.
+- The WebUI never reads SQLite directly or supplies arbitrary update commands.
+- The plugin stores no model credentials, but it does not yet include a deterministic secret scanner.
 
-The current release is an early Beta and continues to evolve. See the [Roadmap](./roadmap.md) for selected planned capabilities and iteration priorities.
+These guarantees are not a rollback-capable distributed transaction across Mnemon SQLite and the filesystem. When uncertain, the system preserves original data. See [Operations](./operations.md) for complete boundaries and limitations.
 
-## Continue Reading
+## Continue reading
 
-- To run it now: read [Getting Started](./getting-started.md).
-- To understand code boundaries: read [Architecture](./architecture.md).
-- To choose a data scope: read [Storage and the Three-Tier Memory Model](./storage-model.md) and the [Configuration Reference](./configuration.md).
-- To understand transactions and review: read [Lifecycle and Core Workflows](./workflows.md).
-- To deploy or upgrade: read [Operations, Security, and Troubleshooting](./operations.md).
-- To contribute: read [Development and Verification](./development.md).
+- [Getting Started](./getting-started.md): installation and first verification.
+- [Sidebar and conversation UI guide](./ui-guide.md): complete visual workflow.
+- [Architecture](./architecture.md): modules, workers, and trust boundaries.
+- [Storage model](./storage-model.md): directories, capacity, and authority.
+- [Lifecycle and workflows](./workflows.md): injection, recall, writing, review, and archive.
+- [Configuration](./configuration.md): display, storage, and advanced switches.

package/docs/en/ui-guide.md

@@ -0,0 +1,156 @@
+# Sidebar and Conversation UI Guide
+
+[简体中文](../zh-CN/ui-guide.md) | **English** | [Documentation hub](./README.md)
+
+This guide follows the default `sidebar` presentation and a real user path through Memory System. Screenshots come from the v0.1.3 interface and use the Chinese locale; names, counts, and content vary with your data.
+
+## Start with the two display modes
+
+Choose the entry point and storage location under **Settings → Memory System**:
+
+[![Memory System settings: Sidebar, Buildin, storage, conversation UI, and backup](../assets/screenshots/settings-memory-system.png)](../assets/screenshots/settings-memory-system.png)
+
+| Mode | Best suited for |
+|---|---|
+| **Sidebar** (default) | A dedicated workbench opened from the DSH sidebar, visually aligned with official panels such as Task Board and SSH |
+| **Buildin** | The original conversation-area tab, preserving the previous layout and visuals for established workflows |
+
+Both modes share functionality, data, and Host services. Only entry and appearance differ. Saving switches live without a browser refresh or duplicate mounts.
+
+## Workbench anatomy
+
+The Sidebar header always answers three questions: which system is open, which storage-location mode is effective, and whether the Host is connected.
+
+The body has four primary tabs: **Status, Runtime, Memory Spaces, and Documents**. Memory Spaces adds **Overview, Recall, Content, and Entities** as secondary tabs, with **Remember** as its primary action.
+
+## 1. Status: establish that the system is ready
+
+[![Status summary for versions, Runtime, Memory Spaces, Documents, and storage root](../assets/screenshots/status-overview.png)](../assets/screenshots/status-overview.png)
+
+Status aggregates:
+
+- installed Mnemon CLI and dsh-mnemon versions;
+- USER / MEMORY Runtime counts;
+- active Memory Spaces and durable-memory counts;
+- active / archived Document counts;
+- the current storage root and concrete Runtime, Documents, and Memory Spaces directories.
+
+If this page reports a failure, avoid Remember or Archive until you follow [Troubleshooting](./operations.md#troubleshooting).
+
+### Check and update versions
+
+Open the version area for a read-only check:
+
+[![Check and update Mnemon and dsh-mnemon versions](../assets/screenshots/version-check.png)](../assets/screenshots/version-check.png)
+
+Checking never installs automatically. Update appears only when a newer release exists and the installation source is supported. After an update, the interface rechecks both components and refreshes Status automatically. Restart `dsh web` after a dsh-mnemon update to load new plugin code.
+
+## 2. Runtime: maintain hot memory used every turn
+
+[![Runtime capacity, scope filters, content filter, and unified list](../assets/screenshots/runtime-memory.png)](../assets/screenshots/runtime-memory.png)
+
+The top summarizes User Profile (`USER.md`) and Working Memory (`MEMORY.md`); one list below holds both.
+
+- Filter by All / User Profile / Working Memory.
+- Filter by content with the input on the right.
+- Chips identify source and importance.
+- Edit opens a dialog; Remove enters a destructive flow.
+- Long lists expand progressively through “Show N more.”
+
+### Add Runtime Memory
+
+[![Add hot memory dialog with content, category, and importance](../assets/screenshots/runtime-memory-add.png)](../assets/screenshots/runtime-memory-add.png)
+
+A Runtime item should be compact, independent, and repeatedly useful. Put identity, preferences, and explicit collaboration requirements in User Profile; put project, environment, decision, and tool lessons in Working Memory. Temporary progress and raw logs do not belong here.
+
+## 3. Memory Spaces: durable memory and relationships
+
+### Overview
+
+[![Memory Space catalog, activation, and multi-space relationship graph](../assets/screenshots/overview-memory-graph.png)](../assets/screenshots/overview-memory-graph.png)
+
+Each card leads with its name and routing description, pins read activation at the top right, and keeps statistics plus Edit / Delete in the footer. Activation controls reads only. A write may target an inactive registered space and activates it after success.
+
+The graph aggregates all active spaces. Layout, dragging, and reset affect browser presentation only and never mutate Mnemon data.
+
+### Remember
+
+[![Remember dialog with candidate and optional advanced constraints](../assets/screenshots/remember-dialog.png)](../assets/screenshots/remember-dialog.png)
+
+Normally, provide only a candidate. On confirmation, an isolated memory subagent decides whether it qualifies, chooses the narrowest space, deduplicates, distills, and writes. Expand advanced options only when a target space, category, or importance must be constrained explicitly.
+
+### Recall
+
+[![Recall query, category, strategy, raw evidence, and progressive results](../assets/screenshots/recall-agent-answer.png)](../assets/screenshots/recall-agent-answer.png)
+
+- **Direct recall** returns raw evidence without an answer Agent.
+- **Agent query** retrieves the same evidence, then gives it to an evidence-only worker with no Mnemon tools.
+- Category and strategy narrow the search.
+- Results retain space, category, importance, score, and ID.
+- Related traverses the graph; Forget is a destructive semantic action.
+
+Focused questions are more reliable than broad keywords.
+
+### Content and Entities
+
+| Content | Entities |
+|---|---|
+| [![Memory content and filters](../assets/screenshots/memory-content.png)](../assets/screenshots/memory-content.png) | [![Entity lookup and related memories](../assets/screenshots/entities-context.png)](../assets/screenshots/entities-context.png) |
+
+- **Content** browses durable memory without recall side effects and supports text/category filtering, Related, clone-from-item, Copy ID, and Forget.
+- **Entities** starts with frequent names, then aggregates related facts, decisions, and context for a selected or entered entity.
+
+Both expose visible / total counts and progressive loading.
+
+## 4. Documents: preserve complete project narratives
+
+[![Document capacity, progressive directory, and dedicated Markdown reader](../assets/screenshots/documents-markdown.png)](../assets/screenshots/documents-markdown.png)
+
+Documents are for designs, investigations, procedures, postmortems, and handoffs. The directory loads progressively; the reader keeps title, retrieval description, source, revision, hash, size, and full Markdown. Selecting a Document resets the reader to the top.
+
+Before active capacity is exhausted, least-recently-used Documents are cold-indexed in Mnemon and then moved to archived storage. A failure or revision conflict preserves the active original.
+
+### Create a Document
+
+[![Create managed Document dialog](../assets/screenshots/document-create-dialog.png)](../assets/screenshots/document-create-dialog.png)
+
+Title and retrieval description determine future discoverability; source paths preserve provenance; the body retains Markdown structure. Source project files remain read-only—the workbench creates a managed copy.
+
+## 5. In-conversation interaction
+
+### Turn memory
+
+[![Expanded Turn memory with recalls, Document search, and exact tool links](../assets/screenshots/conversation-turn-memory.png)](../assets/screenshots/conversation-turn-memory.png)
+
+The bar appears only on completed turns with memory activity. Expanding lists exact tools; clicking one opens its matching page while retaining the conversation context.
+
+[![Jump from Turn memory to Memory Space Recall](../assets/screenshots/conversation-memory-jump.png)](../assets/screenshots/conversation-memory-jump.png)
+
+### Save to memory
+
+[![Confirm save to memory and edit the candidate before dispatch](../assets/screenshots/conversation-save-dialog.png)](../assets/screenshots/conversation-save-dialog.png)
+
+Save to memory sits in the native action strip for finalized assistant replies. Clicking only opens confirmation and reads that reply. Edit or cancel freely; writing starts only after **Confirm and send to memory subagent**.
+
+## Workspace mode: separating inspection from execution
+
+Under `storageScope=workspace`, keep two concepts separate:
+
+| Concept | Selected by | Affects |
+|---|---|---|
+| **Inspected workspace** | Workbench header selector | Which `<workspace>/.mnemon` the UI displays and maintains manually |
+| **Effective workspace** | Current conversation / Agent cwd | Which root tools, commands, lifecycle hooks, and subagents actually use |
+
+You may inspect project B while staying in project A's conversation; the Agent still uses A. When they differ, the header explains the mismatch and offers one-click alignment. Agent-backed actions are rejected while misaligned to prevent writes to the wrong project. Switching inspection target unmounts old page state before loading the new root.
+
+`global` and `custom` resolve to one explicit root and need no alignment layer.
+
+## Common interaction rules
+
+- Solid blue is the primary action; blue outline usually means Edit; red is Remove, Delete, Archive, or Forget; neutral actions are View, Copy, and Cancel.
+- Physical destructive operations such as deleting a Memory Space require a dedicated confirmation. Forget is semantic soft deletion and should still be deliberate.
+- Saving settings clears stale page state and reloads automatically; no browser refresh is needed.
+- Sidebar primary headings remain stable; secondary headings within Memory Spaces scroll naturally.
+- Buildin preserves its established layout and visuals. Functional concepts still apply, though control positions differ.
+
+Next: [Getting Started](./getting-started.md) · [Storage model](./storage-model.md) · [Configuration](./configuration.md) · [Operations](./operations.md)

package/docs/zh-CN/README.md

@@ -1,40 +1,46 @@
 # dsh-mnemon 文档中心
 
-**简体中文** | [English](../en/README.md) | [返回项目首页](../../README.md)
+**简体中文** | [English](../en/README.md) | [项目首页](../../README.md)
 
-这组文档以当前代码实现为事实源。根 README 用于快速理解；这里展开设计理由、边界、事务流程、配置和运维方式。
+这里按“你现在要完成什么”组织文档。第一次使用从快速开始进入；需要理解页面时看 UI 指南；只有在部署、集成或开发时才需要进入参考文档。
 
-## 建议阅读路径
+## 新用户路径
 
-1. [项目介绍](./project-overview.md)：项目定位、Mnemon 与 DSH 的集成边界、三层模型、总体架构与适用场景。
-2. [快速开始](./getting-started.md)：安装、首次配置与基本验证。
-3. [架构设计](./architecture.md)：DSH Host、Web Client、控制层、子 Agent 与 Mnemon CLI 的边界。
-4. [存储与三层记忆模型](./storage-model.md)：Runtime、Documents、Memory Spaces 的语义和目录结构。
-5. [生命周期与核心流程](./workflows.md)：召回、写入、后台审查、容量整理和归档。
-6. [配置参考](./configuration.md)：全部配置、默认值、优先级和 provider 要求。
-7. [WebUI、工具、命令与 RPC](./interfaces.md)：所有用户与模型入口。
-8. [运维、安全与故障排查](./operations.md)：锁、权限、备份、恢复和已知限制。
-9. [开发与验证](./development.md)：模块结构、测试、构建和发布检查。
-10. [Roadmap](./roadmap.md)：尚未完成的可靠性、运维和国际化工作。
-11. [安全策略](../../SECURITY.md)：支持版本、漏洞私密报告渠道与范围。
+1. [快速开始](./getting-started.md)：安装 Mnemon 与插件，选择存储范围，完成第一次验证。
+2. [Sidebar 与对话交互指南](./ui-guide.md)：认识状态、运行时、记忆体、档案和对话内入口。
+3. [项目介绍](./project-overview.md)：理解三层模型、读写边界与完整流转。
 
-## 术语
+## 按任务查找
 
-| 中文 | English | 含义 |
-|---|---|---|
-| 记忆体 | Memory Space | 一个 Mnemon 原生命名 Store 及其独立 `mnemon.db` |
-| 运行时热记忆 | Runtime Memory / hot memory | 每轮直接注入的紧凑用户画像和工作记忆 |
-| 项目档案 | Project Documents | 由插件托管的完整 Markdown 项目知识 |
-| 活跃档案 | Active Document | 参与默认近场检索的档案 |
-| 归档 | Archive | 已建立长期索引、不计 active 容量的原文 |
-| 沉淀 | Distill / supervised writeback | 经 LLM 判断、查重和路由后的持久写入 |
-| 召回 | Recall | 从已激活记忆体读取历史证据 |
+| 我想要…… | 文档 |
+|---|---|
+| 决定一条信息应放在哪一层 | [存储与三层记忆模型](./storage-model.md) |
+| 了解每轮注入、召回、沉淀和归档何时发生 | [生命周期与核心流程](./workflows.md) |
+| 切换 Sidebar / Buildin、全局 / 工作区 / 自定义目录 | [配置参考](./configuration.md) |
+| 理解工作区“查看目录”与 Agent“实际生效目录” | [UI 指南：工作区模式](./ui-guide.md#工作区模式查看与执行分离) |
+| 检查或更新 Mnemon 与 dsh-mnemon | [运维指南：版本检查与更新](./operations.md#版本检查与更新) |
+| 备份、恢复或迁移完整记忆目录 | [运维指南：备份与恢复](./operations.md#备份与恢复) |
+| 排查召回为空、目录未对齐、CLI 或 Provider 问题 | [运维、安全与故障排查](./operations.md#故障排查) |
+| 使用模型工具、`/mnemon` 命令或内部 RPC | [接口参考](./interfaces.md) |
+| 理解 Host、worker、控制面与数据面 | [架构设计](./architecture.md) |
+| 修改代码、截图、测试或发布 | [开发与验证](./development.md) |
+| 查看下一阶段计划 | [Roadmap](./roadmap.md) |
+
+## 核心术语
 
-品牌名、命令、工具名、配置键、RPC endpoint 和代码符号保持原样，不翻译。
+| 中文 | 英文 / 代码名 | 含义 |
+|---|---|---|
+| 记忆系统 | Memory System | dsh-mnemon 在 DSH 中的完整入口 |
+| 运行时记忆 | Runtime Memory | 每轮注入的 USER / MEMORY 热记忆 |
+| 档案 | Project Documents | 受管、可检索、保留完整 Markdown 叙事的项目知识 |
+| 记忆体 | Memory Space | 独立、可激活、按需召回的长期 Mnemon Store |
+| 沉淀 | Remember / Distill | 把候选交给受监督子 Agent 判断、查重与写入 |
+| 召回 | Recall | 从已激活记忆体按需取回有界证据 |
+| 归档 | Archive | 先建立冷引用，再把不常用档案迁出 active 层 |
 
 ## 文档边界
 
-- 当前用户指令和仓库事实高于历史记忆。
-- `state/` 目前是预留目录；后台审查水位仍只存在于 Host 进程内。
-- 主要 Web 工作台已提供中文和英文；命令输出、工具卡和部分后端诊断尚未全部国际化。
-- `docs/sedimentation-research.md` 是历史研究记录，不是规范或用户手册。
+- 用户文档以 v0.1.3 的 Sidebar 默认体验为主，同时说明 Buildin 兼容形态。
+- 架构图表达稳定执行边界，不是实时监控面板；实时数量与版本以“状态”页为准。
+- RPC 是 Host 与插件客户端之间的内部协议，不承诺稳定外部 API。
+- 当前没有正式固定的 DSH / Mnemon 版本矩阵；升级前应备份并在隔离目录验证。

package/docs/zh-CN/architecture.md

@@ -12,7 +12,7 @@
 
 ## 组件图
 
-[![dsh-mnemon 运行时架构](./assets/project-architecture.svg)](./assets/project-architecture.svg)
+[![dsh-mnemon 运行时架构](../assets/diagrams/zh-CN/project-architecture.svg)](../assets/diagrams/zh-CN/project-architecture.svg)
 
 图中实线表示确定性数据或控制路径，紫色虚线表示 LLM 监督路径。Runtime Memory 和 Documents 直接使用受管文件；只有 Memory Spaces 通过 `MnemonRunner` 调用本地 Mnemon CLI。点击图片可以查看原始 SVG。
 
@@ -51,6 +51,8 @@ root Agent calls mnemon_recall
 
 长期语义写入、关系、软删除以及记忆体创建/更新/合并采用相同模式。运行时记忆和 Documents 的普通变更先经过 coordinator，但通常由确定性控制层直接提交；只有容量维护或归档需要额外 worker。
 
+记忆体目录的物理删除是单独的确定性危险操作：WebUI 必须先展示二次确认，随后经 loopback 写 RPC 调用 Mnemon 原生 `store remove`；只有 CLI 删除成功后才移除目录登记。
+
 ## 两类子 Agent
 
 ### `spawn`