dsh-mnemon 0.1.4 → 0.1.6

package/docs/en/getting-started.md

@@ -1,155 +0,0 @@
-# Getting Started
-
-[简体中文](../zh-CN/getting-started.md) | **English** | [Documentation hub](./README.md)
-
-This guide goes from a blank environment to the first verified recall. It uses Sidebar and global storage by default. If installation is complete, jump to [First verification](#6-complete-first-verification).
-
-## 1. Prerequisites
-
-You need:
-
-- a DSH Web profile that starts successfully;
-- a locally executable `mnemon` CLI;
-- a DSH subagent provider for isolated memory tasks.
-
-Regular semantic work prefers a provider named `spawn` with `outputSchema`, `toolFilter`, `persona`, and `depthLimit`. Optional score-based background review additionally requires a provider named `fork` with `inheritsParentContext=true`. Missing `fork` does not block deterministic pages or regular manual actions.
-
-The project does not declare a fixed minimum DSH / Mnemon matrix. This guide and its screenshots target dsh-mnemon v0.1.4. Back up and repeat this verification against an isolated root before upgrading.
-
-## 2. Install Mnemon
-
-Homebrew Cask is recommended on macOS:
-
-```sh
-brew install --cask mnemon-dev/tap/mnemon
-```
-
-On macOS or Linux, Go is another option:
-
-```sh
-go install github.com/mnemon-dev/mnemon@latest
-```
-
-Verify the binary:
-
-```sh
-mnemon --version
-```
-
-If DSH cannot find it on `PATH`, set `MNEMON_CLI_PATH` or configure an absolute `mnemon.cliPath`. `mnemon status` opens the effective Store and may initialize data or run upstream migrations, so it is not a side-effect-free installation probe.
-
-## 3. Install dsh-mnemon
-
-Install into the Web profile:
-
-```sh
-dsh plugin --profile web add dsh-mnemon
-```
-
-Use an absolute path for a development checkout:
-
-```sh
-dsh plugin --profile web add "link:/absolute/path/to/dsh-mnemon"
-```
-
-Then start or restart the profile:
-
-```sh
-dsh --profile web
-```
-
-Upgrade and uninstall:
-
-```sh
-dsh plugin --profile web update dsh-mnemon
-dsh plugin --profile web remove dsh-mnemon
-```
-
-Uninstall removes the plugin registration, not memory data in global, workspace, or custom roots.
-
-## 4. Choose entry point and storage
-
-Open **Settings → Memory System**:
-
-[![Memory System settings for display, storage, conversation UI, and backup](../assets/screenshots/settings-memory-system.png)](../assets/screenshots/settings-memory-system.png)
-
-### Display mode
-
-- **Sidebar** (default): a dedicated workbench opened from the DSH sidebar; recommended for most users.
-- **Buildin**: the original conversation-area tab with its established visuals.
-
-### Storage location
-
-| Scope | Root | Best suited for |
-|---|---|---|
-| **Global** (default) | `MNEMON_DATA_DIR` or `~/.mnemon` | Sharing one memory set across workspaces |
-| **Workspace** | `<workspace>/.mnemon` | Project isolation with cross-workspace inspection in the workbench |
-| **Custom** | `dataDir` | A dedicated disk, mounted volume, or explicit directory |
-
-Save initializes a candidate runtime graph before atomically switching the Host. The page clears stale state and reloads automatically—no browser refresh is needed. Changing scope never migrates, merges, or deletes old data.
-
-In Workspace mode, the workbench selector changes only what data is being inspected. Agents, tools, and lifecycle hooks always use the current conversation's effective root. The header reports a mismatch and offers one-click alignment.
-
-## 5. Open the Sidebar workbench
-
-Click **Memory System** in the sidebar, then start on **Status**:
-
-[![Status with CLI, versions, Runtime, Memory Spaces, Documents, and storage root](../assets/screenshots/status-overview.png)](../assets/screenshots/status-overview.png)
-
-Confirm that:
-
-- the top right says Connected;
-- Mnemon and dsh-mnemon show installed versions;
-- the storage root matches your chosen scope;
-- Runtime, Memory Spaces, and Documents report no errors.
-
-If Mnemon is unavailable, run `command -v mnemon` and `mnemon --version`. See [Troubleshooting](./operations.md#troubleshooting) for other symptoms.
-
-## 6. Complete first verification
-
-### Create a Memory Space
-
-1. Open **Memory Spaces → Overview**.
-2. Select **Create Memory Space**.
-3. Use a narrow name such as “Project Decisions.”
-4. Describe what belongs there and which tasks should recall it.
-5. Enable read activation.
-
-### Remember one test item
-
-Open **Remember** and enter something stable, self-contained, future-useful, and secret-free. Leave advanced options collapsed so the memory subagent can select a target, deduplicate, and distill.
-
-Writing starts only after confirmation. Canceling the dialog changes no state.
-
-### Verify recall
-
-1. Open **Memory Spaces → Recall**.
-2. Ask a concrete question that should match the item.
-3. Use **Direct recall** first to inspect raw evidence.
-4. Confirm the result retains its Memory Space, category, importance, score, and ID.
-
-You can also use conversation commands:
-
-```text
-/mnemon status
-/mnemon recall <focused query>
-```
-
-## 7. Verify memory inside a conversation
-
-Ask a question that genuinely depends on history and allow the Agent to decide whether recall helps. After completion:
-
-- Turn memory appears below the reply if the turn used memory tools.
-- Expanding shows exact tools and links to their pages.
-- Save to memory opens an editable confirmation; canceling performs no write.
-
-[![Turn memory and exact tool navigation](../assets/screenshots/conversation-turn-memory.png)](../assets/screenshots/conversation-turn-memory.png)
-
-Ordinary conversation should not force recall. Current requests, repository files, and live tool results outrank historical content.
-
-## 8. Next steps
-
-- Use the [Sidebar and conversation UI guide](./ui-guide.md) to learn every page.
-- Use the [storage model](./storage-model.md) to choose Runtime, Documents, or Memory Spaces.
-- Use the [configuration reference](./configuration.md) for Workspace scope, read-only behavior, and lifecycle switches.
-- Use the [operations guide](./operations.md) to export your first ZIP backup and establish a pre-upgrade checklist.

package/docs/en/interfaces.md

@@ -1,181 +0,0 @@
-# WebUI, Tools, Commands, and RPC
-
-[简体中文](../zh-CN/interfaces.md) | **English** | [Documentation hub](./README.md)
-
-This page is an integration reference. For daily use, start with the [Sidebar and conversation UI guide](./ui-guide.md).
-
-## User-facing entry points
-
-| Entry | Default | Description |
-|---|---:|---|
-| Sidebar | Yes | Dedicated Memory System workbench with Status, Runtime, Memory Spaces, and Documents |
-| Buildin | No | Original `conversation.view` tab with established visuals |
-| Turn memory | Yes | Memory-tool summary for a completed turn, with exact page links |
-| Save to memory | Yes | Action beside finalized assistant replies; confirmation invokes supervised writing |
-| `/mnemon` | — | Conversation command entry |
-| Model tools | — | Structured Root Agent read/write entry |
-
-Sidebar and Buildin are live, mutually exclusive mounts that share functionality, data, and Host services. The two conversation entries can be disabled independently through `mnemon-ui` settings.
-
-## Model tools
-
-### Read-only tools
-
-| Tool | Purpose | Root Agent path |
-|---|---|---|
-| `mnemon_status` | Aggregated CLI, configuration, storage, and directory status | Direct service |
-| `mnemon_memory_bodies` | Read Memory Space directory and statistics | Direct service |
-| `mnemon_recall` | Recall from one or more active spaces | `spawn` recall worker |
-| `mnemon_related` | Traverse from a known ID | `spawn` related worker; Root defaults to two hops |
-| `mnemon_document_search` | Deterministically search managed Documents | Documents control layer |
-
-“Read only” means managed bodies and durable semantics do not change. `mnemon_document_search` still updates `lastAccessedAt` for LRU ordering, so feature read-only is not disk read-only.
-
-### Tools available with `writeEnabled=true`
-
-| Tool | Purpose | Root Agent path |
-|---|---|---|
-| `mnemon_runtime_memory` | `add` / `replace` / `remove` hot memory | Deterministic control; add overflow may start a worker |
-| `mnemon_document_manage` | Create, update, or archive a Document | Create/update deterministic; archive uses a worker |
-| `mnemon_remember` | Retain one durable insight | `spawn` write worker |
-| `mnemon_link` | Create a typed relationship | `spawn` write worker |
-| `mnemon_forget` | Soft-delete an exact ID | `spawn` write worker |
-| `mnemon_memory_body_create` | Create an independent Memory Space | `spawn` write worker |
-| `mnemon_memory_body_update` | Update name, description, or active state | `spawn` write worker |
-| `mnemon_memory_body_merge` | Non-destructive import merge | `spawn` write worker |
-
-When a worker invokes the same tool name, it reaches the service directly and is not delegated recursively.
-
-## Tool admission
-
-- **Runtime**: explicit preferences, stable project conventions, environment facts, and high-frequency lessons.
-- **Documents**: designs, investigations, procedures, postmortems, or handoffs with complete structure and rationale.
-- **Memory Spaces**: stable facts, decisions, and insights that must survive across tasks or benefit from graph relationships.
-- **Skip**: questions, guesses, temporary progress, completion logs, raw output, secrets, and ordinary repository facts that are easy to rediscover.
-
-`mnemon_forget` is a destructive semantic action. Use it only on explicit request or after confirming that content is wrong or obsolete.
-
-## `/mnemon` commands
-
-```text
-/mnemon
-/mnemon status
-/mnemon recall <query>
-/mnemon related <full memory ID>
-/mnemon remember <content>
-/mnemon forget <exact ID>
-```
-
-- Empty `/mnemon` equals `status`.
-- `status` is deterministic and starts no model.
-- `recall`, `related`, `remember`, and `forget` use the live Agent containing the command as worker parent.
-- Command recall returns at most 10 results.
-- `forget` requires one exact ID without spaces.
-
-## In-conversation contracts
-
-| DSH slot | Registration | Behavior |
-|---|---|---|
-| `conversation.chat.turnTail` | chain | `turn-activity` summarizes `mnemon_*` calls from completed turns; open turns and turns without activity render nothing |
-| `conversation.chat.assistant-actions` | list, `id=mnemon-save` | `assistant-message` reads finalized text; `supervise` runs only after confirmation |
-
-Both are additive and replace no official DSH rendering. The assistant-message candidate is editable and long replies are bounded by the UI preview limit. Persistence is complete only after a memory-subagent receipt.
-
-## Workspace routing
-
-Workbench requests carry `sessionId` and an optional `workspaceId`. The Host accepts only IDs registered in `workspaceRegistry`:
-
-- deterministic reads and manual maintenance may route to the inspected root selected by `workspaceId`;
-- Agents, tools, commands, and lifecycle hooks still route by the Agent cwd associated with `sessionId`;
-- `status.workspaceContext` returns selected / effective roots and `aligned`;
-- Agent-backed operations are rejected while misaligned.
-
-## RPC channels
-
-RPC is an internal Host-to-client bridge, not a stable external HTTP API.
-
-### Read channel
-
-```text
-channel:   /dsh-mnemon-read
-authority: trusted-host
-```
-
-| Endpoint | Behavior |
-|---|---|
-| `status` | Aggregated service, version, lifecycle, Documents, and workspace/storage context |
-| `versions` | Check installed/latest Mnemon and dsh-mnemon versions and installation sources |
-| `runtime-memory` | Runtime snapshot |
-| `documents` / `document` / `document-search` | Directory, body, and deterministic search |
-| `graph` / `bodies` | Active multi-space graph and Memory Space directory |
-| `list` / `entities` | Durable content list and entity aggregation |
-| `search` / `agent-search` / `related` | Direct retrieval, evidence answer, and relation traversal |
-| `turn-activities` / `turn-activity` | Session-wide or single-turn memory-tool activity |
-| `assistant-message` | Finalized assistant text by messageId |
-
-### Write channel
-
-```text
-channel:   /dsh-mnemon-write
-authority: loopback
-```
-
-| Endpoint | Behavior |
-|---|---|
-| `runtime-memory` | Hot-memory mutation |
-| `supervise` | Submit a candidate to the memory worker |
-| `document` | create / update / archive |
-| `remember` / `link` / `forget` | Durable semantic write, relation, and soft deletion |
-| `body-create` / `body-update` / `body-delete` | Create, edit, or physically delete a confirmed Memory Space |
-| `version-update` | Update a named component with Host-fixed commands and arguments |
-
-With `writeEnabled=false`, the channel remains registered but mutations are rejected at the Host boundary.
-
-### Backup channel
-
-```text
-channel:   /dsh-mnemon-pack
-authority: loopback
-```
-
-| Endpoint | Behavior |
-|---|---|
-| `target` | Effective root and scope |
-| `export` | Export a complete ZIP with manifest and SHA-256 checksums |
-| `inspect` | Parse and verify an import ZIP, returning component and occupancy preview |
-| `import` | Safely merge into the effective root; rejected in read-only mode |
-
-Backups contain private memory, so the entire channel is loopback-only.
-
-### Settings channel
-
-```text
-channel:   /dsh-mnemon-settings
-authority: loopback
-namespaces: mnemon, mnemon-ui
-endpoints: get, mutate
-```
-
-Mutations use settings revisions to prevent overwriting concurrent edits. `mnemon` owns Host/storage settings; `mnemon-ui` owns `turnBar` and `saveAction`.
-
-## npm exports
-
-The root package exposes Host composition and core classes:
-
-```text
-apply
-Config / resolveConfig
-createRunner
-MnemonService
-RuntimeMemoryController
-DocumentManager
-StorageScopeInspector
-MnemonSubagentCoordinator
-MnemonLifecycle
-```
-
-`dsh-mnemon/client` exports `apply` and `inject` for the DSH client bundle. Client implementation classes and RPC endpoints are internal and should not be treated as a stable public SDK.
-
-## Internationalization
-
-The main Sidebar / Buildin workbench, settings, and conversation entries support Chinese and English and follow DSH locale live. Brand names, tool names, and configuration keys are not translated. `/mnemon` commands, model-tool cards, some Host errors, and compatibility metadata remain partially untranslated.

package/docs/en/operations.md

@@ -1,166 +0,0 @@
-# Operations, Security, and Troubleshooting
-
-[简体中文](../zh-CN/operations.md) | **English** | [Documentation hub](./README.md)
-
-## Health checks
-
-Check the binary, then open **Status** in the workbench:
-
-```sh
-command -v mnemon
-mnemon --version
-```
-
-```text
-/mnemon status
-```
-
-[![Status with component versions, three-tier data, and effective directories](../assets/screenshots/status-overview.png)](../assets/screenshots/status-overview.png)
-
-Status shows Mnemon / dsh-mnemon versions, Runtime, Memory Spaces, Documents, and effective directories. `mnemon status` opens the effective Store and may initialize data or run upstream migrations, so it is not a completely side-effect-free probe.
-
-## Version checks and updates
-
-**Check versions** on Status opens the version panel:
-
-[![Check and update Mnemon CLI and dsh-mnemon](../assets/screenshots/version-check.png)](../assets/screenshots/version-check.png)
-
-- **Mnemon CLI**: installed from `mnemon --version`; latest from Mnemon GitHub Releases.
-- **dsh-mnemon**: installed from the running package; latest from the npm registry.
-
-Checking is read-only and never installs automatically. Update appears only when a newer version exists and the source is safely recognized. Mnemon supports Homebrew Cask / Formula and `go install`; dsh-mnemon supports npm installations managed by pnpm in the owning DSH Profile. `link:` / `file:` development builds and unrecognized manual installs show guidance only.
-
-The Host fixes update commands and arguments. The browser cannot supply either; shell is disabled and execution/output are bounded. After an update, the UI rechecks both components and refreshes Status automatically. Mnemon applies on the next CLI call. Restart `dsh web` after updating dsh-mnemon.
-
-## Backup and recovery
-
-### Recommended: Settings ZIP
-
-**Settings → Memory System → Backup and migration** operates on the **currently effective root**:
-
-- **Export ZIP** includes Runtime, Documents, and every Memory Space.
-- **Import ZIP** previews, validates, then merges into the effective root.
-- Packs include `manifest.json`, SHA-256 inventory, and component summaries.
-- Export/import hold component locks; a Memory Space with an uncheckpointed WAL is rejected.
-- Import checks paths, counts, compressed/expanded limits, JSON schemas, Document hashes, registry consistency, and SQLite headers.
-- Merge is staged before replacing component directories; commit failure restores pre-import directories.
-
-The UI offers safe merge, not “overwrite everything”:
-
-- Runtime deduplicates by target and content.
-- Identical Document ID + hash is skipped; conflicting content receives a new ID.
-- Identical Memory Space ID + database is skipped; conflicting content receives a new ID.
-
-Import is governed by `writeEnabled` and is rejected in read-only deployments. A ZIP contains private memory—encrypt it, restrict access, and rehearse recovery.
-
-### Recovery rehearsal
-
-1. Select an isolated `custom` directory and save.
-2. Confirm **Current directory ZIP** points to that root.
-3. Select the backup, review its preview, then import.
-4. Check Runtime, Documents, Memory Spaces, and directories on Status.
-5. Run one focused direct recall and read one Document.
-6. Only after verification decide whether to switch a production scope.
-
-Never restore directly into the only production root without another backup.
-
-### Filesystem snapshot
-
-To preserve reserved `state` or take an offline complete snapshot, stop every DSH / Mnemon process using the root and copy:
-
-```text
-<storageRoot>/runtime
-<storageRoot>/documents
-<storageRoot>/data
-<storageRoot>/state    # when present; outside the built-in Pack's three data components
-```
-
-Generate an inventory or checksums and rehearse recovery in isolation. A normal directory copy while writers are running is not a consistent snapshot.
-
-## Changing storage scope
-
-Saving `global` / `workspace` / `custom` initializes a new runtime graph before switching atomically. The page reloads automatically, but **data is not migrated**:
-
-```text
-old scope -- save --> new empty or existing root
-
-no automatic copy
-no automatic merge
-no automatic delete
-```
-
-Recommended migration: export from the old scope → switch and confirm the new root → import → verify. In Workspace mode, confirm both inspection and execution targets.
-
-## Security boundaries
-
-### Process
-
-- CLI uses `spawn(command, args, { shell: false })`.
-- stdout + stderr are capped at 2 MiB by default.
-- Calls use `timeoutMs` and AbortSignal; cancellation sends `SIGTERM`, then `SIGKILL` after 1.5 seconds.
-- One Runner serializes calls; separate DSH processes still rely on Mnemon / SQLite concurrency.
-
-### Files
-
-- Runtime, Documents, and Pack operations use in-process queues or component locks.
-- Lock wait defaults to 5 seconds; stale threshold is 30 seconds.
-- Writes use temporary files, staging, and rename.
-- Runtime revisions block stale compaction; Document revisions block movement of updated originals.
-- `sourcePaths` cannot escape the initiating workspace or point into managed Documents.
-
-### Web and model
-
-- Read RPC is `trusted-host`; write, settings, and backup RPC are `loopback`.
-- The WebUI neither reads SQLite directly, starts processes, nor supplies arbitrary update commands.
-- Workers use persona, tool allowlists, structured output, and `maxDepth: 1`.
-- Queries, candidates, Document bodies, and historical memory are treated as untrusted data.
-
-These boundaries are not a secret scanner. There is no deterministic credential detection; never submit keys, tokens, private keys, or raw sensitive logs.
-
-### Security reporting
-
-Report vulnerabilities privately through [SECURITY.md](../../SECURITY.md), not a public issue. Data loss, path traversal, lock/revision bypasses, subagent-isolation breaks, and injection through rendered memory are in scope.
-
-## Troubleshooting
-
-| Symptom | Check and resolution |
-|---|---|
-| Mnemon unavailable | Run `command -v mnemon`, `mnemon --version`; set `MNEMON_CLI_PATH` or `cliPath`, then restart |
-| Memory System missing from sidebar | Check `tabEnabled=true`, `displayMode=sidebar`; Buildin is in the conversation area; for a local link run `pnpm run build`, then restart |
-| Status healthy but recall empty | Check active spaces, storage scope, inspected root, effective session root, and query focus |
-| Header reports misalignment | The workbench is inspecting another workspace; align or keep deliberate read-only inspection; Agent-backed actions are rejected |
-| Saved settings appear unchanged | Inspect the save error; success applies live and reloads automatically without refresh |
-| Custom directory rejected | Use an absolute path, `~`, or `~/...` |
-| `memoryBodyId is required...` | Active count is not exactly one; select a target explicitly |
-| `memory body is not active for reading` | Activate it in Overview; inactive writes are allowed, reads are not |
-| Provider error | Semantic work needs full isolation capabilities; background review additionally needs `fork + inheritsParentContext` |
-| Runtime replace exceeds capacity | Shorten it or organize first; automatic maintenance handles add overflow only |
-| Document source path rejected | Keep it inside the session workspace and outside managed Documents |
-| CLI timeout | Increase `timeoutMs`; large Stores may need more than 10 seconds for status or graph |
-| Lock timeout | Check other writers; never delete a lock owned by a live process |
-| ZIP export reports WAL busy | Wait for Memory Space writes to settle; do not bypass the uncheckpointed-WAL guard |
-| ZIP import checksum/schema failure | The backup is damaged or incompatible; preserve the current root and never unzip over it manually |
-| No Update button | Already current, remote check failed, or the source is link/manual; follow panel guidance |
-| Remote page reads but cannot write | Write, settings, and backup RPC enforce loopback by design |
-
-## Known limitations
-
-### Feature read-only is not disk read-only
-
-`writeEnabled=false` disables semantic mutation and Pack import, but startup may initialize/repair Runtime, Document search updates `lastAccessedAt`, and Mnemon reads may migrate a database.
-
-### Shared Documents scope
-
-`global` and `custom` can share one Document index across workspaces; records have no independent workspace-ownership field. `sourcePaths` are checked against the initiating cwd only when written.
-
-### Cross-system transactions
-
-Cold-index-first protects active content but is not a rollback-capable distributed transaction across Mnemon SQLite and the filesystem. A revision conflict after indexing may leave a duplicate reference; the system preserves data.
-
-### Background watermark
-
-Activity score, latest checkpoint, and retry state are not persisted. Host restart clears unprocessed activity. Failure backoff, circuit breaking, and manual retry are not implemented yet.
-
-### Versions and internationalization
-
-There is no formal fixed DSH / Mnemon support matrix. The main Web interface is bilingual, while commands, tool cards, compatibility metadata, and some errors remain partially untranslated.

package/docs/en/project-overview.md

@@ -1,145 +0,0 @@
-# Project Overview: Local Three-Tier and Cross-Agent Memory for DSH
-
-[简体中文](../zh-CN/project-overview.md) | **English** | [Documentation hub](./README.md)
-
-`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.
-
-Its goal is not to store more text. It balances long-term continuity, current-fact priority, context cost, and recoverable writes.
-
-[![Memory Space overview with catalog, activation boundary, and multi-space graph](../assets/screenshots/overview-memory-graph.png)](../assets/screenshots/overview-memory-graph.png)
-
-## Why three tiers
-
-One memory tier cannot serve frequent injection, full-document reading, and cross-session recall equally well:
-
-| Need | With one memory tier | dsh-mnemon's choice |
-|---|---|---|
-| 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 |
-
-Priority always remains: **current user instructions → live tools and repository facts → historical memory**.
-
-## The three-tier model
-
-### 1. Runtime Memory
-
-Runtime retains compact, high-frequency information useful on many turns:
-
-- `USER.md`: identity, roles, preferences, habits, and explicit collaboration requirements;
-- `MEMORY.md`: project conventions, environment facts, decisions, tool behavior, and reusable lessons.
-
-`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.
-
-### 2. Project Documents
-
-Documents preserve complete designs, investigations, procedures, postmortems, and handoffs. Title, retrieval description, and body participate in deterministic search; the body keeps Markdown structure.
-
-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.
-
-### 3. Memory Spaces
-
-Each Memory Space maps to an independent Mnemon Store and `mnemon.db`, with a stable ID, name, routing description, and activation state.
-
-- 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 model](./storage-model.md) for authoritative files, capacities, and directories.
-
-## Cross-agent sharing boundary
-
-“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:
-
-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.
-
-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.
-
-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.
-
-## Architecture
-
-[![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)
-
-Four boundaries shape the system:
-
-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.
-
-### Memory System flow
-
-This diagram describes stable execution boundaries, not a live status dashboard. Solid lines are deterministic Host paths; dashed lines require supervised LLM judgment.
-
-[![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 three major flows are:
-
-- **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.
-
-See [Lifecycle and workflows](./workflows.md) for thresholds, cancellation, and failure semantics.
-
-## Read path: near to far
-
-A history-dependent request expands in this order:
-
-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.
-
-`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.
-
-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.
-
-## Write path: semantics versus guarantees
-
-| Memory worker | Host guarantees |
-|---|---|
-| 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 |
-
-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.
-
-## What users see
-
-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.
-
-Two additive entries surface memory in conversations:
-
-- **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.
-
-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.
-
-## Local-first reliability
-
-- 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.
-
-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
-
-- [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.