dsh-mnemon 0.1.5 → 0.1.6

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.

package/docs/zh-CN/README.md

@@ -1,48 +0,0 @@
-# dsh-mnemon 文档中心
-
-**简体中文** | [English](../en/README.md) | [项目首页](../../README.zh-CN.md)
-
-这里按“你现在要完成什么”组织文档。第一次使用从快速开始进入；需要理解页面时看 UI 指南；只有在部署、集成或开发时才需要进入参考文档。
-
-## 新用户路径
-
-1. [快速开始](./getting-started.md)：安装 Mnemon 与插件，选择存储范围，完成第一次验证。
-2. [Sidebar 与对话交互指南](./ui-guide.md)：认识状态、运行时、记忆体、档案和对话内入口。
-3. [项目介绍](./project-overview.md)：理解三层模型、跨 Agent 共享边界、读写边界与完整流转。
-
-## 按任务查找
-
-| 我想要…… | 文档 |
-|---|---|
-| 决定一条信息应放在哪一层 | [存储与三层记忆模型](./storage-model.md) |
-| 让 DSH 与其他 Mnemon-enabled Agent 共享长期记忆 | [项目介绍：跨 Agent 共享边界](./project-overview.md#跨-agent-共享边界) · [配置参考：共享范围](./configuration.md#选择跨-agent-共享范围) |
-| 了解每轮注入、召回、沉淀和归档何时发生 | [生命周期与核心流程](./workflows.md) |
-| 切换 Sidebar / Buildin、全局 / 工作区 / 自定义目录 | [配置参考](./configuration.md) |
-| 理解工作区“查看目录”与 Agent“实际生效目录” | [UI 指南：工作区模式](./ui-guide.md#工作区模式查看与执行分离) |
-| 检查或更新 Mnemon 与 dsh-mnemon | [运维指南：版本检查与更新](./operations.md#版本检查与更新) |
-| 备份、恢复或迁移完整记忆目录 | [运维指南：备份与恢复](./operations.md#备份与恢复) |
-| 排查召回为空、目录未对齐、CLI 或 Provider 问题 | [运维、安全与故障排查](./operations.md#故障排查) |
-| 使用模型工具、`/mnemon` 命令或内部 RPC | [接口参考](./interfaces.md) |
-| 理解 Host、worker、控制面与数据面 | [架构设计](./architecture.md) |
-| 修改代码、截图、测试或发布 | [开发与验证](./development.md) |
-| 查看下一阶段计划 | [Roadmap](./roadmap.md) |
-
-## 核心术语
-
-| 中文 | 英文 / 代码名 | 含义 |
-|---|---|---|
-| 记忆系统 | Memory System | dsh-mnemon 在 DSH 中的完整入口 |
-| 运行时记忆 | Runtime Memory | 每轮注入的 USER / MEMORY 热记忆 |
-| 档案 | Project Documents | 受管、可检索、保留完整 Markdown 叙事的项目知识 |
-| 记忆体 | Memory Space | 独立、可激活、按需召回的长期 Mnemon Store |
-| 跨 Agent 共享 | Cross-agent memory sharing | 多个 Mnemon-enabled Agent 使用同一根和 Store，共享长期记忆而非完整 DSH 上下文 |
-| 沉淀 | Remember / Distill | 把候选交给受监督子 Agent 判断、查重与写入 |
-| 召回 | Recall | 从已激活记忆体按需取回有界证据 |
-| 归档 | Archive | 先建立冷引用，再把不常用档案迁出 active 层 |
-
-## 文档边界
-
-- 用户文档以 v0.1.5 的 Sidebar 默认体验为主，同时说明 Buildin 兼容形态。
-- 架构图表达稳定执行边界，不是实时监控面板；实时数量与版本以“状态”页为准。
-- RPC 是 Host 与插件客户端之间的内部协议，不承诺稳定外部 API。
-- 当前没有正式固定的 DSH / Mnemon 版本矩阵；升级前应备份并在隔离目录验证。

package/docs/zh-CN/architecture.md

@@ -1,133 +0,0 @@
-# 架构设计
-
-**简体中文** | [English](../en/architecture.md) | [文档中心](./README.md)
-
-## 定位
-
-`dsh-mnemon` 是 DSH 与 Mnemon 之间的集成和监督层，不是新的数据库引擎：
-
-- DSH 提供主 Agent、生命周期事件、subagent provider、工具、命令、设置和 Web 扩展点；
-- 插件提供三层知识控制面、路由策略、事务屏障和 UI；
-- 本地 `mnemon` CLI 提供命名 Store、SQLite 持久化、四类图、召回、关系和软删除，并形成与其他 Mnemon-enabled Agent 共享长期记忆的数据边界。
-
-## 组件图
-
-[![dsh-mnemon 运行时架构](../assets/diagrams/zh-CN/project-architecture.svg)](../assets/diagrams/zh-CN/project-architecture.svg)
-
-图中实线表示确定性数据或控制路径，紫色虚线表示 LLM 监督路径。Runtime Memory 和 Documents 直接使用受管文件；只有 Memory Spaces 通过 `MnemonRunner` 调用本地 Mnemon CLI。点击图片可以查看原始 SVG。
-
-因此跨 Agent 互操作只发生在图中的 Memory Spaces：共享的是 Mnemon Store 内的长期记忆与关系，不是 DSH 的会话上下文、Runtime 投影或 Documents 控制面。插件不会把数据主动推送到其他 Agent；参与方通过对齐本地 Mnemon 根和 Store 来共享。
-
-## Host 组合根
-
-`src/index.ts::apply()` 按以下顺序组装插件：
-
-```text
-settings.register("mnemon")
-  -> resolveConfig
-  -> createRunner
-  -> MnemonService
-  -> RuntimeMemoryController
-  -> DocumentManager
-  -> StorageScopeInspector
-  -> MnemonSubagentCoordinator
-  -> MnemonLifecycle
-  -> tools / commands / prompt sections
-  -> register RPC when a Web connection exists
-```
-
-Host 声明依赖 `tools`、`settings`、`commands`、`agents` 和 `subagents`。Web client 另外依赖 slots、connection 和 DSH locale 服务。
-
-## 主 Agent 与 worker 的双路径
-
-同名 `mnemon_*` 工具根据调用者是否为 subagent 分流，防止递归委派：
-
-```text
-root Agent calls mnemon_recall
-  -> coordinator starts a bounded recall worker
-  -> worker calls mnemon_memory_bodies and mnemon_recall
-  -> tool sees origin=subagent
-  -> call reaches MnemonService directly
-  -> structured evidence returns to root Agent
-```
-
-长期语义写入、关系、软删除以及记忆体创建/更新/合并采用相同模式。运行时记忆和 Documents 的普通变更先经过 coordinator，但通常由确定性控制层直接提交；只有容量维护或归档需要额外 worker。
-
-记忆体目录的物理删除是单独的确定性危险操作：WebUI 必须先展示二次确认，随后经 loopback 写 RPC 调用 Mnemon 原生 `store remove`；只有 CLI 删除成功后才移除目录登记。
-
-## 两类子 Agent
-
-### `spawn`
-
-`spawn` 使用新的隔离上下文。插件为每类任务提供：
-
-- 固定 persona；
-- 最小工具白名单；
-- DSH 支持子集内的结构化输出 schema；
-- `maxDepth: 1`；
-- 可取消的 signal 和有界 token 预算。
-
-它用于召回、长期语义写入、证据限定问答、热记忆整理和 Document 归档。
-
-### `fork`
-
-评分后台审查必须使用名为 `fork` 且 `inheritsParentContext=true` 的 provider。它只继承已经完成的父 checkpoint，用于判断是否需要维护热记忆或最多一份项目档案。它不是用户任务的延续，也不会把审查推理注入主对话。
-
-当前审查白名单不包含 `mnemon_remember`、`mnemon_forget` 或记忆体维护工具，因此后台审查不会直接修改长期记忆体。
-
-## 控制面与数据面
-
-```text
-LLM-owned judgment                  Host-owned guarantees
-------------------                  ---------------------
-what is worth keeping               input validation
-which Memory Space fits             path boundary
-whether two items are duplicates    process timeout/cancel
-how to summarize a Document         file lock + atomic rename
-whether a reusable artifact exists  UTF-8 capacity accounting
-                                     revision conflict rejection
-                                     read/write RPC authority
-```
-
-必须区分“persona 约束”和“Host 硬保证”。例如 MEMORY 归档 worker 被要求覆盖每条已提交热记忆，但 Host 只能硬校验结构化 action、revision 和字节预算；USER 压缩的 source coverage 则由 Host 逐项验证。
-
-## Web 边界
-
-WebUI 不启动系统进程，也不直接打开 SQLite：
-
-```text
-browser component
-  -> typed client wrapper
-  -> DSH RPC authority check
-  -> Host validation
-  -> controller / service / bounded worker
-  -> local CLI or managed files
-```
-
-读通道要求 `trusted-host`，记忆写通道和设置通道要求 `loopback`。`writeEnabled=false` 时 Host 不注册记忆写通道。
-
-## 国际化
-
-`src/client/locales.ts` 以中文键集定义 `MnemonKey`，英文词典必须满足同一键集合；`src/client/index.ts` 把两套词典注册到 DSH locale。主要 Web 页面和设置卡随 DSH 全局语言即时切换，并复用全局明暗主题。
-
-当前命令输出、工具卡标题、持久化的兼容默认记忆体名称和部分后端错误仍是单语，这是 Roadmap 中的已知缺口。
-
-## 关键模块
-
-| 模块 | 职责 |
-|---|---|
-| `src/index.ts` | Host 组合与注册 |
-| `src/config.ts` | 配置 schema、默认值和解析 |
-| `src/process.ts` | 无 shell 的有界进程执行 |
-| `src/runner.ts` | CLI 发现、参数、序列化和 JSON 解析 |
-| `src/service.ts` | 长期记忆应用门面 |
-| `src/memory-bodies.ts` | Memory Space 目录元数据 |
-| `src/runtime-memory.ts` | 热记忆事实源与投影 |
-| `src/documents.ts` | Documents 控制面 |
-| `src/subagent.ts` | worker 编排与容量事务 |
-| `src/lifecycle.ts` | per-root-Agent 生命周期 |
-| `src/review-activity.ts` | 确定性审查评分 |
-| `src/tools.ts` | 模型工具及 root/worker 分流 |
-| `src/rpc.ts` | Web 读写通道 |
-| `src/storage-scope.ts` | 三种存储范围的只读盘点 |
-| `src/client/*` | Web 工作台、设置和 locale |