dsh-mnemon 0.1.4 → 0.1.6

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

package/docs/en/workflows.md

@@ -1,290 +0,0 @@
-# Lifecycle and Core Workflows
-
-[简体中文](../zh-CN/workflows.md) | **English** | [Documentation Center](./README.md)
-
-## Per-Turn Context
-
-The plugin registers two system prompt sections:
-
-- `mnemon:routing`: when `routingGuidance=true`, provides concise boundaries for tiered queries;
-- `mnemon:runtime-memory`: reads the latest `USER.md` and `MEMORY.md` whenever a prompt is assembled and includes admission rules for saving content.
-
-Lifecycle hooks do not unconditionally read the Memory Space catalog or run recall at the start of every turn:
-
-```text
-agent/session-start
-  -> mark primePending
-
-agent/pre-step(step=1)
-  -> cancel pending/running background review for a new turn
-  -> mark Prime once
-  -> optionally append one short recall/writeback cue
-  -> main Agent decides whether to call a memory tool
-```
-
-Prime only initializes routing state; it does not run asynchronous CLI status queries.
-
-## Root Agent Recall
-
-```text
-Root Agent calls mnemon_recall(query)
-          |
-          v
-MnemonSubagentCoordinator
-          |
-          | spawn + recall persona
-          | allow: memory_bodies, recall, related
-          v
-Recall worker lists the catalog
-          |
-          v
-select active Memory Space(s) by name + description
-          |
-          v
-call mnemon_recall from the worker
-          |
-          v
-MnemonService searches selected Store(s)
-          |
-          v
-normalize and attach memoryBodyId / memoryBodyName
-          |
-          v
-structured output, Host caps results at 12
-          |
-          v
-Root Agent receives evidence, not the raw routing trace
-```
-
-If the user has already supplied current facts, or the repository can answer directly, the Agent should not recall merely to “show memory.” When relationship explanations are needed, first use the complete `memoryBodyId + id` returned by recall, then run related.
-
-## Web Retrieval and Agent Queries
-
-The Web “Recall” page follows a different path from model tools:
-
-```text
-Direct search
-  -> RPC read channel
-  -> MnemonService.search directly
-  -> raw evidence
-
-Agent search
-  -> the same deterministic direct search
-  -> spawn a worker with no Mnemon tools
-  -> answer only from supplied evidence
-  -> Host filters citations to actual memoryBodyId/id pairs
-```
-
-The “Entities” and “Content” pages also read the deterministic service directly and do not start a recall worker. “Content” uses a graph snapshot and does not increment Mnemon recall access counts.
-
-## Explicit Long-Term Writes
-
-The long-term write flow for the root Agent or `/mnemon remember` is:
-
-```text
-durable candidate
-       |
-       v
-spawn write worker
-       |
-       +-- list Memory Spaces
-       +-- choose the narrowest suitable scope
-       +-- recall when duplicate/conflict checking is useful
-       +-- create a new scope only for a recurring distinct domain
-       +-- remember / link / forget / merge as requested
-       v
-structured receipt
-```
-
-The Host generates IDs for new Memory Spaces. A successful write to an inactive target activates it. Merging a source database is non-destructive.
-
-Runtime `add` / `replace` / `remove` and Document `create` / `update` do not need a model to perform storage I/O; they enter the deterministic control layer through the coordinator. Only capacity maintenance and archiving start dedicated workers.
-
-## Runtime add: Normal Path
-
-```text
-request
-  -> normalize content
-  -> acquire in-process queue and file lock
-  -> reload memories.json
-  -> validate unique match / duplicate / capacity
-  -> write temporary JSON and Markdown projections
-  -> rename projections
-  -> rename memories.json as the commit marker
-  -> return compact receipt
-```
-
-`replace` and `remove` must match exactly one item through `old_text`. Capacity maintenance is triggered automatically only when `add` overflows.
-
-## USER.md Capacity Maintenance
-
-```text
-USER add exceeds 4 KiB
-          |
-          v
-snapshot revision + committed entries
-          |
-          v
-spawn no-tool local compactor
-          |
-          v
-return compacted entries + sourceIndexes
-          |
-          v
-Host validates:
-  - every source index appears exactly once
-  - no duplicate or out-of-range index
-  - importance is not lowered
-  - candidate fits the Host byte budget
-  - revision is still current
-          |
-          +-- invalid/conflict -> preserve original data
-          |
-          v
-deterministic UTF-8 packing
-          |
-          v
-retry pending add
-```
-
-The user profile is never sent to Memory Spaces. The worker has no tool permissions.
-
-## MEMORY.md Archival and Compaction
-
-```text
-MEMORY add exceeds 10 KiB
-          |
-          v
-snapshot revision + committed entries
-          |
-          v
-spawn archive worker
-  allow: memory_bodies, recall, remember, body_create
-          |
-          v
-route semantic clusters and archive or duplicate-check them
-          |
-          v
-return action + target spaces + compacted candidates
-          |
-          v
-Host validates structure, action, revision and byte budget
-          |
-          +-- failure/conflict -> preserve hot memory
-          |
-          v
-pack candidates by importance
-          |
-          v
-retry pending add
-```
-
-The worker persona requires every committed entry to be represented in long-term storage or verified as a duplicate; this is an LLM-supervised policy. The Host's hard guarantees are structural, revision, and capacity validation, so semantic coverage should not be described as a database-level proof.
-
-If a revision conflict occurs after a successful long-term write, the hot memory is preserved while the long-term layer may also contain a copy. The plugin prioritizes preventing data loss and does not attempt to roll back a completed Mnemon write across the database and file system.
-
-## Document Creation, Update, and Archiving
-
-```text
-create/update request
-          |
-          v
-capacityPlan using rendered UTF-8 bytes
-          |
-     +----+----+
-     |         |
-    fits     overflow
-     |         |
-     v         v
- commit    select least-recently-used active Document
-               |
-               v
-          snapshot document + revision
-               |
-               v
-          spawn archive worker
-               |
-               v
-       write/verify concise Mnemon cold reference
-       with title, summary, planned path, SHA-256
-               |
-          +----+----+
-          |         |
-        failed    receipt ok
-          |         |
-          v         v
-   keep active   revision check
-                    |
-               +----+----+
-               |         |
-             conflict   current
-               |         |
-               v         v
-          keep active  move file to archived
-                             |
-                             v
-                    retry original mutation
-```
-
-Manual archiving uses the same “index first, move second” path. When the Mnemon index succeeds but a revision conflict occurs, the index is not rolled back, so a safe duplicate reference may remain while the active original text is never lost.
-
-## Deterministic Activity Scoring and Background Review
-
-Completed turns accumulate four signals:
-
-```text
-score =
-  min(floor(totalUserCharacters / 50), 3)
-  + completedTurnCount
-  + min(floor(completedToolResults / 5), 2)
-  + toolDiversityScore
-
-toolDiversityScore:
-  unique tools < 3  -> 0
-  unique tools = 3  -> 1
-  unique tools >= 4 -> 2
-
-eligible when score >= 5
-```
-
-Reaching the threshold does not guarantee a write:
-
-```text
-completed turn
-      |
-      v
-score >= 5 ? -- no --> retain activity for later turns
-      |
-     yes
-      |
-      v
-wait idleReviewMs (default 30 s)
-      |
-      +-- new turn --> cancel timer/worker, retain activity
-      |
-      v
-confirm Agent is idle and turn/end exists
-      |
-      v
-fork completed parent checkpoint
-      |
-      v
-conservative maintenance decision
-  - at most one hot-memory mutation by persona
-  - at most one Document create/update by persona
-  - no direct long-term remember/forget tools
-      |
-      +-- completed, including skip -> clear activity
-      |
-      +-- failed/aborted ------------> retain activity
-```
-
-“At most one” is currently enforced by the worker persona, not by a Host mutation counter. Background watermarks are not yet persisted, so a Host restart loses accumulated signals that have not been processed.
-
-## How Configuration Switches Interact
-
-- `recallMode=off`: stops injecting recall cues; explicit `mnemon_recall` remains available.
-- `writebackMode=off`: disables writeback cues and scored background review; explicit writes are still governed by `writeEnabled`.
-- `lifecycleEnabled=false`: disables lifecycle reminders and review without removing explicit tools or Web entry points.
-- `routingGuidance=false`: removes only the additional routing section; the Runtime Memory section remains registered.
-- `writeEnabled=false`: removes semantic write tools and write RPC, and rejects write commands; it does not guarantee a read-only file-system mount.