dsh-layered-memory 0.7.0 → 0.8.0

package/README.en.md

@@ -1,56 +1,19 @@
-[简体中文](README.md) | **English**
+<div align="center">
 
-<p align="center">
-  <img src="./assets/img/Hero.png" width="100%"
-       alt="DeepSeek Harness hero banner: conversations distilled into layered memories and recalled before every model step — chat bubbles dissolve into three progressively brighter light layers flowing into a frosted-glass capsule with a glowing orb and gradient track (tick labels: 日常·工作·智能·关闭), with light threads looping back to suggest recall">
-</p>
+<img src="./assets/img/Hero.png" width="100%"
+     alt="DeepSeek Harness hero banner: conversations distilled into layered memories and recalled before every model step — chat bubbles dissolve into three progressively brighter light layers flowing into a frosted-glass capsule with a glowing orb and gradient track (tick labels: 日常·工作·智能·关闭), with light threads looping back to suggest recall">
 
 # dsh-layered-memory
 
-A **layered distillation memory plugin** for DeepSeek Harness (persistent composition
-plugin): conversations are processed in the background through L0 capture → L1 atomic
-memories → L2 scene consolidation → L3 persona distillation, and relevant memories are
-automatically injected into context before every model step — neither the user nor the
-model needs to do anything.
+**A layered distillation memory plugin for DeepSeek Harness: conversations are processed in the background through L0 capture → L1 atomic memories → L2 scene consolidation → L3 persona distillation, and relevant memories are automatically injected into context before every model step — neither the user nor the model needs to do anything.**
 
-> The core memory capabilities of this plugin (the L0–L3 layered distillation pipeline,
-> prompts, and dual-write storage design) are modeled after **MemoryCore** from
-> [TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory):
-> prompts are kept as-is; only the L2/L3 "LLM manipulates files" flow is adapted to
-> "LLM outputs, engineering side executes".
+[简体中文](README.md) · [Latest release](https://github.com/JunNanLYS/dsh-layered-memory/releases/latest) · [Report issues](https://github.com/JunNanLYS/dsh-layered-memory/issues)
 
-## Runtime Data Flow
+[![main 0.7.1](https://img.shields.io/badge/main-0.7.1-6f83ff?style=flat-square)](https://github.com/JunNanLYS/dsh-layered-memory/tree/main)
+[![DSH 0.1.0-rc.6](https://img.shields.io/badge/DSH-0.1.0--rc.6-8b5cf6?style=flat-square)](https://github.com/deepseek-ai/deepseek-harness)
+[![MIT License](https://img.shields.io/badge/license-MIT-536990?style=flat-square)](LICENSE)
 
-<p align="center">
-  <img src="./assets/readme/flow.svg" width="100%"
-       alt="Runtime data flow: session events from User and Assistant (left) flow into the plugin (L0 capture, L1–L3 distillation, retrieval, memory tools), which injects relevant memories into the DeepSeek Harness core (right) at agent/pre-step; distillation reuses the core's ctx.llm and data is dual-written to ~/.dsh/memory/">
-</p>
-
-The plugin attaches to DSH-native event seams (`session/event` for capture,
-`agent/pre-step` for injection), reuses the host's `ctx.llm` for distillation, and stays
-fully transparent to both user and model. It also registers three model-callable memory
-tools: `memory_search` / `conversation_search` / `memory_read_scene`.
-
-## Layered Memory (L0–L3)
-
-<p align="center">
-  <img src="./assets/img/Layers.png" width="100%"
-       alt="Four memory layers refining from top-left to bottom-right: L0 raw conversation (chat bubbles) → L1 atomic memories (glowing fact particles) → L2 scene blocks (glass document slabs) → L3 core persona (radiant crystal core); stages connected by LLM extract/consolidate/distill light beams, shrinking width shows progressive refinement">
-</p>
-
-## Per-Session Memory Modes
-
-<p align="center">
-  <img src="./assets/img/Modes.png" width="100%"
-       alt="Per-session memory modes: a glass capsule track with four stops (日常 · 工作 · 智能 · 关闭), the glowing orb resting on 智能 (default); a vignette above each — personal chat bubbles for 日常, code/document panes for 工作, two streams merging brightest for 智能, a dim dashed ghost bubble for 关闭">
-</p>
-
-- **Control**: the pill next to the mode selector in the input bar (`Memory · Auto`);
-  clicking opens a macOS-style sliding picker above — release to snap to the nearest
-  mode; adapts to light/dark themes;
-- Each session's choice is persisted by sessionId to `session-modes.json`, surviving
-  restarts/session restore; stacks with the global switches (global is the master gate);
-  L2/L3 are fully family-isolated — content never leaks across families.
+</div>
 
 ## Getting Started
 
@@ -58,7 +21,7 @@ Requires Node ≥ 22.16. Two invocation styles — the `npx` prefix can replace
 any command below:
 
 ```bash
-# Option 1: run the official CLI directly via npx (no pre-installed dsh; version can be pinned, e.g. dsh-layered-memory@0.6.1)
+# Option 1: run the official CLI directly via npx (no pre-installed dsh; version can be pinned, e.g. dsh-layered-memory@0.7.1)
 npx -y @deepseek-ai/dsh plugin --profile web add dsh-layered-memory
 
 # Option 2: with the dsh CLI installed (dsh is a pnpm forwarder; npm i -g pnpm first if missing)
@@ -69,6 +32,24 @@ dsh plugin --profile web add https://github.com/JunNanLYS/dsh-layered-memory
 dsh plugin --profile web add /path/to/dsh-layered-memory
 ```
 
+### Install via an AI Agent (Recommended)
+
+If your current agent can run terminal commands, send it this message as-is:
+
+```text
+Please install the dsh-layered-memory plugin for the web profile of DeepSeek Harness.
+
+Run only the two commands below and do not modify any other profile:
+dsh plugin --profile web add dsh-layered-memory
+dsh --profile web --dump-config
+
+Confirm that dsh-layered-memory appears in the output, then report the result to me.
+Do not close or restart my running DSH yourself; after installation, remind me to manually restart the DSH Web Host.
+```
+
+The agent should report the installation result and explicitly tell you whether
+`dsh-layered-memory` has appeared in the configuration.
+
 This package declares a `dsh.bundle` composition layer (`cordis.patch.yml`); after
 installation the **plugin entry is mounted automatically** — no need to hand-edit
 `$DSH_HOME/profiles/web/cordis.patch.yml`. Then restart DeepSeek Harness and verify:
@@ -95,6 +76,63 @@ npm run smoke                         # smoke test (rebuild first: see command b
 npx tsc src/smoke.ts --outDir dist-smoke --module nodenext --moduleResolution nodenext --target es2022 --strict --skipLibCheck --esModuleInterop
 ```
 
+## Runtime Data Flow
+
+<p align="center">
+  <img src="./assets/readme/flow.svg" width="100%"
+       alt="Runtime data flow: session events from User and Assistant (left) flow into the plugin (L0 capture, L1–L3 distillation, retrieval, memory tools), which injects relevant memories into the DeepSeek Harness core (right) at agent/pre-step; distillation reuses the core's ctx.llm and data is dual-written to ~/.dsh/memory/">
+</p>
+
+The plugin attaches to DSH-native event seams (`session/event` for capture,
+`agent/pre-step` for injection) and reuses the host's `ctx.llm` for distillation. Recall
+is presented as **message-side injection**: relevant memories enter the conversation as a
+synthetic message placed right before the user's new message, rendered as a
+**"Context injection · memory"** row in the chat flow (expand to see the hits) — so you
+can see "memory at work" directly. Injected content is bounded by length and
+time budgets — oversized lines are truncated (pointing the model at the memory tools for
+the full text) and a timed-out recall silently skips that turn, never slowing the chat. It
+also registers three model-callable memory tools: `memory_search` /
+`conversation_search` / `memory_read_scene`.
+
+In action: the "Context injection · memory" row surfaces relevant memories first, and
+the model then calls `memory_read_scene` directly to read scene blocks before answering
+from memory:
+
+<p align="center">
+  <img src="./assets/img/MemoryTools.png" width="60%"
+       alt="Real conversation UI (light theme): a "Context injection · memory" row sits above the user's message asking about recent plans; the assistant lists 4 memory_read_scene tool calls (with scene-block .md filenames as arguments) before answering from memory">
+</p>
+
+In restricted sessions where only the code-execution entry point is available, the model
+reaches the memory tools indirectly through `run_code` (nested as SUBTOOL calls in the
+trajectory view):
+
+<p align="center">
+  <img src="./assets/img/ToolTrajectory.png" width="80%"
+       alt="Tool-call trajectory view: a colored timeline on top and a step list on the left (SYSTEM/CONTEXT/USER/ASSISTANT/TOOL/SUBTOOL tags); a run_code tool step nests 5 memory_read_scene sub-tool calls (SUBTOOL tags), with a detail panel for the selected step on the right">
+</p>
+
+## Layered Memory (L0–L3)
+
+<p align="center">
+  <img src="./assets/img/Layers.png" width="100%"
+       alt="Four memory layers refining from top-left to bottom-right: L0 raw conversation (chat bubbles) → L1 atomic memories (glowing fact particles) → L2 scene blocks (glass document slabs) → L3 core persona (radiant crystal core); stages connected by LLM extract/consolidate/distill light beams, shrinking width shows progressive refinement">
+</p>
+
+## Per-Session Memory Modes
+
+<p align="center">
+  <img src="./assets/img/Modes.png" width="100%"
+       alt="Per-session memory modes: a glass capsule track with four stops (日常 · 工作 · 智能 · 关闭), the glowing orb resting on 智能 (default); a vignette above each — personal chat bubbles for 日常, code/document panes for 工作, two streams merging brightest for 智能, a dim dashed ghost bubble for 关闭">
+</p>
+
+- **Control**: the pill next to the mode selector in the input bar (`Memory · Auto`);
+  clicking opens a macOS-style sliding picker above — release to snap to the nearest
+  mode; adapts to light/dark themes;
+- Each session's choice is persisted by sessionId to `session-modes.json`, surviving
+  restarts/session restore; stacks with the global switches (global is the master gate);
+  L2/L3 are fully family-isolated — content never leaks across families.
+
 ## UI Preview
 
 <p align="center">
@@ -128,8 +166,9 @@ the bundle layer appends and causes `duplicate loader entry id` startup failure)
 | `capture.stripCodeBlocks` | `true` | Strip code blocks from assistant messages |
 | `capture.maxMessageChars` | `4000` | Max characters per message |
 | `extract.enabled` | `true` | L1 extraction |
-| `extract.minMessages` | `1` | Run L1 extraction after N new messages accumulate |
-| `extract.backgroundMessages` | `10` | Background messages attached to extraction |
+| `extract.minMessages` | `6` | Steady-state trigger threshold: run L1 extraction once a session accumulates N new messages. The effective threshold ramps up 1→2→4→…→N (first turn yields memories immediately, then batches to save calls) |
+| `extract.idleSeconds` | `300` | Idle flush: distill a session's pending slice after N seconds of silence (catches "user left before reaching the threshold"); `0` disables |
+| `extract.backgroundMessages` | `10` | Background messages attached to extraction (fetched per session from L0 — no cross-session contamination) |
 | `extract.candidatePool` | `5` | Dedup candidate pool size |
 | `l2.enabled` | `true` | L2 scene consolidation |
 | `l2.minNewMemories` | `5` | New-memory threshold since last L2 consolidation |
@@ -138,7 +177,12 @@ the bundle layer appends and causes `duplicate loader entry id` startup failure)
 | `l3.enabled` | `true` | L3 persona distillation |
 | `l3.interval` | `20` | L3 distillation interval (new-memory count) |
 | `recall.enabled` | `true` | Auto recall |
-| `recall.maxResults` | `5` | L1 records injected per step |
+| `recall.maxResults` | `5` | Max L1 records injected before each new user message |
+| `recall.maxCharsPerMemory` | `500` | Per-memory character cap for injected recall (overlong lines truncated with a hint to use the memory tools for the full text); `0` disables |
+| `recall.maxTotalRecallChars` | `2000` | Total character cap per injected recall batch (lowest-ranked tail dropped first); `0` disables |
+| `recall.timeoutMs` | `5000` | Overall recall budget (ms): a timed-out recall skips that turn without blocking the chat; `0` disables |
+| `recall.includePersona` | `true` | Inject persona context into the system prompt (`<user-persona>`, stable zone) |
+| `recall.includeSceneNav` | `true` | Inject scene navigation into the system prompt (`<scene-navigation>`, stable zone) |
 | `recall.strategy` | `hybrid` | Retrieval strategy: `keyword` / `embedding` / `hybrid` |
 | `recall.scoreThreshold` | `0.3` | Recall score threshold (below is not injected; applies to keyword/embedding only, not pre-fusion hybrid; tool path unfiltered) |
 | `embedding.enabled` | `false` | Vector retrieval switch; off = pure FTS |
@@ -146,13 +190,16 @@ the bundle layer appends and causes `duplicate loader entry id` startup failure)
 | `embedding.apiKey` | empty | API key |
 | `embedding.model` | empty | embedding model name |
 | `embedding.dimensions` | `0` | Vector dimensions (required when enabled; must match model output) |
+| `embedding.maxInputChars` | `5000` | Max characters per text (overlong inputs truncated) |
+| `embedding.timeoutMs` | `10000` | Per-call embedding timeout (ms) |
 | `embedding.allowLocalModels` | `true` | Allow the local embedding tier (deployment ceiling; when off, no model downloads and no local tier in settings) |
 | `embedding.mirror` | `https://hf-mirror.com` | Download mirror root for local models (can be changed back to `https://huggingface.co`) |
 | `llm.provider/model` | empty | Distillation model override (defaults to current selection) |
-| `llm.maxTokens` | `256000` | Output token cap per distillation call (unified across stages; a reasoning model's reasoning shares this budget — too low gets fully consumed by thinking, leaving 0 chars of text) |
+| `llm.maxTokens` | `65536` | Fallback output cap for non-layered calls. Each distillation stage has its own budget (extraction 16k / dedup 8k / L2 32k / L3 16k; auto ×4 when reasoning effort is high/max, so thinking can't starve the text budget) |
 | `llm.reasoningEffort` | `off` | Distillation reasoning-effort tier (deployment default): `off` / `high` / `max`; empty string = don't send (follow model default). Distillation is structured extraction, so thinking is off by default — a reasoning model (e.g. v4-flash) at its default `high` tier can consume the entire output budget on thinking, leaving 0 chars of text; set to empty string for models that don't recognize the effort parameter. Switchable at runtime in Settings → Memory → Overview ("follow config" falls back to this value) |
 | `llm.temperature` | `0.3` | Distillation temperature |
 | `llm.maxInputChars` | `700000` | Input character budget per distillation call (over-budget L1 inputs are chunked automatically) |
+| `llm.timeoutMs` | `120000` | Per-call distillation timeout (ms) |
 | `tools` | `true` | Whether to register model-callable memory tools |
 
 ## Storage Layout
@@ -171,20 +218,17 @@ local), switchable at runtime in the settings page — see the next section.
 Pick the embedding source in Settings → Memory → Overview → Semantic Retrieval;
 it takes effect immediately, no config edit or restart:
 
-| Source | Description |
-| --- | --- |
-| **Off** (default) | No vector embedding at all; pure BM25 keyword retrieval |
-| **Remote** | Bring any OpenAI-compatible `/embeddings` service (selectable only when the `embedding.*` quartet is configured) |
-| **Local** | Pick from a built-in model catalog, ONNX-quantized **CPU inference** — no API key, data never leaves the machine |
-
-The local catalog is a built-in allowlist (each model pinned to a revision with
-per-file sha256; arbitrary repos cannot be downloaded):
+<p align="center">
+  <img src="./assets/img/EmbeddingSource.png" width="70%"
+       alt="Semantic retrieval (embedding source) panel in the settings page (light theme): a three-state selector (Off/Local/Remote, Local selected) showing the current source and the first-run runtime install hint; below it the local model catalog lists BGE small Chinese (in use/ready), EmbeddingGemma 300M (download 316MB) and BGE-M3 (download 560MB) with dims/context/size/notes and download buttons">
+</p>
 
-| Model | Dims | Context | Size | Notes |
-| --- | --- | --- | --- | --- |
-| BGE small Chinese | 512 | 512 | ~25MB | Fastest on CPU; good first taste of semantic retrieval |
-| EmbeddingGemma 300M | 768 | 2048 | ~330MB | 100+ languages incl. Chinese; balanced quality/cost (same as upstream MemoryCore) |
-| BGE-M3 | 1024 | 8192 | ~590MB | Best Chinese quality; a single embedding can take seconds |
+Three sources: **Off** (default; no vector embedding at all, pure BM25 keyword
+retrieval), **Remote** (bring any OpenAI-compatible `/embeddings` service, selectable
+only when the `embedding.*` quartet is configured), **Local** (pick from a built-in
+model catalog, ONNX-quantized **CPU inference** — no API key, data never leaves the
+machine). The local catalog is a built-in allowlist (each model pinned to a revision
+with per-file sha256; arbitrary repos cannot be downloaded).
 
 - **Download**: one click on the model card (default mirror `hf-mirror.com`, resumable
   downloads + sha256 integrity checks); stored under `models/<id>/` in the data
@@ -216,8 +260,8 @@ of the raw model output; all failure warns carry the first stack frame.
 
 - The full pipeline is embedded (no external Gateway); distillation reuses DSH's own LLM;
 - L2/L3 changed from "LLM manipulates file tools" to "LLM outputs operation JSON / full documents, engineering side executes";
-- Recall injection happens at `agent/pre-step` + agent-scoped `systemPrompt.context` (DSH-native events/services);
-- Storage/retrieval is a single-machine slimmed version of the official sqlite backend (drops multi-tenant isolation columns, TCVDB cloud backend, audit tables; tokenization uses a bundled CJK bigram instead of jieba, keeping zero native dependencies — sqlite-vec is the only native extension, auto-degrading on load failure).
+- Recall injection happens at `agent/pre-step` (message-side synthetic message, the official pre-step replacement semantics) plus agent-scoped `systemPrompt.context` (persona/navigation stable zone — DSH-native events/services);
+- Storage/retrieval is a single-machine slimmed version of the official sqlite backend (drops multi-tenant isolation columns, TCVDB cloud backend, audit tables; tokenization uses jieba like the official one — @node-rs/jieba prebuilt binaries union CJK character bigrams: word tokens give BM25 exact-word hits while bigrams keep sub-word recall; on load failure it falls back to pure bigrams, and FTS indexes are rebuilt automatically via a tokenizer version stamp).
 
 ## Credits
 
@@ -226,6 +270,14 @@ dual-write storage architecture) are modeled after **MemoryCore** from
 [TencentCloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory).
 Thanks to the original project for open-sourcing its design and implementation.
 
+## Roadmap
+
+Features under planning — feedback and priorities welcome in the
+[issue tracker](https://github.com/JunNanLYS/dsh-layered-memory/issues):
+
+- [ ] **Git branch awareness**: associate memories with the current git branch; recall can filter/boost by branch (orthogonal to the existing memory modes)
+- [ ] **Claude Code / Codex memory import**: one-click migration of existing memory assets (`CLAUDE.md`, Claude Code memory files, Codex `AGENTS.md`, etc.), fed into the layered distillation pipeline
+
 ## License
 
 [MIT](LICENSE)

package/README.md

@@ -1,57 +1,26 @@
-**简体中文** | [English](README.en.md)
+<div align="center">
 
-<p align="center">
-  <img src="./assets/img/Hero.png" width="100%"
-       alt="DeepSeek Harness hero 横幅：对话自动分层蒸馏成记忆，模型每步前自动召回注入——右侧对话气泡逐层溶解为三层渐亮光带，流入带发光圆球与渐变轨道的玻璃胶囊（下有 日常·工作·智能·关闭 四档刻度），光丝回流示意召回注入">
-</p>
+<img src="./assets/img/Hero.png" width="100%"
+     alt="DeepSeek Harness hero 横幅：对话自动分层蒸馏成记忆，模型每步前自动召回注入——右侧对话气泡逐层溶解为三层渐亮光带，流入带发光圆球与渐变轨道的玻璃胶囊（下有 日常·工作·智能·关闭 四档刻度），光丝回流示意召回注入">
 
 # dsh-layered-memory
 
-DeepSeek Harness 的**分层蒸馏记忆插件**（持久组合插件）：对话在后台自动完成
-L0 捕获 → L1 原子记忆 → L2 场景整合 → L3 画像蒸馏，模型每一步前自动把相关记忆
-注入上下文——用户与模型都不需要做任何操作。
-
-> 本插件的记忆核心能力（L0–L3 分层蒸馏管线、Prompt 与双写存储设计）参考自
-> [TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
-> 中的 **MemoryCore**：Prompt 原样保留，仅把"LLM 操作文件"的 L2/L3 流程适配为
-> "LLM 输出、工程侧执行"。
-
-## 运行时数据流
-
-<p align="center">
-  <img src="./assets/readme/flow.svg" width="100%"
-       alt="dsh-layered-memory 运行时数据流：左侧 User 与 Assistant 的会话事件流入插件（L0 捕获、L1–L3 蒸馏、检索召回、记忆工具），插件经 agent/pre-step 把相关记忆注入右侧 DSH 核心；蒸馏复用核心的 ctx.llm，数据双写 ~/.dsh/memory/">
-</p>
+**DeepSeek Harness 的分层蒸馏记忆插件：对话在后台自动完成 L0 捕获 → L1 原子记忆 → L2 场景整合 → L3 画像蒸馏，模型每一步前自动把相关记忆注入上下文。**
 
-插件挂在 dsh 原生事件缝上（`session/event` 捕获、`agent/pre-step` 注入），
-蒸馏调用复用宿主 `ctx.llm`，全程对用户与模型透明。另注册三个模型可主动调用的
-记忆工具：`memory_search` / `conversation_search` / `memory_read_scene`。
+[English](README.en.md) · [最新发行版](https://github.com/JunNanLYS/dsh-layered-memory/releases/latest) · [反馈问题](https://github.com/JunNanLYS/dsh-layered-memory/issues)
 
-## 分层记忆（L0–L3）
+[![main 0.7.1](https://img.shields.io/badge/main-0.7.1-6f83ff?style=flat-square)](https://github.com/JunNanLYS/dsh-layered-memory/tree/main)
+[![DSH 0.1.0-rc.6](https://img.shields.io/badge/DSH-0.1.0--rc.6-8b5cf6?style=flat-square)](https://github.com/deepseek-ai/deepseek-harness)
+[![MIT License](https://img.shields.io/badge/license-MIT-536990?style=flat-square)](LICENSE)
 
-<p align="center">
-  <img src="./assets/img/Layers.png" width="100%"
-       alt="分层记忆四层（自左上向右下逐层精炼）：L0 原始对话（对话气泡）→ L1 原子记忆（发光事实粒子）→ L2 场景块（玻璃文档板）→ L3 核心画像（发光晶核）；层间由 LLM 提取/整合/蒸馏光束相连，宽度递减表示数据逐层精炼">
-</p>
-
-## 会话级记忆档位
-
-<p align="center">
-  <img src="./assets/img/Modes.png" width="100%"
-       alt="会话级记忆档位：一条玻璃胶囊滑轨四个停点（日常·工作·智能·关闭），发光圆球停在智能（默认）档；各档上方微场景——日常为个人聊天气泡、工作为代码文档窗格、智能为双流合流最亮、关闭为暗淡虚线幽灵泡">
-</p>
-
-- **控件**：输入栏内、模式选择器右侧的 pill（`记忆·自动`），点击在上方浮出 macOS
-  风格滑动选择器——拖拽松手吸附最近档位；深浅主题自适应；
-- 每会话的选择按 sessionId 持久化到 `session-modes.json`，重启/恢复会话不丢；
-  与全局开关叠加（全局是总闸）；L2/L3 完全分族，间族内容不渗透。
+</div>
 
 ## 快速开始
 
 需要 Node ≥ 22.16。两种调用方式任选（`npx` 前缀可替换下面任何 `dsh` 命令）：
 
 ```bash
-# 方式一：npx 直接跑官方 CLI（无需预装 dsh；可 pin 版本，如 dsh-layered-memory@0.6.1）
+# 方式一：npx 直接跑官方 CLI（无需预装 dsh；可 pin 版本，如 dsh-layered-memory@0.7.1）
 npx -y @deepseek-ai/dsh plugin --profile web add dsh-layered-memory
 
 # 方式二：已装 dsh CLI（dsh 是 pnpm 转发器，未装 pnpm 时先 npm i -g pnpm）
@@ -62,14 +31,28 @@ dsh plugin --profile web add https://github.com/JunNanLYS/dsh-layered-memory
 dsh plugin --profile web add /path/to/dsh-layered-memory
 ```
 
+### 让 Agent 安装（推荐）
+
+如果当前 Agent 可以执行终端命令，把下面这段话完整发送给它：
+
+```text
+请为 DeepSeek Harness 的 web Profile 安装 dsh-layered-memory 插件。
+
+只执行下面两条命令，不要修改其他 Profile：
+dsh plugin --profile web add dsh-layered-memory
+dsh --profile web --dump-config
+
+确认输出中出现 dsh-layered-memory 后告诉我安装结果。
+不要替我关闭或重启正在运行的 DSH；安装完成后提醒我手动重启 DSH Web Host。
+```
+
+Agent 应当返回安装结果，并明确告诉你配置中是否已经出现 `dsh-layered-memory`。
+
 本包声明了 `dsh.bundle` 组合包层（`cordis.patch.yml`），安装后会**自动挂载插件行**——
 不需要再手改 `$DSH_HOME/profiles/web/cordis.patch.yml`。然后重启 DeepSeek Harness，
 验证：`~/.dsh/memory/` 下出现 `conversations/ records/ scenes/` 目录和 `memory.db`
 即插件 apply 成功；设置页出现"记忆"页面、输入栏出现档位 pill 即 client 半边就绪。
 
-> ⚠️ **安全提示**：安装插件 = 以你的权限运行第三方代码。本插件会读取会话内容、
-> 在数据目录写文件、调用你配置的 LLM/embedding 服务；介意请先审查源码（`src/`）。
-
 **卸载**：`dsh plugin --profile web remove dsh-layered-memory` + 重启。数据保留在
 `~/.dsh/memory/`，不需要时手动删除整个目录即可。
 
@@ -84,6 +67,52 @@ npm run smoke                         # 冒烟测试（先重编：见下方命
 npx tsc src/smoke.ts --outDir dist-smoke --module nodenext --moduleResolution nodenext --target es2022 --strict --skipLibCheck --esModuleInterop
 ```
 
+## 运行时数据流
+
+<p align="center">
+  <img src="./assets/readme/flow.svg" width="100%"
+       alt="dsh-layered-memory 运行时数据流：左侧 User 与 Assistant 的会话事件流入插件（L0 捕获、L1–L3 蒸馏、检索召回、记忆工具），插件经 agent/pre-step 把相关记忆注入右侧 DSH 核心；蒸馏复用核心的 ctx.llm，数据双写 ~/.dsh/memory/">
+</p>
+
+插件挂在 dsh 原生事件上（`session/event` 捕获、`agent/pre-step` 注入），蒸馏调用复用宿主 `ctx.llm`。召回以**消息侧注入**呈现：相关记忆作为一条合成消息排在用户新消息之前，会话流里显示为**"上下文注入 · memory"**行（点开看命中内容）——用户能直接看到"记忆生效了"；注入内容有长度预算与时间预算，超限截断/超时跳过，绝不拖慢对话。
+
+**记忆工具(3):**
+- memory_search
+- conversation_search
+- memory_read_scene
+
+真机实录：召回注入与工具调用在对话里的样子——"上下文注入 · memory"行先带出相关记忆，模型再按需调 `memory_read_scene` 读取场景块，凭记忆直接作答：
+
+<p align="center">
+  <img src="./assets/img/MemoryTools.png" width="60%"
+       alt="对话界面实录（浅色主题）：用户消息"我们最近要干什么？"上方可见"上下文注入 · memory"行；助手回答前列出 4 次 memory_read_scene 工具调用（参数为 scenes 场景块的 .md 文件名），随后凭记忆梳理近期目标与推进路线">
+</p>
+
+在只开放代码执行入口的受限会话中，模型经由 `run_code` 间接调用记忆工具（轨迹视图中的 SUBTOOL 嵌套）：
+
+<p align="center">
+  <img src="./assets/img/ToolTrajectory.png" width="80%"
+       alt="工具调用轨迹视图：顶部彩色时间线与左侧步骤列表（SYSTEM/CONTEXT/USER/ASSISTANT/TOOL/SUBTOOL 彩色标签），run_code 工具步骤内嵌套 5 次 memory_read_scene 子工具调用（SUBTOOL 标记），右侧为所选步骤的详情面板">
+</p>
+
+## 分层记忆（L0–L3）
+
+<p align="center">
+  <img src="./assets/img/Layers.png" width="100%"
+       alt="分层记忆四层（自左上向右下逐层精炼）：L0 原始对话（对话气泡）→ L1 原子记忆（发光事实粒子）→ L2 场景块（玻璃文档板）→ L3 核心画像（发光晶核）；层间由 LLM 提取/整合/蒸馏光束相连，宽度递减表示数据逐层精炼">
+</p>
+
+## 会话级记忆档位
+
+<p align="center">
+  <img src="./assets/img/Modes.png" width="100%"
+       alt="会话级记忆档位：一条玻璃胶囊滑轨四个停点（日常·工作·智能·关闭），发光圆球停在智能（默认）档；各档上方微场景——日常为个人聊天气泡、工作为代码文档窗格、智能为双流合流最亮、关闭为暗淡虚线幽灵泡">
+</p>
+
+- **控件**：输入栏内、模式选择器右侧的 pill（`记忆·自动`），点击在上方浮出档位滑块深浅主题自适应；
+- 每会话的选择按 sessionId 持久化到 `session-modes.json`，重启/恢复会话不丢；
+  与全局开关叠加（全局是总闸）；L2/L3 完全分类，分类内容不渗透。
+
 ## 界面预览
 
 <p align="center">
@@ -93,6 +122,40 @@ npx tsc src/smoke.ts --outDir dist-smoke --module nodenext --moduleResolution no
        alt="浅色主题下的同一设置页记忆浏览器概览：同款布局与信息，浅色卡片底与同套强调色，主题切换无需重载">
 </p>
 
+## 存储布局
+
+<p align="center">
+  <img src="./assets/readme/storage.svg" width="100%"
+       alt="存储布局：双写架构（JSONL 事实源只增不改 + memory.db 主检索库）；文件形态含 conversations/records/scenes/persona/state/pending/session-modes/embedding-source/模型目录/推理运行时/日志与重建归档；检索三策略 keyword/embedding/hybrid（RRF k=60）；降级链保证永不阻塞宿主">
+</p>
+
+向量能力默认关闭（纯 FTS）。DSH 的 `ctx.llm` 无 embeddings 端点，语义检索由
+**三态嵌入源**提供（关闭 / 远程 / 本地），设置页可运行时切换——见下节。
+
+## 语义检索（嵌入源）
+
+设置页（记忆 → 概览 → 语义检索）选择嵌入源，即时生效、无需改配置重启：
+
+<p align="center">
+  <img src="./assets/img/EmbeddingSource.png" width="70%"
+       alt="设置页语义检索（嵌入源）面板（浅色主题）：三态选择器（关闭/本地/远程，本地选中）显示当前嵌入源与首次启用自动安装运行时提示；下方本地模型目录列出 BGE small 中文（使用中/已就绪）、EmbeddingGemma 300M（下载 316MB）、BGE-M3（下载 560MB）三款模型的维度/上下文/体积/特点与下载入口">
+</p>
+
+三种嵌入源：**关闭**（默认，纯 BM25 关键词检索）、**远程**（自备任意 OpenAI 兼容
+`/embeddings` 服务，`embedding.*` 四件套配齐才可选）、**本地**（内置模型目录选一款，
+ONNX 量化 **CPU 推理**——无需 API Key，数据不出本机）。本地模型目录是插件内置
+白名单（每款锁定 revision + 每文件 sha256，不可下载任意仓库）。
+
+- **下载**：模型卡一键下载（默认镜像 `hf-mirror.com`，断点续传 + sha256 完整性
+  校验），落盘数据目录 `models/<id>/`，不用了随时在设置页删除；
+- **按需运行时**：首次切换本地档才安装推理运行时（transformers.js，约 100~200MB，
+  装进数据目录 `runtime/`——不进插件依赖树，不碰插件安装目录）；
+- **活切换**：一键换源——自动后台全量重嵌（进度可见、可取消，期间检索自动降级
+  关键词，不影响对话；维度变化时向量表按新维度重建）；切换失败保持旧源，重启仍按原源运行；
+- **生效规则 = 部署上限 AND 运行时选择**：`embedding.allowLocalModels=false` 可整体
+  禁用本地档、未配 `embedding.*` 四件套则远程档不可选（企业部署可收口），状态持久
+  化在 `embedding-source.json`。
+
 ## 配置
 
 覆盖配置写在 profile 自己的 `cordis.patch.yml`，用**顶层裸 patch 条目**（直接 `id:`，
@@ -117,8 +180,9 @@ npx tsc src/smoke.ts --outDir dist-smoke --module nodenext --moduleResolution no
 | `capture.stripCodeBlocks` | `true` | 助手消息剥离代码块 |
 | `capture.maxMessageChars` | `4000` | 单条消息最大字符数 |
 | `extract.enabled` | `true` | L1 抽取 |
-| `extract.minMessages` | `1` | 攒够 N 条新消息跑一次 L1 抽取 |
-| `extract.backgroundMessages` | `10` | 抽取时附带的背景消息条数 |
+| `extract.minMessages` | `6` | 稳态触发阈值：单会话攒够 N 条新消息跑一次 L1 抽取。起步阶段生效阈值从 1 翻倍爬坡到此值（首轮即出记忆，随后自动攒批省调用） |
+| `extract.idleSeconds` | `300` | 闲置兜底：会话静默 N 秒后把未蒸馏切片落袋（接住"没攒够阈值用户就离开"）；`0` 关闭 |
+| `extract.backgroundMessages` | `10` | 抽取时附带的背景消息条数（按会话从 L0 现查，会话间互不污染） |
 | `extract.candidatePool` | `5` | 去重候选池大小 |
 | `l2.enabled` | `true` | L2 场景整合 |
 | `l2.minNewMemories` | `5` | 距上次 L2 整合的新记忆阈值 |
@@ -127,7 +191,12 @@ npx tsc src/smoke.ts --outDir dist-smoke --module nodenext --moduleResolution no
 | `l3.enabled` | `true` | L3 画像蒸馏 |
 | `l3.interval` | `20` | L3 蒸馏间隔（新记忆条数） |
 | `recall.enabled` | `true` | 自动召回 |
-| `recall.maxResults` | `5` | 每步召回注入的 L1 条数 |
+| `recall.maxResults` | `5` | 每条新用户消息前注入的 L1 条数上限 |
+| `recall.maxCharsPerMemory` | `500` | 单条注入记忆的字符上限（超限截断并提示用记忆工具查全文）；`0` 不限 |
+| `recall.maxTotalRecallChars` | `2000` | 整轮注入总字符上限（超限按相关性丢尾部）；`0` 不限 |
+| `recall.timeoutMs` | `5000` | 召回总预算（ms）：超时跳过本轮注入、不阻塞对话；`0` 不限时 |
+| `recall.includePersona` | `true` | 系统提示注入画像上下文（`<user-persona>`，稳定区） |
+| `recall.includeSceneNav` | `true` | 系统提示注入场景导航（`<scene-navigation>`，稳定区） |
 | `recall.strategy` | `hybrid` | 检索策略：`keyword` / `embedding` / `hybrid` |
 | `recall.scoreThreshold` | `0.3` | 召回分数阈值（低于不注入；仅 keyword/embedding 策略生效，hybrid 融合前不过滤；工具路径不过滤） |
 | `embedding.enabled` | `false` | 向量检索开关；关闭即纯 FTS 运行 |
@@ -135,70 +204,34 @@ npx tsc src/smoke.ts --outDir dist-smoke --module nodenext --moduleResolution no
 | `embedding.apiKey` | 空 | API Key |
 | `embedding.model` | 空 | embedding 模型名 |
 | `embedding.dimensions` | `0` | 向量维度（启用时必填，须与模型输出一致） |
+| `embedding.maxInputChars` | `5000` | 单条文本最大字符数（超长截断） |
+| `embedding.timeoutMs` | `10000` | 单次 embedding 调用超时（ms） |
 | `embedding.allowLocalModels` | `true` | 允许本地嵌入档（部署上限：关闭后设置页不能下载模型、不能切本地档） |
 | `embedding.mirror` | `https://hf-mirror.com` | 本地模型下载镜像根地址（可改回官方 `https://huggingface.co`） |
 | `llm.provider/model` | 空 | 蒸馏模型覆盖（默认用当前默认选择） |
-| `llm.maxTokens` | `256000` | 单次蒸馏输出 token 上限（全阶段统一；推理模型的 reasoning 与正文共享该预算，过低会被思考吃光导致正文 0 字符） |
+| `llm.maxTokens` | `65536` | 未分层调用的兜底输出总闸。各蒸馏层有独立预算（抽取 16k / 去重 8k / L2 32k / L3 16k；思考档 high/max 时自动 ×4，防 reasoning 吃光预算） |
 | `llm.reasoningEffort` | `off` | 蒸馏思考档位（部署默认）：`off` / `high` / `max`，空串不传（跟随模型默认）。蒸馏是结构化抽取任务，默认关思考——推理模型（如 v4-flash）默认 high 档的思考可把任意输出预算全部吃光导致正文 0 字符；非推理模型不认识 effort 时需设为空串。运行时可在设置页 → 记忆 → 概览临时切换（选"跟随配置"即回退本值） |
 | `llm.temperature` | `0.3` | 蒸馏温度 |
 | `llm.maxInputChars` | `700000` | 单次蒸馏输入字符预算（超限的 L1 输入自动分块抽取） |
+| `llm.timeoutMs` | `120000` | 单次蒸馏调用超时（ms） |
 | `tools` | `true` | 是否注册模型可调用的记忆工具 |
 
-## 存储布局
-
-<p align="center">
-  <img src="./assets/readme/storage.svg" width="100%"
-       alt="存储布局：双写架构（JSONL 事实源只增不改 + memory.db 主检索库）；文件形态含 conversations/records/scenes/persona/state/pending/session-modes/embedding-source/模型目录/推理运行时/日志与重建归档；检索三策略 keyword/embedding/hybrid（RRF k=60）；降级链保证永不阻塞宿主">
-</p>
-
-向量能力默认关闭（纯 FTS）。DSH 的 `ctx.llm` 无 embeddings 端点，语义检索由
-**三态嵌入源**提供（关闭 / 远程 / 本地），设置页可运行时切换——见下节。
-
-## 语义检索（嵌入源）
-
-设置页（记忆 → 概览 → 语义检索）选择嵌入源，即时生效、无需改配置重启：
-
-| 嵌入源 | 说明 |
-| --- | --- |
-| **关闭**（默认） | 不做任何向量嵌入，纯 BM25 关键词检索 |
-| **远程** | 自备任意 OpenAI 兼容 `/embeddings` 服务（`embedding.*` 四件套配齐才可选） |
-| **本地** | 内置模型目录选一款，ONNX 量化 **CPU 推理**——无需 API Key，数据不出本机 |
-
-本地模型目录是插件内置白名单（每款锁定 revision + 每文件 sha256，不可下载任意仓库）：
-
-| 模型 | 维度 | 上下文 | 体积 | 特点 |
-| --- | --- | --- | --- | --- |
-| BGE small 中文 | 512 | 512 | ~25MB | CPU 嵌入最快，适合先体验语义检索 |
-| EmbeddingGemma 300M | 768 | 2048 | ~330MB | 100+ 语言含中文，质量与开销均衡（上游 MemoryCore 同款） |
-| BGE-M3 | 1024 | 8192 | ~590MB | 中文质量最强，单条嵌入可达秒级 |
-
-- **下载**：模型卡一键下载（默认镜像 `hf-mirror.com`，断点续传 + sha256 完整性
-  校验），落盘数据目录 `models/<id>/`，不用了随时在设置页删除；
-- **按需运行时**：首次切换本地档才安装推理运行时（transformers.js，约 100~200MB，
-  装进数据目录 `runtime/`——不进插件依赖树，不碰插件安装目录）；
-- **活切换**：一键换源——自动后台全量重嵌（进度可见、可取消，期间检索自动降级
-  关键词，不影响对话；维度变化时向量表按新维度重建）；切换失败保持旧源，重启仍
-  按原源运行；
-- **生效规则 = 部署上限 AND 运行时选择**：`embedding.allowLocalModels=false` 可整体
-  禁用本地档、未配 `embedding.*` 四件套则远程档不可选（企业部署可收口），状态持久
-  化在 `embedding-source.json`。
-
-## 日志与排查
-
-dsh 宿主把插件日志打到控制台，插件将 info 及以上镜像到数据目录 `memory.log`。一轮
-对话的典型日志路径：`L0 捕获` → `L0 落盘` → `蒸馏管线开始` → `LLM 调用（输入/输出
-字符数、耗时）` → `L1 抽取完成` → `蒸馏管线结束`；下一轮有 `召回命中 N 条 L1`。
-LLM 空输出带完整诊断（finish 原因 / token 计数 / reasoning 摘录），JSON 解析失败
-附模型原始输出前 400 字符，失败 warn 均带堆栈首帧。
-
 ## 与 MemoryCore 的差异
 
 - 内嵌完整管线（不依赖外部 Gateway），蒸馏复用 DSH 自己的 LLM；
 - L2/L3 由"LLM 操作文件工具"改为"LLM 输出操作 JSON / 完整文档，工程侧执行"；
-- 召回注入点在 `agent/pre-step` + agent 作用域 `systemPrompt.context`（DSH 原生事件/服务）；
+- 召回注入点在 `agent/pre-step`（消息侧合成消息，官方 pre-step 替换语义）+ agent 作用域 `systemPrompt.context`（画像/导航稳定区，DSH 原生事件/服务）；
 - 存储/检索即官方 sqlite 后端的单机裁剪版（裁掉多租户隔离列、TCVDB 云后端、审计表；
-  分词用自带 CJK 二元组替代 jieba，保持零原生依赖——仅 sqlite-vec 一个原生扩展，
-  加载失败自动降级）。
+  分词与官方一致用 jieba——@node-rs/jieba 预编译二进制 + CJK 二元组并集，
+  词元供 BM25 精确整词命中、二元组保子词召回；加载失败自动回退纯二元组，
+  FTS 索引按分词器版本戳自动重建）。
+
+## 路线图
+
+以下为规划中的功能，欢迎在 [Issues](https://github.com/JunNanLYS/dsh-layered-memory/issues) 反馈需求与优先级：
+
+- [ ] **Git 分支感知**：记忆与当前 git 分支关联，召回可按分支过滤/加权（与现有记忆档位正交）
+- [ ] **Claude Code / Codex 记忆导入**：一键迁移既有记忆资产（`CLAUDE.md`、Claude Code 记忆文件、Codex `AGENTS.md` 等），导入后进入分层蒸馏管线
 
 ## 致谢
 

package/dist/client.js

@@ -1500,11 +1500,20 @@ window.__ModuleLoader__.load({
         if (!settingsData) return;
         // 乐观更新：立即翻 UI，失败回滚
         var prev = settingsData;
+        var patch = (function () { var o = {}; o[key] = value; return o; })();
         var next = Object.assign({}, prev, {
-          settings: Object.assign({}, prev.settings, (function () { var o = {}; o[key] = value; return o; })()),
+          settings: Object.assign({}, prev.settings, patch),
         });
+        // 蒸馏思考选择器读 effort.current（非 settings 键）：乐观更新须同步该视图字段，
+        // 否则点击后选择器在下一个 5s 轮询前"弹回"旧值，看起来没生效
+        if (key === "reasoningEffort" && next.effort) {
+          next.effort = Object.assign({}, prev.effort, {
+            current: value,
+            effective: value || prev.effort.fallback,
+          });
+        }
         setSettingsData(next);
-        rpc("dsh-memory/settings-set", (function () { var o = {}; o[key] = value; return o; })())
+        rpc("dsh-memory/settings-set", patch)
           .then(function (r) {
             if (!r || !r.ok) {
               setSettingsData(prev);