dsh-mnemon 0.1.0

package/docs/en/getting-started.md

@@ -0,0 +1,147 @@
+# Getting Started
+
+[简体中文](../zh-CN/getting-started.md) | **English** | [Documentation Center](./README.md)
+
+## 1. Prerequisites
+
+You need:
+
+- a DSH Web profile that can start successfully;
+- a locally executable `mnemon` CLI;
+- a DSH subagent provider available for bounded subtasks.
+
+The exact provider requirements are:
+
+```text
+regular semantic operations
+  -> prefer provider named "spawn"
+  -> may fall back to another compatible provider
+
+scored background review
+  -> requires provider named "fork"
+  -> inheritsParentContext = true
+
+both paths require
+  -> outputSchema
+  -> toolFilter
+  -> persona
+  -> depthLimit
+```
+
+The plugin does not declare a fixed minimum-version matrix for DSH and Mnemon in its code. Before upgrading, run the verification steps on this page against an isolated data directory.
+
+## 2. Install Mnemon
+
+On macOS, the recommended installation method is Homebrew Cask:
+
+```sh
+brew install --cask mnemon-dev/tap/mnemon
+```
+
+On macOS or Linux, you can also install it with Go:
+
+```sh
+go install github.com/mnemon-dev/mnemon@latest
+```
+
+Verify the binary:
+
+```sh
+mnemon --version
+```
+
+To inspect an upstream Store directly, you can also run `mnemon status`. This command opens the effective Store and may initialize default data or run migrations; do not treat it as a completely side-effect-free installation probe.
+
+If DSH cannot find it on `PATH`, set `MNEMON_CLI_PATH` or configure an absolute path in `mnemon.cliPath`.
+
+## 3. Install the Plugin
+
+Install it into the Web profile:
+
+```sh
+dsh plugin --profile web add dsh-mnemon
+```
+
+Pre-release builds not yet published to npm can be installed from git:
+
+```sh
+dsh plugin --profile web add "github:omdsh-dev/dsh-mnemon"
+```
+
+For a local development checkout:
+
+```sh
+dsh plugin --profile web add "link:/absolute/path/to/dsh-mnemon"
+```
+
+The plugin package's `cordis.patch.yml` mounts the Host plugin; the Web client bundle registers the session workspace and plugin settings card.
+
+## 4. Choose a Storage Scope
+
+Start the DSH Web profile:
+
+```sh
+dsh --profile web
+```
+
+Under “Settings -> Plugin Configuration -> Mnemon,” choose:
+
+| Scope | Root directory | Best suited for |
+|---|---|---|
+| `global` | `MNEMON_DATA_DIR` or `~/.mnemon` | Sharing one memory set across multiple workspaces |
+| `workspace` | `.mnemon` under the DSH Host startup directory | Project isolation |
+| `custom` | `dataDir` | An explicit disk, mounted volume, or dedicated data directory |
+
+Settings are written to `$DSH_HOME/settings.yaml` and take effect after restarting DSH. Switching scopes does not move existing data; to preserve it, stop all writes first and manually copy the entire old root directory.
+
+## 5. Create Your First Memory Space
+
+Open the “Memory System” tab in any session:
+
+1. Open the “Memory Spaces” page.
+2. Create a narrowly scoped Memory Space, such as “Project Decisions.”
+3. Its description should explain what belongs there and which tasks should recall it.
+4. Enable its read toggle, or let the plugin activate it automatically after the first write.
+
+An empty Memory Space may remain inactive by default. Activation controls only the read scope; writes may target any registered Memory Space, and a successful write automatically activates the target.
+
+## 6. Verify the Complete Path
+
+First inspect deterministic status:
+
+```text
+/mnemon status
+```
+
+Then submit a stable, self-contained item that will remain useful in the future on the “Distill” page. The worker selects a Memory Space, checks for duplicates, and returns a structured receipt. Then verify recall:
+
+```text
+/mnemon recall <a focused query that should match the new item>
+```
+
+Finally, check that:
+
+- the “Memory Spaces” page shows the active Memory Space and graph;
+- “Content” shows the new item and its Memory Space;
+- CLI, runtime memory, Memory Space catalog, and subagent status are all healthy under “Status”;
+- the recall result includes a complete `memoryBodyId` and memory ID.
+
+## 7. Recommended First Real Conversation
+
+Choose a question that genuinely depends on a historical decision instead of instructing the model to invoke memory tools unconditionally. The expected flow is:
+
+```text
+user asks a history-dependent question
+  -> pre-step adds a short optional cue
+  -> main Agent decides whether history matters
+  -> recall worker selects active Memory Spaces
+  -> only useful evidence returns to the main Agent
+```
+
+Ordinary conversation should not force recall. The current request, existing source files, and live tool results should take precedence over historical content.
+
+## 8. Next Steps
+
+- Read the [storage model](./storage-model.md) before choosing `storageScope`.
+- Read the [configuration reference](./configuration.md) to configure read-only mode or disable lifecycle cues.
+- Read the [operations guide](./operations.md) to establish backup and pre-upgrade verification procedures.

package/docs/en/interfaces.md

@@ -0,0 +1,159 @@
+# WebUI, Tools, Commands, and RPC
+
+[简体中文](../zh-CN/interfaces.md) | **English** | [Documentation Center](./README.md)
+
+## Web Workspace
+
+The main Web interface follows DSH's global language and light/dark theme. The top navigation is split into three divider-separated groups: “Status” stands alone; “Runtime, Memory Spaces, Documents” cover the three storage tiers; “Distill, Recall, Entities, Content” are the read/write tools. The “Status” page opens by default.
+
+| Page | Purpose | Call Boundary |
+|---|---|---|
+| Status | Diagnostics for the CLI, runtime hot memory, storage scope, Memory Spaces, Documents, lifecycle, and workers | Aggregated reads |
+| Runtime | Inspect and maintain USER / MEMORY hot memory and capacity | Regular mutations are deterministic; capacity maintenance may start a worker |
+| Memory Spaces | Memory Space directory, activation switches and metadata editing, a live multi-space graph, and node inspection | Deterministic RPC reads; switches and metadata edits use write RPC |
+| Documents | Search, read, create, update, and archive Documents | Search/edit operations use the control layer; archiving starts a worker |
+| Distill | Let a memory worker select scope, deduplicate, and write; supports advanced constraints | `spawn` semantic write |
+| Recall | Direct smart / keyword / basic retrieval; optional evidence-bounded Agent answers | Direct service reads; Agent answers use a worker with no tools |
+| Entities | Frequent entities and entity-related context | Direct service reads |
+| Content | Browse active Memory Spaces without recall side effects, copy or clone content, or soft-delete it | Graph reads; deletion uses a worker |
+
+The graph synchronizes every 15 seconds and can also be refreshed manually. Natural layout, uniform reset, dragging, and keyboard adjustments affect only client-side presentation and do not modify Mnemon data.
+
+## Model Tools
+
+### Read-Only Tools
+
+| Tool | Purpose | Root Agent Path |
+|---|---|---|
+| `mnemon_memory_bodies` | Read the Memory Space directory and statistics | Direct service |
+| `mnemon_recall` | Recall from one or more active spaces | `spawn` recall worker |
+| `mnemon_related` | Traverse relationships from a known ID | `spawn` related worker; the root path always requests two hops |
+| `mnemon_status` | Aggregate CLI, configuration, and active-space status | Direct service |
+| `mnemon_document_search` | Deterministically search managed Documents | Direct Documents control layer |
+
+Here, “read-only” means that managed bodies and long-term semantic content are not modified. After a hit, `mnemon_document_search` still updates `lastAccessedAt` and rewrites the Document index for LRU ordering.
+
+### Tools Available When `writeEnabled=true`
+
+| Tool | Purpose | Root Agent Path |
+|---|---|---|
+| `mnemon_runtime_memory` | `add` / `replace` / `remove` hot memory | Deterministic control layer; a worker is used when add overflows |
+| `mnemon_document_manage` | Create, update, or archive a Document | Create/update are deterministic; archive uses a worker |
+| `mnemon_remember` | Distill one insight into long-term memory | `spawn` write worker |
+| `mnemon_link` | Create a typed relationship | `spawn` write worker |
+| `mnemon_forget` | Soft-delete by 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` | Perform a non-destructive import merge | `spawn` write worker |
+
+When a worker calls a tool with the same name, the call goes directly to the service layer and is not delegated again.
+
+## Tool Admission Guidelines
+
+- Hot memory: explicit user preferences, stable project conventions, environment facts, and frequently useful lessons.
+- Document: designs, investigations, procedures, or handoffs with complete structure and rationale.
+- Long-term Memory Space: stable insights that explicitly need to persist across tasks or benefit from graph relationships and deep recall.
+- Skip: questions, guesses, temporary progress, completion logs, raw output, secrets, and repository facts that are easy to rediscover.
+
+`mnemon_forget` is a destructive semantic operation. It should run only when the user explicitly requests it or when content has been verified as incorrect or obsolete.
+
+## `/mnemon` Commands
+
+```text
+/mnemon
+/mnemon status
+/mnemon recall <query>
+/mnemon related <full memory ID>
+/mnemon remember <content>
+/mnemon forget <exact ID>
+```
+
+- An empty `/mnemon` is equivalent to `status`.
+- `status` is a deterministic read and does not start a model.
+- `recall`, `related`, `remember`, and `forget` use the live Agent containing the command as the worker parent.
+- Command recall returns at most 10 results.
+- The `forget` argument must be one exact ID containing no spaces.
+- Current command help and results are primarily in Chinese and do not yet follow the Web locale.
+
+## RPC Channels
+
+RPC is the internal bridge between the DSH Host and this plugin's Web client. It is not a promised stable external HTTP API.
+
+### Read Channel
+
+```text
+channel:   /dsh-mnemon-read
+authority: trusted-host
+```
+
+| Endpoint | Behavior |
+|---|---|
+| `runtime-memory` | Runtime snapshot |
+| `status` | Aggregated service, lifecycle, Documents, and storage-scope status |
+| `documents` | Document directory snapshot |
+| `document` | Read one Document |
+| `document-search` | Deterministic search; hits update LRU metadata |
+| `graph` | Aggregated graph of active Memory Spaces |
+| `bodies` | Memory Space directory |
+| `list` | Content list |
+| `entities` | Entity statistics or entity-related context |
+| `search` | Direct Mnemon retrieval |
+| `agent-search` | Evidence-bounded answer after direct retrieval |
+| `related` | Direct relationship traversal |
+
+### Write Channel
+
+```text
+channel:   /dsh-mnemon-write
+authority: loopback
+```
+
+| Endpoint | Behavior |
+|---|---|
+| `runtime-memory` | Hot-memory mutation |
+| `supervise` | Submit a Tab candidate to a memory worker |
+| `document` | create / update / archive |
+| `remember` | Semantic write with optional advanced constraints |
+| `link` | Create a relationship |
+| `forget` | Soft-delete |
+| `body-create` | Create a Memory Space |
+| `body-update` | Update metadata or active state |
+
+The entire write channel is not registered when `writeEnabled=false`.
+
+### Settings Channel
+
+```text
+channel:   /dsh-mnemon-settings
+authority: loopback
+endpoints: get, mutate
+```
+
+Mutations use the settings revision to prevent overwriting concurrent edits.
+
+## npm Exports
+
+The root package exposes Host-side composition and core classes:
+
+```text
+apply
+Config / resolveConfig
+createRunner
+MnemonService
+RuntimeMemoryController
+DocumentManager
+StorageScopeInspector
+MnemonSubagentCoordinator
+MnemonLifecycle
+```
+
+`dsh-mnemon/client` provides `apply` and `inject` for the DSH client bundle. `MnemonClient` and the RPC endpoints are currently internal implementations and should not be treated as a stable public SDK.
+
+## Internationalization Scope
+
+The Web dictionaries keep Chinese and English keys in one-to-one correspondence. Brand names, tool names, and configuration keys are not translated. Surfaces that are not yet fully internationalized include:
+
+- `/mnemon` command output;
+- model-tool card titles;
+- some Host validation and diagnostic errors;
+- default names and descriptions written during legacy Store compatibility discovery.

package/docs/en/operations.md

@@ -0,0 +1,151 @@
+# Operations, Security, and Troubleshooting
+
+[简体中文](../zh-CN/operations.md) | **English** | [Documentation Center](./README.md)
+
+## Health Checks
+
+Check the binary first, then the plugin's aggregated status:
+
+```sh
+command -v mnemon
+mnemon --version
+```
+
+```text
+/mnemon status
+```
+
+`mnemon status` opens the effective Store, so the upstream CLI may initialize default data or run migrations. It is not a completely side-effect-free read probe. The plugin's Status page also checks active Memory Spaces, Documents, lifecycle state, and subagent counts.
+
+## Security Boundaries
+
+### Process
+
+- `spawn(command, args, { shell: false })`; shell commands are never concatenated.
+- stdout + stderr have a combined default limit of 2 MiB.
+- Every CLI call is governed by `timeoutMs` and an AbortSignal.
+- On timeout or cancellation, the process first receives `SIGTERM`, then `SIGKILL` if it has not exited after 1.5 seconds.
+- CLI calls within one `MnemonRunner` are serialized to avoid SQLite lock conflicts from concurrent migrations in the same process.
+
+The serial queue does not replace coordination across DSH processes. When multiple Hosts access the same Mnemon Store concurrently, they still rely on Mnemon/SQLite's own concurrency semantics.
+
+### Files
+
+- Runtime and Documents both use an in-process queue and a cross-instance lock file.
+- Lock acquisition waits up to 5 seconds by default; a lock is considered stale only after 30 seconds.
+- Writes use temporary files and rename.
+- Runtime uses a revision to prevent stale compaction from overwriting concurrent changes.
+- Document archiving uses a numeric revision to prevent moving active source text that has since been updated.
+- `sourcePaths` cannot escape the initiating session's workspace or point into the managed Documents directory.
+
+### Web
+
+- Read RPC: `trusted-host`.
+- Memory write RPC: `loopback`.
+- Settings RPC: `loopback`.
+- The WebUI neither reads SQLite directly nor starts processes.
+
+### Model
+
+- Workers use a persona, a tool allowlist, structured output, and `maxDepth: 1`.
+- User queries, candidate content, Document bodies, and historical memories are all treated as untrusted data.
+- The evidence-answer worker has no Mnemon tools and can use only the hits supplied by the Host.
+
+These boundaries are not a secret scanner. There is currently no deterministic credential/secret detection. Do not submit keys, tokens, private keys, or raw sensitive logs to hot memory, Documents, or Memory Spaces.
+
+## Backup
+
+All three tiers share `storageRoot`. A consistent backup should cover the entire root, not just `mnemon.db`:
+
+```text
+<storageRoot>/runtime
+<storageRoot>/documents
+<storageRoot>/data
+<storageRoot>/state    # when present
+```
+
+Recommended procedure:
+
+1. Stop the DSH Host and any other process writing to the same root.
+2. Record the current plugin, DSH, and `mnemon --version` versions.
+3. Copy the entire root to a new timestamped directory.
+4. Generate a file inventory or checksums for the backup.
+5. Complete a recovery rehearsal in an isolated path before relying on the backup.
+
+The project currently has no built-in consistent snapshot, export, or recovery command. Copying while the system is running may capture an inconsistent state across files.
+
+## Recovery
+
+1. Stop every DSH/Mnemon process using the target root.
+2. Preserve a second copy of the existing root; do not overwrite the only copy of the data.
+3. Restore the complete backup to a new directory.
+4. First point `storageScope=custom` at the new directory.
+5. Start the system and inspect the Runtime projections, Document index, Memory Space directory, and recall.
+6. After verification, decide whether to replace the original root.
+
+If `USER.md` / `MEMORY.md` is damaged, the control layer can repair it from a valid `memories.json`. There is no general automatic repair flow for damaged JSON, the Document index, or SQLite.
+
+## Changing Storage Scope
+
+The plugin does not migrate data automatically:
+
+```text
+old scope -- change setting + restart --> new empty or existing scope
+
+no implicit copy
+no implicit merge
+no implicit delete
+```
+
+When migration is required, stop writes and copy the complete root. Two roots cannot be merged by overwriting directories because JSON indexes, the registry, and multiple databases may conflict. Design an explicit merge procedure against backups instead.
+
+## Troubleshooting
+
+| Symptom | Check and Resolution |
+|---|---|
+| Mnemon is unavailable | Run `command -v mnemon` and `mnemon --version`; set `MNEMON_CLI_PATH` or `cliPath`, then restart |
+| Status is healthy but recall is empty | Check that a Memory Space is active, inspect the current `storageScope` and DSH launch cwd, and make sure the query is focused enough |
+| `memoryBodyId is required...` | The active count is not exactly 1; have the worker or caller select a target explicitly |
+| `memory body is not active for reading` | Activate the target in Overview; writing to an inactive space is allowed, but reading is not |
+| Subagent provider error | Regular tasks require the full isolation capabilities; background review additionally requires `fork + inheritsParentContext` |
+| Settings have no effect after saving | All options take effect after restart |
+| Custom directory is rejected | Use an absolute path, `~`, or `~/...` |
+| Document has no workspace | The session must correspond to a live root Agent and include cwd in its session header |
+| Source path is rejected | The path must stay within the session workspace and must not reference the managed Documents directory |
+| Runtime replace exceeds capacity | Shorten the replacement or organize it explicitly first; current automatic maintenance handles only add overflow |
+| CLI timeout | Increase `timeoutMs`; status and graph exports for large Stores may take longer than 10 seconds |
+| Lock timeout | Check whether another instance is writing; do not delete a lock that still belongs to a live process |
+| Invalid JSON / unexpected viz | The CLI output protocol may be incompatible; validate the version against an isolated root and do not continue writing production data |
+| A remote page can read but not write | Write RPC enforces loopback by design |
+| `tabEnabled=false` still shows the Tab | The setting currently stops only Host data RPC and does not remove the client slot |
+| Local link does not reflect source | Run `pnpm run build`, then restart the DSH profile |
+
+## Known Limitations
+
+### Feature Read-Only Is Not Disk Read-Only
+
+`writeEnabled=false` disables semantic mutations, but startup may still create or repair Runtime files, Document search updates `lastAccessedAt`, and Mnemon reads may trigger upstream migrations. Do not assume it can operate without writes on a genuinely read-only filesystem.
+
+### Shared Scope of Documents
+
+`global` and `custom` may cause multiple workspaces to share one Document index; records do not have a separate workspace-ownership field. `sourcePaths` are validated against the initiating session's cwd only when written.
+
+### Cold-Reference Paths
+
+The current archive-worker prompt uses `.mnemon/documents/archived/<filename>` as its planned reference. Under global/custom scope, the actual file is at `<storageRoot>/documents/archived/<filename>`. When locating the original, use `documents/index.json` or the `relativePath` shown in the UI as the source of truth. This path-expression difference remains to be fixed.
+
+### Cross-System Transactions
+
+“Index first, move second” protects the active source text but is not a rollback-capable distributed transaction across Mnemon SQLite and the filesystem. If a revision conflict occurs after indexing succeeds, the index may retain a duplicate reference; the plugin chooses to preserve data instead of rolling back a completed long-term write.
+
+### Background Watermarks
+
+Scores, the latest checkpoint, and retry state are not persisted. Restarting the Host clears activity that has not yet been processed. Failure backoff, circuit breaking, and a manual retry entry point are not yet implemented either.
+
+### Version Matrix
+
+The project does not yet declare a formal DSH/Mnemon support matrix or schema-migration policy. Back up first and validate against an isolated root before upgrading.
+
+### Internationalization
+
+The main Web workspace is bilingual in Chinese and English, but commands, tool cards, compatibility default metadata, and some error messages are not yet fully internationalized.