dsh-mnemon 0.1.0

package/docs/en/workflows.md

@@ -0,0 +1,290 @@
+# 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

@@ -0,0 +1,39 @@
+# dsh-mnemon 文档中心
+
+**简体中文** | [English](../en/README.md) | [返回项目首页](../../README.md)
+
+这组文档以当前代码实现为事实源。根 README 用于快速理解；这里展开设计理由、边界、事务流程、配置和运维方式。
+
+## 建议阅读路径
+
+1. [项目介绍](./project-overview.md)：项目定位、Mnemon 与 DSH 的集成边界、三层模型、总体架构与适用场景。
+2. [快速开始](./getting-started.md)：安装、首次配置与基本验证。
+3. [架构设计](./architecture.md)：DSH Host、Web Client、控制层、子 Agent 与 Mnemon CLI 的边界。
+4. [存储与三层记忆模型](./storage-model.md)：Runtime、Documents、Memory Spaces 的语义和目录结构。
+5. [生命周期与核心流程](./workflows.md)：召回、写入、后台审查、容量整理和归档。
+6. [配置参考](./configuration.md)：全部配置、默认值、优先级和 provider 要求。
+7. [WebUI、工具、命令与 RPC](./interfaces.md)：所有用户与模型入口。
+8. [运维、安全与故障排查](./operations.md)：锁、权限、备份、恢复和已知限制。
+9. [开发与验证](./development.md)：模块结构、测试、构建和发布检查。
+10. [Roadmap](./roadmap.md)：尚未完成的可靠性、运维和国际化工作。
+
+## 术语
+
+| 中文 | English | 含义 |
+|---|---|---|
+| 记忆体 | Memory Space | 一个 Mnemon 原生命名 Store 及其独立 `mnemon.db` |
+| 运行时热记忆 | Runtime Memory / hot memory | 每轮直接注入的紧凑用户画像和工作记忆 |
+| 项目档案 | Project Documents | 由插件托管的完整 Markdown 项目知识 |
+| 活跃档案 | Active Document | 参与默认近场检索的档案 |
+| 归档 | Archive | 已建立长期索引、不计 active 容量的原文 |
+| 沉淀 | Distill / supervised writeback | 经 LLM 判断、查重和路由后的持久写入 |
+| 召回 | Recall | 从已激活记忆体读取历史证据 |
+
+品牌名、命令、工具名、配置键、RPC endpoint 和代码符号保持原样，不翻译。
+
+## 文档边界
+
+- 当前用户指令和仓库事实高于历史记忆。
+- `state/` 目前是预留目录；后台审查水位仍只存在于 Host 进程内。
+- 主要 Web 工作台已提供中文和英文；命令输出、工具卡和部分后端诊断尚未全部国际化。
+- `docs/sedimentation-research.md` 是历史研究记录，不是规范或用户手册。

package/docs/zh-CN/architecture.md

@@ -0,0 +1,129 @@
+# 架构设计
+
+**简体中文** | [English](../en/architecture.md) | [文档中心](./README.md)
+
+## 定位
+
+`dsh-mnemon` 是 DSH 与 Mnemon 之间的集成和监督层，不是新的数据库引擎：
+
+- DSH 提供主 Agent、生命周期事件、subagent provider、工具、命令、设置和 Web 扩展点；
+- 插件提供三层知识控制面、路由策略、事务屏障和 UI；
+- 本地 `mnemon` CLI 提供命名 Store、SQLite 持久化、四类图、召回、关系和软删除。
+
+## 组件图
+
+[![dsh-mnemon 运行时架构](./assets/project-architecture.svg)](./assets/project-architecture.svg)
+
+图中实线表示确定性数据或控制路径，紫色虚线表示 LLM 监督路径。Runtime Memory 和 Documents 直接使用受管文件；只有 Memory Spaces 通过 `MnemonRunner` 调用本地 Mnemon CLI。点击图片可以查看原始 SVG。
+
+## 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。
+
+## 两类子 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 |

package/docs/zh-CN/assets/project-architecture.svg

@@ -0,0 +1,182 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="1040" viewBox="0 0 1600 1040" role="img" aria-labelledby="title description" lang="zh-CN">
+  <title id="title">dsh-mnemon 运行时架构</title>
+  <desc id="description">DSH Web、主 Agent 和工具命令进入 dsh-mnemon 控制与监督层，再分别连接运行时热记忆、项目档案和 Mnemon 长期记忆体。</desc>
+  <style>
+    text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans CJK SC", "Microsoft YaHei", sans-serif; fill: #172033; }
+    .canvas { fill: #f7f9fc; }
+    .section { fill: #f0f3f8; stroke: #d7deea; stroke-width: 1.5; }
+    .card { fill: #ffffff; stroke: #d7deea; stroke-width: 1.5; filter: url(#shadow); }
+    .card-hot { fill: #fff3df; stroke: #c66a09; }
+    .card-doc { fill: #e8f1ff; stroke: #2563be; }
+    .card-long { fill: #e2f7ef; stroke: #087c5b; }
+    .title { font-size: 34px; font-weight: 720; letter-spacing: -0.6px; }
+    .subtitle { font-size: 17px; fill: #647086; }
+    .section-title { font-size: 17px; font-weight: 700; fill: #6558d9; letter-spacing: 0.4px; }
+    .node-title { font-size: 21px; font-weight: 700; }
+    .node-copy { font-size: 15px; fill: #647086; }
+    .node-code { font-family: "SFMono-Regular", Consolas, monospace; font-size: 14px; fill: #647086; }
+    .store-title { font-size: 23px; font-weight: 740; }
+    .store-copy { font-size: 15px; fill: #647086; }
+    .pill { fill: #f0f3f8; stroke: #d7deea; }
+    .pill-text { font-size: 13px; font-weight: 650; fill: #647086; }
+    .flow { fill: none; stroke: #aeb9ca; stroke-width: 2.5; marker-end: url(#arrow); }
+    .flow-hot { stroke: #c66a09; marker-end: url(#arrow-hot); }
+    .flow-doc { stroke: #2563be; marker-end: url(#arrow-doc); }
+    .flow-long { stroke: #087c5b; marker-end: url(#arrow-long); }
+    .flow-supervised { stroke: #6558d9; stroke-dasharray: 8 7; marker-end: url(#arrow-accent); }
+    .flow-label { font-size: 13px; font-weight: 650; fill: #647086; }
+    .legend { font-size: 13px; fill: #647086; }
+    .legend-line, .bus-line { marker-end: none; }
+    .bar-hot { fill: #c66a09; }
+    .bar-doc { fill: #2563be; }
+    .bar-long { fill: #087c5b; }
+  </style>
+  <defs>
+    <filter id="shadow" x="-10%" y="-20%" width="120%" height="150%">
+      <feDropShadow dx="0" dy="7" stdDeviation="10" flood-color="#21314d" flood-opacity="0.08"/>
+    </filter>
+    <marker id="arrow" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#aeb9ca"/>
+    </marker>
+    <marker id="arrow-hot" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#c66a09"/>
+    </marker>
+    <marker id="arrow-doc" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#2563be"/>
+    </marker>
+    <marker id="arrow-long" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#087c5b"/>
+    </marker>
+    <marker id="arrow-accent" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#6558d9"/>
+    </marker>
+  </defs>
+
+  <rect class="canvas" width="1600" height="1040" rx="24"/>
+  <text class="title" x="64" y="58">dsh-mnemon 运行时架构</text>
+  <text class="subtitle" x="64" y="87">DSH 负责监督与编排 · Mnemon 负责确定性长期存储 · 三层数据保留在本地</text>
+  <rect class="section" x="48" y="300" width="1504" height="394" rx="24"/>
+
+  <g aria-label="DSH 交互入口">
+    <rect class="card" x="64" y="124" width="430" height="126" rx="18"/>
+    <rect class="pill" x="88" y="146" width="96" height="27" rx="13.5"/>
+    <text class="pill-text" x="136" y="165" text-anchor="middle">DSH WEB</text>
+    <text class="node-title" x="88" y="204">记忆体工作台与插件设置</text>
+    <text class="node-copy" x="88" y="231">八个页面 · 中文/英文 · 全局明暗主题</text>
+
+    <rect class="card" x="585" y="124" width="430" height="126" rx="18"/>
+    <rect class="pill" x="609" y="146" width="112" height="27" rx="13.5"/>
+    <text class="pill-text" x="665" y="165" text-anchor="middle">ROOT AGENT</text>
+    <text class="node-title" x="609" y="204">当前任务与主上下文</text>
+    <text class="node-copy" x="609" y="231">当前指令和实时事实始终优先</text>
+
+    <rect class="card" x="1106" y="124" width="430" height="126" rx="18"/>
+    <rect class="pill" x="1130" y="146" width="142" height="27" rx="13.5"/>
+    <text class="pill-text" x="1201" y="165" text-anchor="middle">TOOLS · COMMANDS</text>
+    <text class="node-title" x="1130" y="204">模型工具与 /mnemon 命令</text>
+    <text class="node-copy" x="1130" y="231">显式召回、沉淀、关系、状态与维护</text>
+  </g>
+
+  <g aria-hidden="true">
+    <path class="flow" d="M279 250 V281 H1298 V350"/>
+    <path class="flow flow-supervised" d="M800 250 V350"/>
+    <path class="flow" d="M1321 250 V292 H800 V350"/>
+    <text class="flow-label" x="1042" y="276">typed RPC</text>
+    <text class="flow-label" x="815" y="302">工具调用</text>
+  </g>
+
+  <text class="section-title" x="80" y="337">DSH HOST · DSH-MNEMON 控制与监督层</text>
+
+  <g aria-hidden="true">
+    <path class="flow bus-line" d="M300 476 V498"/>
+    <path class="flow flow-supervised bus-line" d="M800 476 V498"/>
+    <path class="flow bus-line" d="M1300 476 V498"/>
+    <path class="flow bus-line" d="M245 498 H1300"/>
+    <path class="flow" d="M245 498 V520"/>
+    <path class="flow" d="M615 498 V520"/>
+    <path class="flow" d="M985 498 V520"/>
+    <path class="flow" d="M990 630 H1190"/>
+  </g>
+
+  <g aria-label="监督与权限组件">
+    <rect class="card" x="100" y="350" width="400" height="126" rx="17"/>
+    <text class="node-title" x="126" y="390">Prompt 与 Lifecycle</text>
+    <text class="node-copy" x="126" y="420">热记忆注入 · 短提示 · 活动评分</text>
+    <text class="node-code" x="126" y="448">pre-step · turn/end · idle review</text>
+
+    <rect class="card" x="600" y="350" width="400" height="126" rx="17"/>
+    <text class="node-title" x="626" y="390">Subagent Coordinator</text>
+    <text class="node-copy" x="626" y="420">spawn 隔离任务 · fork 已完成 checkpoint</text>
+    <text class="node-code" x="626" y="448">persona · allowlist · schema · depth=1</text>
+
+    <rect class="card" x="1100" y="350" width="400" height="126" rx="17"/>
+    <text class="node-title" x="1126" y="390">RPC 与权限边界</text>
+    <text class="node-copy" x="1126" y="420">trusted-host 读取 · loopback 写入</text>
+    <text class="node-code" x="1126" y="448">read · write · settings channels</text>
+  </g>
+
+  <g aria-label="确定性控制组件">
+    <rect class="card" x="80" y="520" width="330" height="110" rx="16"/>
+    <text class="node-title" x="104" y="559">Runtime Memory</text>
+    <text class="node-copy" x="104" y="587">JSON 事实源 · Markdown 投影</text>
+    <text class="node-code" x="104" y="612">lock · revision · UTF-8</text>
+
+    <rect class="card" x="450" y="520" width="330" height="110" rx="16"/>
+    <text class="node-title" x="474" y="559">Documents</text>
+    <text class="node-copy" x="474" y="587">索引 · 检索 · active / archived</text>
+    <text class="node-code" x="474" y="612">path boundary · LRU · SHA-256</text>
+
+    <rect class="card" x="820" y="520" width="330" height="110" rx="16"/>
+    <text class="node-title" x="844" y="559">Mnemon Service</text>
+    <text class="node-copy" x="844" y="587">记忆体路由 · 召回 · 关系 · 图谱</text>
+    <text class="node-code" x="844" y="612">active read · targeted write</text>
+
+    <rect class="card" x="1190" y="520" width="280" height="110" rx="16"/>
+    <text class="node-title" x="1214" y="559">CLI Runner</text>
+    <text class="node-copy" x="1214" y="587">参数数组 · 禁用 shell</text>
+    <text class="node-code" x="1214" y="612">serialized · timeout</text>
+  </g>
+
+  <g aria-hidden="true">
+    <path class="flow flow-hot" d="M245 630 V760"/>
+    <path class="flow flow-doc" d="M615 630 V724 H800 V760"/>
+    <path class="flow flow-long" d="M1330 630 V724 H1310 V760"/>
+    <text class="flow-label" x="262" y="718">每轮投影</text>
+    <text class="flow-label" x="632" y="714">受管 Markdown</text>
+    <text class="flow-label" x="1344" y="713">本地 CLI</text>
+  </g>
+
+  <g aria-label="三层本地存储">
+    <rect class="card card-hot" x="64" y="760" width="440" height="194" rx="20"/>
+    <rect class="bar-hot" x="88" y="784" width="9" height="48" rx="4.5"/>
+    <text class="store-title" x="116" y="809">运行时热记忆</text>
+    <text class="node-code" x="116" y="834">&lt;storageRoot&gt;/runtime</text>
+    <text class="store-copy" x="88" y="870">memories.json 是唯一事实源</text>
+    <text class="store-copy" x="88" y="898">USER.md 4 KiB · MEMORY.md 10 KiB</text>
+    <text class="store-copy" x="88" y="926">紧凑内容每轮直接进入主上下文</text>
+
+    <rect class="card card-doc" x="580" y="760" width="440" height="194" rx="20"/>
+    <rect class="bar-doc" x="604" y="784" width="9" height="48" rx="4.5"/>
+    <text class="store-title" x="632" y="809">项目档案</text>
+    <text class="node-code" x="632" y="834">&lt;storageRoot&gt;/documents</text>
+    <text class="store-copy" x="604" y="870">index.json · active/ · archived/</text>
+    <text class="store-copy" x="604" y="898">保留完整 Markdown 叙事与来源</text>
+    <text class="store-copy" x="604" y="926">先建立冷引用，再迁移原文</text>
+
+    <rect class="card card-long" x="1096" y="760" width="440" height="194" rx="20"/>
+    <rect class="bar-long" x="1120" y="784" width="9" height="48" rx="4.5"/>
+    <text class="store-title" x="1148" y="809">Mnemon 记忆体</text>
+    <text class="node-code" x="1148" y="834">&lt;storageRoot&gt;/data/&lt;space-id&gt;/mnemon.db</text>
+    <text class="store-copy" x="1120" y="870">独立 SQLite Store · active 读取边界</text>
+    <text class="store-copy" x="1120" y="898">temporal · semantic · causal · entity</text>
+    <text class="store-copy" x="1120" y="926">跨会话、按需、带来源的长期证据</text>
+  </g>
+
+  <g aria-label="图例">
+    <line x1="70" y1="996" x2="112" y2="996" class="flow legend-line"/>
+    <text class="legend" x="124" y="1001">确定性数据 / 控制路径</text>
+    <line x1="346" y1="996" x2="388" y2="996" class="flow flow-supervised legend-line"/>
+    <text class="legend" x="400" y="1001">LLM 监督路径</text>
+    <text class="legend" x="1532" y="1001" text-anchor="end">所有持久数据位于选定 storageRoot</text>
+  </g>
+</svg>