dsh-mnemon 0.1.2 → 0.1.4

package/docs/en/project-overview.md

@@ -1,249 +1,145 @@
-# Project Overview: Local Three-Tier Memory for DSH
+# Project Overview: Local Three-Tier and Cross-Agent 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. Because the durable tier uses native Mnemon Stores, DSH can reuse the same local long-term memory with other Mnemon-enabled agents.
 
-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.
+Runtime retains compact, high-frequency information useful on many turns:
 
-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 |
+- `USER.md`: identity, roles, preferences, habits, and explicit collaboration requirements;
+- `MEMORY.md`: project conventions, environment facts, decisions, tool behavior, and reusable lessons.
 
-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.
+`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.
 
-## The Three-Tier Memory Model
+### 2. Project Documents
 
-### 1. Runtime Memory: Hot Context Visible Every Turn
+Documents preserve complete designs, investigations, procedures, postmortems, and handoffs. Title, retrieval description, and body participate in deterministic search; the body keeps Markdown structure.
 
-Runtime Memory contains compact, frequently used stable information:
+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.
 
-- `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.
+### 3. Memory Spaces
 
-`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.
+Each Memory Space maps to an independent Mnemon Store and `mnemon.db`, with a stable ID, name, routing description, and activation state.
 
-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.
+- 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.
 
-[![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)
+See [Storage and the three-tier model](./storage-model.md) for authoritative files, capacities, and directories.
 
-*The Runtime page places the USER and MEMORY projections side by side with their capacity, importance, categories, and per-entry edit controls.*
+## Cross-agent sharing boundary
 
-### 2. Project Documents: Complete, Readable Project Knowledge
+“Sharing” does not mean that dsh-mnemon broadcasts conversations or files to arbitrary agents. It means that multiple Mnemon-enabled agents use the same local Mnemon data:
 
-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.
+1. every participant installs and integrates Mnemon;
+2. every participant can access the same `storageRoot`;
+3. durable memories intended for sharing live in Mnemon Stores recognized by those participants.
 
-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.
+Under those conditions, another Mnemon-enabled agent can recall durable facts, entities, and relations written through DSH, and DSH can discover compatible memories written in the other direction. This boundary covers Mnemon Memory Spaces only. `runtime/` and `documents/` are DSH layers managed by dsh-mnemon and do not automatically become another agent's context merely because the root is shared.
 
-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.
+The default `global` root, `~/.mnemon`, is the simplest choice for several local agents. Use `custom` for an explicitly agreed shared root, or `workspace` to constrain sharing to one project. Concurrent processes rely on Mnemon and SQLite concurrency semantics; stop every user before offline copying, migration, or direct database changes.
 
-[![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)
+## Architecture
 
-*The Documents page preserves both metadata and Markdown structure, combining list selection, search, and complete reading in one view.*
+[![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)
 
-### 3. Memory Spaces: Isolated Long-Term Recall
+Four boundaries shape the system:
 
-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.
+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.
 
-- 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.
+### Memory System flow
 
-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.
+This diagram describes stable execution boundaries, not a live status dashboard. Solid lines are deterministic Host paths; dashed lines require supervised LLM judgment.
 
-See [Storage and the Three-Tier Memory Model](./storage-model.md) for directory layouts, capacity details, and data authorities.
+[![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)
 
-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.
+The three major flows are:
 
-## From the Current Request to Durable Retention
+- **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.
 
-### Read: Start Near and Escalate Only When Needed
+See [Lifecycle and workflows](./workflows.md) for thresholds, cancellation, and failure semantics.
 
-The plugin follows a near-to-far lookup gradient:
+## Read path: near to far
 
-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.
+A history-dependent request expands in this order:
 
-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.
+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.
 
-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.
+`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.
 
-[![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)
+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.
 
-*Agent search restricts evidence to the current hits while retaining source memory IDs and raw recall entries so the answer remains reviewable.*
+## Write path: semantics versus guarantees
 
-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 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:
-
-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 |
-|---|---|
-| 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/storage-model.md

@@ -164,6 +164,12 @@ mnemon.db     independent data plane
 - Merge imports source content into the target through Mnemon; the source database remains in place, and by default only the source is marked inactive.
 - `forget` is a soft delete by exact ID, not deletion of a database file.
 
+### Cross-Agent Visibility
+
+`mnemon.db` is Mnemon's native data plane, not a private dsh-mnemon format. Another Mnemon-enabled agent can access the same durable memory when it uses the same `storageRoot` and Store. dsh-mnemon also discovers compatible Stores already present on disk; DSH-specific names, descriptions, and activation state remain managed by `.dsh-memory-bodies.json`.
+
+This sharing does not extend to `runtime/` or `documents/`. Even when those directories sit under the same root, another agent must implement their DSH-specific protocols to understand them. “Shared Mnemon memory” must not be presented as automatic sharing of the complete DSH context.
+
 ## Four Relationship Types
 
 The Mnemon long-term layer preserves `temporal`, `semantic`, `causal`, and `entity` relationships. The plugin does not require relationships to be created manually for every memory; they should be created only when they genuinely improve future recall. Overview can aggregate memories, entities, relationships, and space membership across multiple active Memory Spaces.

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.4 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)