dsh-mnemon 0.1.5 → 0.1.6

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.

package/docs/en/roadmap.md

@@ -1,41 +0,0 @@
-# Roadmap
-
-[简体中文](../zh-CN/roadmap.md) | **English** | [Documentation Center](./README.md)
-
-The Roadmap records work beyond the current implementation; it is not a commitment to deliver these capabilities. Data safety, recoverability, and verifiability take priority.
-
-## P0: Reliability and Recoverable Scheduling
-
-- [ ] **Persist background-review watermarks**: save activity signals, the latest processed checkpoint, scoring version, and run state by root session; restore unprocessed activity after restart or resume.
-- [ ] **Idempotent checkpoints**: assign a stable identifier to each review input to prevent timeouts, retries, or duplicate hooks from producing duplicate Documents.
-- [ ] **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 cold-reference paths**: under every storage scope, write resolvable references that match the actual managed path.
-
-## P1: Long-Term Maintenance and Data Operations
-
-- [ ] **Long-term organization across sessions**: trigger an independent organization process based on time and the number of new sessions instead of reusing per-turn review.
-- [ ] **Mnemon GC / forget review**: generate candidates for decay, conflicts, obsolete content, and orphaned relationships, then present evidence before deletion.
-- [ ] **Consistent backup and recovery**: provide unified snapshots, checksums, and recovery rehearsals for the registry, multiple databases, Runtime, and Documents.
-- [ ] **Repair and rebuild tools**: detect damaged JSON, missing projections, orphaned Documents, missing databases, and registry/disk inconsistencies.
-- [ ] **Schema migration**: add explicit upgrade and rollback strategies for Runtime, the Documents index, and the Memory Space registry.
-- [ ] **Compatibility matrix**: document and automatically test supported combinations of DSH, the Mnemon CLI, Node, and data formats.
-- [ ] **Explicit Documents workspace ownership**: record the source workspace under shared storage scopes or provide a configurable isolation strategy.
-
-## 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.
-- [ ] **Documentation consistency checks**: add relative links, external links, bilingual file mirroring, configuration-key matching, and code-block matching to CI.
-- [ ] **Release completion**: establish stable versions, a changelog, upgrade/uninstall/data-retention guides, artifact checksums, and a minimum-support policy.
-
-## Explicitly Out of Scope
-
-- A Runtime `daily` target; only `user` and `memory` are currently maintained.
-- A proactive notification daemon without explicit delivery semantics; Mnemon remains an on-demand pull system.
-- Declaring internal RPC or `MnemonClient` to be a stable public SDK.
-- Automatically deleting the source Memory Space database; merge currently preserves the source files.

package/docs/en/storage-model.md

@@ -1,185 +0,0 @@
-# Storage and the Three-Layer Memory Model
-
-[简体中文](../zh-CN/storage-model.md) | **English** | [Documentation Center](./README.md)
-
-## Why Three Layers
-
-No single storage form can simultaneously be visible on every turn, preserve complete narratives, and support long-term graph-enhanced recall:
-
-| Question | Corresponding layer | Reason |
-|---|---|---|
-| What must be known directly on the next turn? | Runtime Memory | Tiny and injected directly into the prompt |
-| Which design or procedure needs to be read quickly and in full? | active Documents | Preserves Markdown structure without deep recall |
-| Which historical facts and relationships should persist across sessions? | Memory Spaces | Independent databases, graph relationships, and on-demand recall |
-| What happens when a long document is rarely used but must remain traceable? | archived Documents | Mnemon retains an index while the cold layer retains the original text |
-
-Recommended query gradient:
-
-```text
-current request and repository facts
-             |
-             v
-Runtime Memory already in prompt
-             |
-             v
-search active Documents
-             |
-             v
-recall active Memory Spaces
-             |
-             v
-follow an exact cold reference when full text is required
-```
-
-## Unified Root Directory
-
-```text
-<storageRoot>/
-+-- runtime/
-|   +-- memories.json
-|   +-- USER.md
-|   +-- MEMORY.md
-+-- documents/
-|   +-- index.json
-|   +-- active/
-|   +-- archived/
-+-- data/
-|   +-- .dsh-memory-bodies.json
-|   +-- <memory-space-id>/
-|       +-- mnemon.db
-+-- state/                         # reserved; no persistent reviewer yet
-```
-
-`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
-
-### Semantics
-
-- `target=user`: identity, role, long-term preferences, habits, communication style, and explicit collaboration requirements.
-- `target=memory`: projects, environment, decisions, conventions, tool characteristics, and reusable experience.
-- `importance=critical|normal|low`: retention priority during maintenance.
-
-There is currently no `daily` target.
-
-### Source of Truth and Projections
-
-`runtime/memories.json` is the sole source of truth. Each record contains:
-
-```text
-content
-created_at
-updated_at
-target
-importance
-```
-
-`USER.md` and `MEMORY.md` are deterministic derived files. Each item is normalized to one line, and items are separated by a line containing only `§`; `§` is a reserved character. During startup and prompt assembly, the control layer repairs missing or manually modified projections from the JSON source.
-
-### Operations
-
-- `add` writes an independent new fact; exactly identical content is not added twice.
-- `replace` uses a unique substring match on `old_text` to locate and replace an entire item.
-- `remove` uses a unique substring to remove an entire item.
-- Zero or multiple matches are rejected; no fuzzy mutation is performed.
-
-### Capacity
-
-| Target | Limit | Maintenance method |
-|---|---:|---|
-| `USER.md` | 4 KiB | A local no-tool worker merges conservatively; content never enters a Memory Space |
-| `MEMORY.md` | 10 KiB | A worker archives committed content first, then returns compaction candidates |
-
-Capacity is measured from the actual UTF-8 bytes of the projection body. A single item is limited to 8 KiB. Automatic capacity maintenance is triggered only by an overflowing `add`; an overflowing `replace` fails directly, and the caller should perform explicit maintenance first.
-
-## Project Documents
-
-### Purpose
-
-Documents preserve project knowledge that is more complete than a single memory item but should still be quick to read, such as:
-
-- architecture designs and rationale;
-- evidence-backed investigation findings;
-- operating procedures, release checklists, and incident reviews;
-- implementation handoffs and long-term maintenance notes.
-
-User profiles, ordinary conversation, temporary progress, raw large logs, and secrets should not be stored in Documents.
-
-### Control Plane
-
-`documents/index.json` is the metadata source of truth. It manages IDs, titles, descriptions, status, filenames, source paths, sessions, timestamps, revisions, SHA-256 values, sizes, and Memory Space references. Managed Markdown copies include generated frontmatter.
-
-`sourcePaths`:
-
-- may point only inside the current session workspace;
-- are source references only and are never modified by the plugin;
-- are not required to exist by the current implementation;
-- may not point into the managed `documents/` directory itself.
-
-### Scope
-
-The physical sharing scope of Documents is determined by `storageScope`:
-
-- `workspace`: normally isolated with the project;
-- `global` / `custom`: multiple workspaces may share the same `documents/index.json`.
-
-Therefore, “Project Documents” describes the content type and does not guarantee physical isolation by workspace. The current session workspace constrains only `sourcePaths` on new writes.
-
-### Capacity and Hot/Cold Tiering
-
-| Item | Limit |
-|---|---:|
-| One body | 2 MiB maximum |
-| Total active content | 10 MiB maximum, including generated frontmatter |
-| Total archived content | Does not count toward the active limit |
-
-The actual rendered size is calculated before creation or update. If capacity is insufficient, the least recently accessed active Document is selected by `lastAccessedAt` and then `updatedAt`; a Mnemon cold reference is written and verified first, and the original text is moved only if its revision remains unchanged.
-
-Default search covers only active Documents. Search updates `lastAccessedAt` for matching Documents, so it is read-only with respect to bodies but writes index metadata.
-
-## Memory Spaces
-
-Each Memory Space is a native named Mnemon Store with maintainable metadata added in `.dsh-memory-bodies.json`:
-
-```text
-id            Host-generated stable UUID or discovered compatible Store name
-name          human-readable name
-description   routing boundary: what belongs here and when to recall it
-active        whether it participates in reads
-mnemon.db     independent data plane
-```
-
-### Read and Write Boundaries
-
-- Recall, graph, content, and entity reads use only active Memory Spaces.
-- Reads explicitly targeting an inactive Memory Space are rejected.
-- Writes may target any registered Memory Space.
-- After a successful write to an inactive target, the plugin activates it automatically.
-- Without an explicit target, if the number of active Memory Spaces is not exactly one, the deterministic service requires the caller to choose a target first.
-
-### Creation, Discovery, and Merge
-
-- On creation, the model supplies a name and description; the Host generates the ID.
-- An existing `<storageRoot>/data/<store>/mnemon.db` is discovered and registered without moving the database.
-- 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.
-
-## Data Authority Table
-
-| Data | Authoritative source | Derived/cache |
-|---|---|---|
-| Hot memory | `runtime/memories.json` | `USER.md`, `MEMORY.md` |
-| Documents | `documents/index.json` + managed Markdown | excerpts, search ranking, status aggregation |
-| Memory Space catalog | `data/.dsh-memory-bodies.json` + on-disk Stores | Web status aggregation |
-| Long-term memory | Each Store's `mnemon.db` | parsed HTML/DOT graph results |
-| Review watermark | Host process memory | status-page snapshot; not yet persisted |

package/docs/en/ui-guide.md

@@ -1,156 +0,0 @@
-# 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.5 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)