dsh-mnemon 0.1.0

package/docs/zh-CN/configuration.md

@@ -0,0 +1,204 @@
+# 配置参考
+
+**简体中文** | [English](../en/configuration.md) | [文档中心](./README.md)
+
+## 配置位置与生效方式
+
+插件在 DSH settings 服务中注册 `mnemon` 命名空间。用户配置位于：
+
+```text
+$DSH_HOME/settings.yaml
+```
+
+默认通常是 `~/.dsh/settings.yaml`。当前全部配置标记为 `restart` 生效；保存后需要重启 DSH Host。
+
+Web 设置卡只编辑 `storageScope` 和 `dataDir`。其他高级项需要直接修改 YAML。
+
+## 完整示例
+
+```yaml
+mnemon:
+  storageScope: global # global | workspace | custom
+  # dataDir: ~/mnemon-data       # custom 时必填
+  # cliPath: /opt/homebrew/bin/mnemon
+  # store: legacy-store          # 兼容发现提示，不是常规路由目标
+  timeoutMs: 10000
+  defaultRecallLimit: 10
+  routingGuidance: true
+  lifecycleEnabled: true
+  recallMode: guided
+  writebackMode: guided
+  idleReviewMs: 30000
+  tabEnabled: true
+  writeEnabled: true
+```
+
+## 选项
+
+| 配置 | 默认值 | 范围 | 实现语义 |
+|---|---:|---|---|
+| `storageScope` | `global` | `global` / `workspace` / `custom` | 统一控制 Runtime、Documents、Memory Spaces 和预留 state 根目录 |
+| `dataDir` | 未设置 | 绝对路径、`~` 或 `~/...` | `custom` 时必填；旧配置只设置它时自动解析为 `custom` |
+| `cliPath` | 自动发现 | 可执行路径 | 显式指定 Mnemon CLI |
+| `store` | 未设置 | `[A-Za-z0-9][A-Za-z0-9_-]*` | 用于旧 Store 的兼容发现/首选提示；语义操作由 Memory Space 路由 |
+| `timeoutMs` | `10000` | 100–120000 ms | 单次 CLI 硬超时 |
+| `defaultRecallLimit` | `10` | 1–50 | 服务和 UI 默认召回条数；不同入口可能再收紧 |
+| `routingGuidance` | `true` | boolean | 是否注册额外的分层路由 system section |
+| `lifecycleEnabled` | `true` | boolean | 是否启用 pre-step cue 和评分后台审查 |
+| `recallMode` | `guided` | `guided` / `off` | 是否注入按需 recall cue；不移除显式召回 |
+| `writebackMode` | `guided` | `guided` / `off` | 是否注入热记忆 cue 并启用评分后台审查；不移除显式写入 |
+| `idleReviewMs` | `30000` | 5000–600000 ms | 达标后需要连续空闲的时间 |
+| `tabEnabled` | `true` | boolean | 当前只门控 Host Mnemon 数据 RPC；客户端 Tab 仍会注册，见下方限制 |
+| `writeEnabled` | `true` | boolean | 是否暴露语义写工具、写 RPC 和写命令 |
+
+## 存储范围
+
+### `global`
+
+```text
+MNEMON_DATA_DIR when non-empty
+  otherwise ~/.mnemon
+```
+
+适合希望多个工作区共享 Runtime、Documents 和 Memory Spaces 的用户。
+
+### `workspace`
+
+```text
+resolve(process.cwd(), ".mnemon")
+```
+
+这里的 cwd 是 DSH Host 进程启动目录，不是浏览器页面当前目录，也不一定等于每个会话记录的 cwd。应从目标项目目录启动 DSH。
+
+### `custom`
+
+```yaml
+mnemon:
+  storageScope: custom
+  dataDir: /absolute/path/to/mnemon-data
+```
+
+也允许 `~` 和 `~/...`。相对路径会被拒绝。
+
+## CLI 发现优先级
+
+```text
+config.cliPath
+  -> executable MNEMON_CLI_PATH
+  -> each PATH directory
+  -> ~/.local/bin/mnemon
+  -> /opt/homebrew/bin/mnemon
+  -> /usr/local/bin/mnemon
+  -> /usr/bin/mnemon
+```
+
+显式 `cliPath` 会被采用；若它不可执行，实际调用会返回启动错误。
+
+## 兼容 Store 提示优先级
+
+```text
+config.store
+  -> MNEMON_STORE
+  -> <storageRoot>/active
+  -> default
+```
+
+Memory Space 目录建立后，长期语义操作使用明确的记忆体 ID，不依赖全局 active Store 进行路由。
+
+## Provider 要求
+
+普通 worker 会优先选择 `spawn`；如果没有该名称，可以选择另一个具备全部能力的 provider：
+
+```text
+outputSchema = true
+toolFilter   = true
+persona      = true
+depthLimit   = true
+```
+
+后台审查没有回退：必须存在名为 `fork` 的兼容 provider，并且：
+
+```text
+inheritsParentContext = true
+```
+
+缺少 `fork` 不会阻止确定性状态或普通 UI 读取，但达到审查门槛时会记录 subagent 失败。
+
+## 只读配置
+
+```yaml
+mnemon:
+  writeEnabled: false
+```
+
+效果：
+
+- 不注册模型写工具；
+- 不注册 `/dsh-mnemon-write` RPC；
+- `/mnemon remember` 和 `/mnemon forget` 拒绝；
+- `MnemonService` 的语义 mutation 拒绝。
+
+它是“功能只读”，不是文件系统只读模式：Runtime 控制器仍可能初始化或修复投影，Document 搜索会更新 LRU 访问时间，Mnemon 读命令也可能触发上游数据库迁移。不要把 `writeEnabled=false` 用作只读挂载的安全承诺。
+
+## 开关交互
+
+```text
+writeEnabled=false
+  -> overrides all explicit semantic writes
+
+writebackMode=off
+  -> no write cue, no scored review
+  -> explicit writes remain when writeEnabled=true
+
+recallMode=off
+  -> no recall cue
+  -> explicit recall remains
+
+lifecycleEnabled=false
+  -> no lifecycle cues or review
+  -> UI, commands, and explicit tools remain
+
+routingGuidance=false
+  -> removes only mnemon:routing
+  -> runtime-memory prompt section remains
+```
+
+## `tabEnabled` 当前限制
+
+Host 在 `tabEnabled=false` 时不注册 Mnemon read/write RPC，但 Web client 仍无条件注册 conversation view slot。因此当前效果是“Tab 入口仍可能出现但数据接口不可用”，而不是完整隐藏 Tab。这是实现缺口，不应依赖它进行 UI 卸载。
+
+## Profile patch 覆盖
+
+包内 `cordis.patch.yml` 提供默认 config 行。DSH profile 的同 ID 配置可能整体覆盖这行；自定义 patch 时应保留仍需启用的键，而不是假设深合并。
+
+## 常见配置
+
+工作区隔离：
+
+```yaml
+mnemon:
+  storageScope: workspace
+```
+
+自定义数据盘和较长 CLI 超时：
+
+```yaml
+mnemon:
+  storageScope: custom
+  dataDir: /Volumes/AgentData/mnemon
+  timeoutMs: 30000
+```
+
+保留显式工具、关闭生命周期行为：
+
+```yaml
+mnemon:
+  lifecycleEnabled: false
+```
+
+仅关闭后台写回判断：
+
+```yaml
+mnemon:
+  writebackMode: off
+```

package/docs/zh-CN/development.md

@@ -0,0 +1,178 @@
+# 开发与验证
+
+**简体中文** | [English](../en/development.md) | [文档中心](./README.md)
+
+## 环境
+
+仓库没有在 `package.json` 中声明 Node、pnpm、DSH 或 Mnemon 的最低版本。使用当前 DSH 开发环境，并在升级依赖时通过完整验证链路确认兼容性。
+
+安装依赖：
+
+```sh
+pnpm install
+```
+
+## 标准命令
+
+```sh
+pnpm run typecheck  # tsc --noEmit
+pnpm test           # vitest run
+pnpm run build      # declarations + host/client bundles
+pnpm run verify     # typecheck + test + build
+```
+
+## 目录结构
+
+```text
+src/
++-- index.ts                  # Host composition root
++-- config.ts                 # settings schema
++-- process.ts / runner.ts    # local CLI execution
++-- service.ts                # durable-memory facade
++-- memory-bodies.ts          # Memory Space registry
++-- runtime-memory.ts         # hot-memory authority
++-- documents.ts              # managed Documents
++-- subagent.ts               # bounded workers
++-- lifecycle.ts              # root-Agent hooks
++-- review-activity.ts        # activity score
++-- tools.ts / commands.ts    # model and human interfaces
++-- rpc.ts / settings.ts      # Web bridges
++-- storage-scope.ts          # storage inventory
++-- client/                   # React workspace and locales
+tests/                        # Vitest suites
+lib/                          # committed build artifacts
+docs/zh-CN/                   # Chinese documentation
+docs/en/                      # English mirror
+cordis.patch.yml              # DSH profile bundle patch
+```
+
+## 构建产物
+
+```text
+tsc -p tsconfig.build.json
+  -> lib/types/*              declarations, maps, intermediate ESM
+
+tsdown host bundle
+  -> lib/index.js             Node ES2024 ESM
+
+tsdown client bundle
+  -> lib/client.js            DSH browser module wrapper
+  -> lib/client.js.map
+
+lightningcss plugin
+  -> CSS Modules compiled and injected as scoped <style>
+```
+
+Host 保持 `cordis` 和 `schemastery` external。Client 保持 React、ReactDOM、JSX runtime 和 Cordis external，其余依赖打入 bundle。
+
+`lib/` 是发布输入的一部分。修改 `src/` 后必须重新构建并检查生成 diff；不要手工编辑 `lib/`。
+
+## 测试层次
+
+现有 Vitest 套件覆盖：
+
+- 配置解析、CLI 查找、进程串行；
+- Memory Space 发现、激活、路由与合并；
+- recall payload 兼容和图谱解析；
+- Runtime JSON/Markdown 一致性、锁、容量、UTF-8 和 revision；
+- Documents 路径、frontmatter、搜索、LRU、归档与冲突；
+- worker 工具隔离、schema 子集、结构化回执；
+- 生命周期 cue、评分、idle debounce、取消和水位保留；
+- RPC authority、只读行为和设置 revision；
+- Web 工作台、双语文案和关键交互。
+
+这些主要是临时目录、fake runner 和 mock Host 集成测试，不等同于自动化的真实 DSH + Mnemon WebUI E2E。
+
+## 真实 WebUI 验证
+
+发布前使用隔离环境，避免污染个人记忆：
+
+```text
+temporary DSH_HOME
+temporary MNEMON_DATA_DIR or custom storageScope
+temporary workspace
+independent Web port
+local link installation
+```
+
+建议场景：
+
+1. 空根：UI 不报错，能够创建第一个 Memory Space。
+2. 普通对话：只出现短 cue，不强制 recall 或写入。
+3. 历史问题：Agent 自主 recall，并返回正确 space provenance。
+4. 显式沉淀：worker 查重、选择范围并可被再次召回。
+5. 多空间：读取只覆盖 active，写入 inactive 后自动激活。
+6. Runtime：USER / MEMORY add、replace、remove 和投影一致。
+7. Documents：创建、检索、更新、人工归档和原项目文件不变。
+8. 评分审查：轻任务不触发；达标后等待 idle；新 turn 能取消并保留水位。
+9. 只读：写工具、写命令和写 RPC 被拒绝，读取仍可用。
+10. 状态和浏览器控制台：无未处理错误或警告。
+
+容量极限、CLI 超时、revision 冲突和 Host 重启应在专用故障注入环境验证。
+
+## 修改 subagent schema
+
+DSH structured output 只支持一个紧凑 JSON Schema 子集：
+
+```text
+type, oneOf, properties, required, additionalProperties,
+items, enum, const, and annotation keywords
+```
+
+不要加入 `maxItems` 等不受支持关键字。`assertDshOutputSchema()` 会在启动 worker 前递归拒绝未知 schema 键；结果数量等限制由 persona 和 Host parser 双重实现。
+
+## 修改存储格式
+
+Runtime、Documents 和 Memory Space registry 都带版本字段或固定结构。修改时需要：
+
+1. 明确旧格式解析策略；
+2. 增加迁移或拒绝路径；
+3. 保证临时文件与原子 rename；
+4. 补充并发和损坏输入测试；
+5. 更新中英文存储、运维和 Roadmap 文档；
+6. 在复制的数据根上完成升级/回退验证。
+
+当前没有正式 schema migration 框架，不应静默改变持久格式。
+
+## 文档国际化维护
+
+`docs/zh-CN` 与 `docs/en` 应保持同名文件和相同章节职责。修改默认值、流程或限制时：
+
+- 同步两种语言；
+- 保持命令、配置键、路径和代码符号完全一致；
+- 使用相对路径互链对应语言页面；
+- 架构总览优先使用可访问、无脚本和无外部资源的 SVG；目录树、命令、公式与短协议仍使用可复制的 `text` / ASCII；
+- 根 README 只保留摘要，把细节放到单一权威 docs 页面。
+
+Web locale 变更时，中文键集合仍是类型事实源；英文词典必须满足 `Record<MnemonKey, string>`，并保持占位符一致。
+
+## 发布检查
+
+```text
+[ ] pnpm run verify
+[ ] review source and generated lib diffs
+[ ] validate package file list includes README.en.md and docs
+[ ] install the built/local bundle into an isolated Web profile
+[ ] run real Mnemon CLI and WebUI smoke tests
+[ ] verify Chinese and English workspaces
+[ ] verify global/workspace/custom paths as applicable
+[ ] record tested DSH and Mnemon versions
+[ ] back up any data root used for upgrade testing
+```
+
+`package.json.files` 当前发布 `lib`、patch、两份根 README、双语公开 docs 和 License；历史研究台账不进入安装包。
+
+## 发布到 npm
+
+发布后 `dsh plugin --profile web add dsh-mnemon` 即按 registry 名称解析（与 dsh-better-sidebar 同路径）。发布步骤：
+
+```sh
+npm pack --dry-run                 # 检查 tarball 文件清单（含 cordis.patch.yml、lib、docs）
+pnpm publish --access public       # prepublishOnly 会先跑 pnpm run verify
+```
+
+凭据约定：NPM_TOKEN 只写入用户级 `~/.npmrc`（`npm config set "//registry.npmjs.org/:_authToken" "${NPM_TOKEN}" --userconfig ~/.npmrc`），发布后删除。**不要**把凭据行提交进仓库 `.npmrc`：pnpm 11 出于安全会忽略项目级 `.npmrc` 中未展开的环境变量凭据并告警，且该文件会随仓库传播。
+
+2FA 注意：若 npm 账号开启发布级两步验证，交互发布直接执行 `pnpm publish --access public`，按提示输入 OTP；脚本/CI 发布需改用 Classic **Automation** 令牌或允许 bypass 2FA 的 Granular 令牌（`npm login` 生成的普通令牌无法发布，会报 403 Two-factor authentication required）。
+
+发布前核对 `package.json` 的 `repository`/`homepage`/`bugs` 指向 `omdsh-dev/dsh-mnemon`（npm 页面与 GitHub 保持一致），并确认版本号已递增。

package/docs/zh-CN/getting-started.md

@@ -0,0 +1,147 @@
+# 快速开始
+
+**简体中文** | [English](../en/getting-started.md) | [文档中心](./README.md)
+
+## 1. 前置条件
+
+你需要：
+
+- 一个可以启动的 DSH Web profile；
+- 本地可执行的 `mnemon` CLI；
+- 可用于受限子任务的 DSH subagent provider。
+
+provider 的准确要求如下：
+
+```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
+```
+
+插件没有在代码中声明固定的 DSH/Mnemon 最低版本矩阵。升级前应先在隔离数据目录中运行本页的验证步骤。
+
+## 2. 安装 Mnemon
+
+macOS 推荐 Homebrew Cask：
+
+```sh
+brew install --cask mnemon-dev/tap/mnemon
+```
+
+macOS 或 Linux 也可以通过 Go 安装：
+
+```sh
+go install github.com/mnemon-dev/mnemon@latest
+```
+
+验证二进制：
+
+```sh
+mnemon --version
+```
+
+如果还要直接检查上游 Store，可以运行 `mnemon status`。该命令会打开有效 Store，可能初始化默认数据或执行迁移；不要把它当作完全无副作用的安装探测。
+
+如果 DSH 无法从 `PATH` 找到它，可以设置 `MNEMON_CLI_PATH`，或在 `mnemon.cliPath` 中配置绝对路径。
+
+## 3. 安装插件
+
+安装到 Web profile：
+
+```sh
+dsh plugin --profile web add dsh-mnemon
+```
+
+未发布到 npm 的预发布版本可从 git 安装：
+
+```sh
+dsh plugin --profile web add "github:omdsh-dev/dsh-mnemon"
+```
+
+本地开发检出：
+
+```sh
+dsh plugin --profile web add "link:/absolute/path/to/dsh-mnemon"
+```
+
+插件包中的 `cordis.patch.yml` 会挂载 Host 插件；Web client bundle 会注册会话工作台和插件设置卡。
+
+## 4. 选择存储范围
+
+启动 DSH Web profile：
+
+```sh
+dsh --profile web
+```
+
+在“设置 -> 插件配置 -> Mnemon”选择：
+
+| 范围 | 根目录 | 适合场景 |
+|---|---|---|
+| `global` | `MNEMON_DATA_DIR` 或 `~/.mnemon` | 多个工作区共享同一套记忆 |
+| `workspace` | DSH Host 启动目录下的 `.mnemon` | 项目隔离 |
+| `custom` | `dataDir` | 显式磁盘、挂载卷或专用数据目录 |
+
+设置写入 `$DSH_HOME/settings.yaml`，重启 DSH 后应用。切换范围不会搬运旧数据；需要保留时先停止写入并手工复制整个旧根目录。
+
+## 5. 创建第一个记忆体
+
+进入任意会话的“记忆系统”Tab：
+
+1. 打开“记忆体”页。
+2. 创建一个主题明确的记忆体，例如“项目决策”。
+3. description 应说明“哪些内容属于这里，以及什么任务应召回它”。
+4. 开启读取开关，或在第一次写入后让插件自动激活它。
+
+空白记忆体默认可以保持未激活。激活只控制读取范围；写入可以选择任意已登记记忆体，写入成功后会自动激活目标。
+
+## 6. 验证完整链路
+
+先检查确定性状态：
+
+```text
+/mnemon status
+```
+
+再在“沉淀”页提交一条稳定、自包含、未来仍有用的内容。worker 会选择记忆体、查重并返回结构化回执。随后验证：
+
+```text
+/mnemon recall <一个能命中新内容的聚焦查询>
+```
+
+最后检查：
+
+- “记忆体”页能看到已激活记忆体和图谱；
+- “内容”能看到写入项及所属记忆体；
+- “状态”中 CLI、运行时、记忆体目录和 subagent 均正常；
+- 召回结果包含完整 `memoryBodyId` 和记忆 ID。
+
+## 7. 推荐的第一次真实对话
+
+选择一个确实依赖历史决策的问题，而不是要求模型无条件调用记忆工具。预期流程是：
+
+```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
+```
+
+普通聊天不应强制召回。当前请求、现有源文件和实时工具结果应优先于历史内容。
+
+## 8. 下一步
+
+- 阅读[存储模型](./storage-model.md)，再决定 `storageScope`。
+- 阅读[配置参考](./configuration.md)，配置只读模式或关闭生命周期提示。
+- 阅读[运维指南](./operations.md)，建立备份和升级前验证流程。

package/docs/zh-CN/interfaces.md

@@ -0,0 +1,159 @@
+# WebUI、工具、命令与 RPC
+
+**简体中文** | [English](../en/interfaces.md) | [文档中心](./README.md)
+
+## Web 工作台
+
+主要 Web 界面跟随 DSH 全局语言和明暗主题。顶部导航分为三组，组间以分隔线呈现：「状态」独立成第一组；「运行时、记忆体、档案」对应三层存储；「沉淀、检索、实体、内容」为读写工具。默认进入「状态」页。
+
+| 页面 | 用途 | 调用边界 |
+|---|---|---|
+| 状态 | CLI、运行时热记忆、存储域、记忆体、Documents、生命周期和 worker 诊断 | 聚合读取 |
+| 运行时 | 查看和维护 USER / MEMORY 热记忆及容量 | 普通 mutation 确定性；容量维护可启动 worker |
+| 记忆体 | 记忆体目录、激活开关与元信息编辑、多空间实时图谱、节点检查 | 确定性 RPC 读取；开关与元信息编辑为写 RPC |
+| 档案 | 搜索、阅读、创建、更新、归档 Documents | 搜索/编辑走控制层；归档启动 worker |
+| 沉淀 | 让记忆 worker 选择范围、查重并写入；支持高级约束 | `spawn` 语义写入 |
+| 检索 | smart / keyword / basic 直连召回；可选证据限定 Agent 答案 | 直接服务读取；Agent 答案使用无工具 worker |
+| 实体 | 高频实体和实体相关上下文 | 直接服务读取 |
+| 内容 | 无 recall 副作用地浏览已激活记忆体、复制、克隆或软删除 | 图谱读取；删除走 worker |
+
+图谱每 15 秒同步一次，也可以手动刷新。自然布局、均匀重置、拖拽和键盘微调只影响客户端展示，不修改 Mnemon 数据。
+
+## 模型工具
+
+### 只读工具
+
+| 工具 | 用途 | Root Agent 路径 |
+|---|---|---|
+| `mnemon_memory_bodies` | 读取 Memory Space 目录和统计 | 直接服务 |
+| `mnemon_recall` | 从一个或多个 active spaces 召回 | `spawn` recall worker |
+| `mnemon_related` | 从已知 ID 遍历关系 | `spawn` related worker；root 路径固定请求两跳 |
+| `mnemon_status` | CLI、配置和 active spaces 聚合状态 | 直接服务 |
+| `mnemon_document_search` | 确定性搜索受管 Documents | 直接 Documents 控制层 |
+
+这里的“只读”表示不修改受管正文或长期语义内容。`mnemon_document_search` 命中后仍会更新 `lastAccessedAt` 并重写 Document index，用于 LRU 排序。
+
+### `writeEnabled=true` 时的工具
+
+| 工具 | 用途 | Root Agent 路径 |
+|---|---|---|
+| `mnemon_runtime_memory` | `add` / `replace` / `remove` 热记忆 | 确定性控制层；add 溢出时 worker |
+| `mnemon_document_manage` | 创建、更新或归档 Document | 创建/更新确定性；归档 worker |
+| `mnemon_remember` | 长期沉淀一条洞察 | `spawn` write worker |
+| `mnemon_link` | 建立 typed relationship | `spawn` write worker |
+| `mnemon_forget` | 按精确 ID 软删除 | `spawn` write worker |
+| `mnemon_memory_body_create` | 创建独立 Memory Space | `spawn` write worker |
+| `mnemon_memory_body_update` | 更新名称、description、active | `spawn` write worker |
+| `mnemon_memory_body_merge` | 非破坏性导入合并 | `spawn` write worker |
+
+worker 内调用同名工具时直接到服务层，不再委派。
+
+## 工具准入建议
+
+- 热记忆：用户明确偏好、稳定项目约定、环境事实和高频经验。
+- Document：形成完整结构和理由的设计、调查、流程或交接。
+- 长期 Memory Space：明确要求跨任务保留，或适合图关系和深召回的稳定洞察。
+- 跳过：问题、猜测、临时进度、完成日志、原始输出、秘密、可轻易重新发现的仓库事实。
+
+`mnemon_forget` 是破坏性语义操作，只有用户明确要求或内容已被验证错误/过时时才应执行。
+
+## `/mnemon` 命令
+
+```text
+/mnemon
+/mnemon status
+/mnemon recall <查询>
+/mnemon related <完整记忆 ID>
+/mnemon remember <内容>
+/mnemon forget <精确 ID>
+```
+
+- 空 `/mnemon` 等价于 `status`。
+- `status` 确定性读取，不启动模型。
+- `recall`、`related`、`remember` 和 `forget` 使用命令所在 live Agent 作为 worker parent。
+- 命令 recall 最多返回 10 条。
+- `forget` 参数必须是一个不含空格的精确 ID。
+- 当前命令帮助和结果主要为中文，尚未跟随 Web locale。
+
+## RPC 通道
+
+RPC 是 DSH Host 与本插件 Web client 的内部桥，不是承诺稳定的外部 HTTP API。
+
+### 读通道
+
+```text
+channel:   /dsh-mnemon-read
+authority: trusted-host
+```
+
+| Endpoint | 行为 |
+|---|---|
+| `runtime-memory` | Runtime 快照 |
+| `status` | 服务、生命周期、Documents 和存储域聚合状态 |
+| `documents` | Document 目录快照 |
+| `document` | 读取一份 Document |
+| `document-search` | 确定性搜索，命中会更新 LRU 元数据 |
+| `graph` | 聚合 active Memory Spaces 图谱 |
+| `bodies` | Memory Space 目录 |
+| `list` | 内容列表 |
+| `entities` | 实体统计或实体相关上下文 |
+| `search` | 直接 Mnemon 检索 |
+| `agent-search` | 直接检索后做证据限定回答 |
+| `related` | 直接关系遍历 |
+
+### 写通道
+
+```text
+channel:   /dsh-mnemon-write
+authority: loopback
+```
+
+| Endpoint | 行为 |
+|---|---|
+| `runtime-memory` | 热记忆 mutation |
+| `supervise` | Tab 候选交给记忆 worker |
+| `document` | create / update / archive |
+| `remember` | 带可选高级约束的语义写入 |
+| `link` | 建立关系 |
+| `forget` | 软删除 |
+| `body-create` | 创建 Memory Space |
+| `body-update` | 更新元数据或 active |
+
+`writeEnabled=false` 时整个写通道不注册。
+
+### 设置通道
+
+```text
+channel:   /dsh-mnemon-settings
+authority: loopback
+endpoints: get, mutate
+```
+
+mutation 使用 settings revision 防止覆盖并发编辑。
+
+## npm 导出
+
+根包公开 Host 侧组合与核心类：
+
+```text
+apply
+Config / resolveConfig
+createRunner
+MnemonService
+RuntimeMemoryController
+DocumentManager
+StorageScopeInspector
+MnemonSubagentCoordinator
+MnemonLifecycle
+```
+
+`dsh-mnemon/client` 用于 DSH client bundle 的 `apply` 与 `inject`。`MnemonClient` 和 RPC endpoint 当前属于内部实现，不应当作稳定公共 SDK。
+
+## 国际化范围
+
+Web 词典保持中文/英文键一一对应，品牌名、工具名和配置键不翻译。尚未完整国际化的表面包括：
+
+- `/mnemon` 命令输出；
+- 模型工具展示卡标题；
+- 部分 Host 校验和诊断错误；
+- 兼容发现旧 Store 时写入的默认名称和说明。