dsh-mnemon 0.1.1 → 0.1.3

package/docs/en/project-overview.md

@@ -1,247 +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.
+| 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 |
 
-[![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)
+Priority always remains: **current user instructions → live tools and repository facts → historical memory**.
 
-The architecture has four useful boundaries:
+## The three-tier model
 
-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.
+### 1. Runtime Memory
 
-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 |
+Runtime retains compact, high-frequency information useful on many turns:
 
-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.
+- `USER.md`: identity, roles, preferences, habits, and explicit collaboration requirements;
+- `MEMORY.md`: project conventions, environment facts, decisions, tool behavior, and reusable lessons.
 
-## The Three-Tier Memory Model
+`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.
 
-### 1. Runtime Memory: Hot Context Visible Every Turn
+### 2. Project Documents
 
-Runtime Memory contains compact, frequently used stable information:
+Documents preserve complete designs, investigations, procedures, postmortems, and handoffs. Title, retrieval description, and body participate in deterministic search; the body keeps Markdown structure.
 
-- `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.
+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.
 
-`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.
+### 3. Memory Spaces
 
-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.
+Each Memory Space maps to an independent Mnemon Store and `mnemon.db`, with a stable ID, name, routing description, and activation state.
 
-[![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)
+- 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.
 
-*The Runtime page places the USER and MEMORY projections side by side with their capacity, importance, categories, and per-entry edit controls.*
+See [Storage and the three-tier model](./storage-model.md) for authoritative files, capacities, and directories.
 
-### 2. Project Documents: Complete, Readable Project Knowledge
+## Architecture
 
-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.
+[![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)
 
-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.
+Four boundaries shape the system:
 
-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.
+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.
 
-[![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)
+### Memory System flow
 
-*The Documents page preserves both metadata and Markdown structure, combining list selection, search, and complete reading in one view.*
+This diagram describes stable execution boundaries, not a live status dashboard. Solid lines are deterministic Host paths; dashed lines require supervised LLM judgment.
 
-### 3. Memory Spaces: Isolated Long-Term Recall
+[![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)
 
-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.
+The three major flows are:
 
-- 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.
+- **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.
 
-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.
+See [Lifecycle and workflows](./workflows.md) for thresholds, cancellation, and failure semantics.
 
-See [Storage and the Three-Tier Memory Model](./storage-model.md) for directory layouts, capacity details, and data authorities.
+## Read path: near to far
 
-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.
+A history-dependent request expands in this order:
 
-## From the Current Request to Durable Retention
+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.
 
-### Read: Start Near and Escalate Only When Needed
+`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.
 
-The plugin follows a near-to-far lookup gradient:
+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.
 
-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.
+## Write path: semantics versus guarantees
 
-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.
-
-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.
-
-[![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)
-
-*Agent search restricts evidence to the current hits while retaining source memory IDs and raw recall entries so the answer remains reviewable.*
-
-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.
-
-[![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)
-
-### Write: Separate Semantic Judgment from System Guarantees
-
-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.
-
-The plugin separates semantic judgment from system guarantees:
-
-| LLM / worker responsibility | Hard Host guarantee |
+| Memory worker | Host guarantees |
 |---|---|
-| 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
-
-The conversation's “Memory System” tab 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:
-
-| Page | Primary purpose |
-|---|---|
-| 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/roadmap.md

@@ -11,7 +11,6 @@ The Roadmap records work beyond the current implementation; it is not a commitme
 - [ ] **Backoff, circuit breaking, and manual retry**: apply bounded backoff after consecutive failures, show the reason on the Status page, and allow explicit recovery.
 - [ ] **Deterministic sensitive-data defenses**: add secret/credential pattern detection, size limits, and audit receipts beyond LLM admission.
 - [ ] **Automated real-WebUI E2E**: isolate DSH_HOME, storageRoot, workspace, and the port; cover light tasks, score-based review, cancellation, and failures without partial writes.
-- [ ] **Correct `tabEnabled` semantics**: have the Host and client use the same switch so the complete Tab capability is actually registered or removed.
 - [ ] **Correct cold-reference paths**: under every storage scope, write resolvable references that match the actual managed path.
 
 ## P1: Long-Term Maintenance and Data Operations
@@ -27,6 +26,7 @@ The Roadmap records work beyond the current implementation; it is not a commitme
 ## P2: Observability, Experience, and Release Engineering
 
 - [ ] **Background-review history**: show recent scores, checkpoints, waiting/running/failed states, worker receipts, and resulting changes.
+- [ ] **Switch to DSH's shared directory picker** (blocked on [dsh-external/issues#603](https://github.com/dsh-external/issues/issues/603)): custom storage temporarily uses a manually entered Host path because remote `browse` deployments cannot invoke the `native` picker; once DSH exposes a reusable directory-picker service for plugins, move to the provider-selected native / browse flow and retain manual entry only as a fallback if needed.
 - [ ] **Complete internationalization**: cover commands, tool cards, Host errors, compatibility default metadata, and confirmation copy.
 - [ ] **Multi-Memory-Space E2E**: cover automatic space creation, cross-space recall, one-pass migration routing, multiple relationship types, merge, and controlled forget.
 - [ ] **Capacity and fault injection**: exercise real USER/MEMORY boundaries, Document LRU, revision conflicts, CLI timeouts, and mid-operation Host restarts.

package/docs/en/storage-model.md

@@ -50,7 +50,7 @@ follow an exact cold reference when full text is required
 +-- state/                         # reserved; no persistent reviewer yet
 ```
 
-`storageScope` determines the entire root, not just the Mnemon databases. `state/` is currently recognized only by the status inspector; scored review watermarks remain in the running Host's memory.
+`storageScope` determines the entire root, not just the Mnemon databases. The `workspace` scope resolves an independent `<workspace>/.mnemon` for every registered DSH workspace. The Web inspection target and current-session execution target are independent; only the latter drives agents, tools, and lifecycle hooks. `state/` is currently recognized only by the status inspector; scored review watermarks remain in the running Host's memory.
 
 ## Runtime Memory
 

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)