dsh-memory-fish 0.0.0-stage → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/), versioning follows [SemVer](https://semver.org/).
+
+## [0.7.0] — 2026-10-25
+
+### Added
+- **Dream reminder (C1)** — no scheduler dependency, no session-event writes.
+  `buildInjection` now computes whether a dream is due (`dreamAfterHours`, default
+  24) or memories are due for review, and appends a two-line `### 睡梦` nudge to
+  the injected block. Zero cost when nothing is due; nothing to initialize on
+  install or clean up on uninstall.
+- Config: `dreamReminder` (default `true`), `dreamAfterHours` (default `24`).
+- `stats.capturedSinceDream` tracks new journal records since the last dream and
+  resets after `memory_dream`.
+- Tests: reminder appears when due, disappears after a dream (51 assertions).
+
+### Branding
+- New mark: a chubby fish whose body is a memory core — three memory strata,
+  a small neural net, RAM-style belly pins, and a puzzle-piece dorsal fin for
+  "plugin". Deliberately not the DeepSeek whale.
+- `docs/logo.png` (with background), `docs/logo-transparent.png`,
+  `docs/banner.png` (1280×640 social preview), `icon.svg` (plugin icon),
+  regenerable with `python docs/make-art.py`.
+
+## [0.6.0] — 2026-10-25
+
+### Changed
+- **Split the single-file implementation into modules** under `lib/`:
+  `config`, `util`, `store`, `inject`, `core`, `dream`, `panel`, `tools`, `lock`, `log`.
+  Entry point is now `index.mjs`. No behavior change intended.
+- `package.json`: `engines`, `scripts`, `repository`/`homepage`/`bugs` metadata,
+  `files` whitelist, English description, version bump.
+
+### Added
+- **Secret redaction for journal capture** (`redactSecrets`): message text is
+  filtered before it is appended to `journal/*.jsonl`, both at the call site and
+  inside `Store.appendJournal`. `[REDACTED]` marker on hit.
+- **Cross-process write lock** (`lib/lock.mjs`): mutating tools acquire
+  `<dir>/.index.lock`, break stale locks after 15 s, time out after 5 s.
+  Mutating tool calls also re-read the index under the lock.
+- **Optional debug logging** (`lib/log.mjs`, config `debug: true`) to
+  `<dir>/debug.log`, 1 MB rotation, no-op by default.
+- **Config normalization** (`resolveConfig`): unknown keys ignored, numeric
+  fields coerced, `debug` added.
+- `SECURITY.md`, `CHANGELOG.md`, `LICENSE`, `.gitignore`, CI workflow,
+  English README.
+- Tests: journal redaction, lock release, P3 temporal assertions (46 total).
+
+### Fixed
+- `memory_search` no longer returns values with `undefined` fields (lossless JSON).
+- Historical versions are excluded from spaced-repetition reinforcement.
+
+## [0.5.0] — 2026-10-25
+
+### Added
+- **Temporal validity (P3)**: `validFrom` / `validTo` / `history` per memory.
+  Same-topic updates seal the previous version into history (max 10).
+- `memory_search({ asOf })` returns the version valid at that point in time;
+  default searches only current versions. Historical matches carry
+  `historical: true` and are not reinforced.
+- Migration for pre-0.5 entries.
+
+## [0.4.0] — 2026-10-25
+
+### Added
+- **Three-stage sleep (P0)**: SWS replay/compression, SHY salience-weighted
+  decay, REM associative links. Report includes all three phases.
+- **Spaced repetition (P1)**: `stability`, `lastReview`, `nextReview`, `reviews`.
+  Search reinforces ×1.3, read ×1.1; due items marked `⏰` and listed in the
+  dream report.
+- **Salience + novelty gate (P2)**: automatic 0–10 salience score, NOOP above
+  0.92 similarity, update between 0.75 and 0.92, insert below 0.75.
+- L1 hot index capped at 12 lines (working-memory calibration).
+
+## [0.3.0] — 2026-10-25
+
+### Added
+- Client plugin: a **「小肥鱼记忆」 section in DSH Settings** (React panel).
+  Standalone `/memory-fish/panel` page kept as fallback.
+
+## [0.2.0] — 2026-10-25
+
+### Added
+- **Auto-capture** of user/assistant messages into `journal/YYYY-MM-DD.jsonl`
+  (never injected; 30-day retention; subagent sessions skipped).
+- **Sleep mechanism (`memory_dream`)**: reviews the journal, extracts
+  candidate memories via cue words, writes `dream/YYYY-MM-DD.md`.
+- **Visual panel** at `/memory-fish/panel` with budget bar, profile editor,
+  search, pin/forget, dream/consolidate, reports.
+- Host routes with same-origin guard.
+
+## [0.1.0] — 2026-10-25
+
+### Added
+- Initial release: L0–L3 layered memory, 600-token injection budget,
+  write-time dedupe, decay/archival, secret refusal, nine tools,
+  Markdown/JSON storage, Settings-free first version.

package/DESIGN.md

@@ -0,0 +1,226 @@
+# 小肥鱼记忆 · 设计草案 v0.2
+
+> 目标：一个**上下文成本恒定**的轻量本地记忆插件。
+> 记忆可以无限增长，但注入上下文的部分永远是固定的一小块。
+>
+> 作者：铁凝 × 小肥鱼 🐟
+
+---
+
+## v0.2 落地变更
+
+- **自动捕获**：`session/event` 把 user/assistant 消息追加到 `journal/YYYY-MM-DD.jsonl`（L3 原始层，永不注入）。单条截断 4000 字符，子代理会话默认跳过。捕获零上下文成本。
+- **睡梦机制**：`memory_dream` 回顾最近 N 天 journal，按线索词提炼候选 + 相似去重，生成 `dream/YYYY-MM-DD.md`；每天 23:30 定时任务驱动 Agent 复盘并落库，再 `memory_consolidate`。
+- **可视化面板**：`GET /memory-fish/panel`（同源校验）+ `/memory-fish/api/state`、`/memory-fish/api/action`。展示预算条、条数卡片、画像编辑、记忆检索/置顶/遗忘、一键做梦/整理、最近睡梦报告。无构建步骤，纯 HTML。
+- **代码已按模块拆分函数**：`saveMemoryCore`（工具/面板/做梦共用）、`buildDream`、`registerPanelRoutes`、`runPanelAction`、`trustedRequest`。
+
+## 0. 一句话设计
+
+> **记忆的存储量是 O(∞)，注入成本是 O(1)，检索成本只在需要时发生。**
+
+现有的记忆插件（Claude Code 式、Markdown 索引式、知识图谱式）通病是：
+记忆越多 → 索引越长 → 每次会话注入越多 → 上下文越来越贵、越来越慢。
+
+我们要反过来：**记忆越多，系统越会"压缩"，注入部分永远只有几百 token。**
+
+---
+
+## 1. 目标 / 非目标
+
+### 目标
+- 跨会话记住铁凝的偏好、决策、结论
+- 注入 token 有**硬预算**（默认 ~600 tokens），不随记忆数量增长
+- 零服务端、零外部进程、零 embedding API、零额外 LLM 调用（可选增强除外）
+- 记忆**人类可读**（Markdown），可 git 管理、可手工编辑、可一键删除
+- 支持遗忘、纠错、覆盖（不是只增不减）
+
+### 非目标
+- 不做知识图谱 / 向量数据库 / RAG 平台
+- 不自动捕获每句对话（那会迅速变成垃圾场）
+- 不做多设备同步
+- 不替换系统提示里的其他上下文
+
+---
+
+## 2. 成本模型（先算账，再设计）
+
+一次会话的记忆注入成本 = `L0 + L1`，必须恒定。
+
+| 层 | 内容 | 注入 | 预算 |
+|---|---|---|---|
+| **L0 画像** | 用户是谁、人设、沟通偏好、硬约束 | 每次会话 | ≤ 200 tokens |
+| **L1 热索引** | 置顶记忆 + 最近 N 条的一行摘要 | 每次会话 | ≤ 400 tokens |
+| **L2 温记忆** | 完整记忆正文 | 按需工具读取 | 0（常驻） |
+| **L3 冷档案** | 归档、原始事件、被压缩的细节 | 只有 grep 命令能碰到 | 0 |
+
+**换算**：中文标题 + 日期 + 标签 ≈ 25–30 tokens/行 → L1 预算 400 tokens ≈ **12–15 行**。
+所以"热索引"最多 15 条：置顶 5 条 + 最近 10 条。其余全部沉到 L2/L3。
+
+L2/L3 不是删除，是"按需可取"——一次 `memory_search` 的成本只在真正需要时付。
+
+> 关键点：注入放在 **session start**（稳定前缀），不随每轮消息变化。
+> 稳定前缀能命中服务商的 prompt cache，实际成本远低于账面 token。
+
+---
+
+## 3. 四层架构
+
+```
+┌─────────────────────────────────────────────┐
+│ L0 画像 (≤200 tok, 常驻)                      │
+│   "铁凝：写代码/折腾电脑/关注新技术。             │
+│    自称小肥鱼。中文轻松语气。"                    │
+├─────────────────────────────────────────────┤
+│ L1 热索引 (≤400 tok, 常驻)                     │
+│   ★ 置顶：沟通偏好、项目约定（5 条）              │
+│   · 最近 10 条：标题 + 日期 + 2 个标签           │
+│   → 冷区还有 37 条，memory_search 可查          │
+├─────────────────────────────────────────────┤
+│ L2 温记忆 (磁盘, 按需)                          │
+│   每条 2–5 句，带来源、日期、重要度、失效时间        │
+├─────────────────────────────────────────────┤
+│ L3 冷档案 (磁盘, 极少触碰)                       │
+│   被合并的旧版本、被衰减的条目、压缩前的原始记录      │
+└─────────────────────────────────────────────┘
+```
+
+**晋升 / 降级规则**
+- 用户说"记住这个"或记忆被检索≥3 次 → 重要度↑，可晋升到 L1
+- 30 天未被检索且重要度低 → 降级到 L3（归档，不删除）
+- 同一主题出现新结论 → 旧条目标记 `superseded`，移出 L1，新旧之间保留链接
+
+---
+
+## 4. 防膨胀的六个机制
+
+### 4.1 写入门槛（Gate）
+不是所有对话都值得记。只在**结论时刻**写：
+- 用户明确表达偏好/纠正（最高价值）
+- 做出决策并说明理由
+- 排障闭环（错误 → 根因 → 修复）
+- 关键数字/ID/路径
+
+不写：临时状态、进行中的调试、仓库里能读到的、模型猜测。
+
+### 4.2 写入即去重（Dedupe）
+保存前做**字符 bigram Jaccard 相似度**（本地、零依赖）：
+- 相似度 > 0.75 → 判定同主题，**原地更新**（保留历史版本到 L3）
+- 相似度 0.4–0.75 → 作为"相关记忆"链接，不新增
+- 否则新增
+
+> 这是控制增长的**第一道闸门**：重复才是膨胀的主因，而不是数量。
+
+### 4.3 定期压缩（Consolidation）
+触发条件（任一）：L1 超过预算 / 新增 20 条 / 每周一次 / 用户手动 `/memory-consolidate`
+动作：
+1. 聚类（同标签或相似度 > 0.5）
+2. 每簇合并成一条"主题记忆"（保留要点 + 时间线）
+3. 合并前的原文全部进 L3 冷档案（可回溯）
+4. 重新生成 L1（只保留置顶 + 最近）
+
+压缩用**纯规则**（标题/标签/时间/相似度），不调 LLM —— 零额外 token。
+如果以后想要更聪明的合并，可以挂一个"可选：用便宜模型压缩"的开关，默认关闭。
+
+### 4.4 衰减（Decay）
+每条记忆维护 `score = importance × recency × (1 + hits)`
+- `importance`：用户明说 5，决策 4，偏好 3，结论 2
+- `recency`：指数衰减，半衰期 30 天
+- `hits`：被检索次数
+
+score 低于阈值的条目移出 L1 → L3。**只降级不删除**，除非用户明确"忘掉"。
+
+### 4.5 预算守卫（Budget Guard）
+- 注入前统计 L0+L1 估算 token，超预算则自动执行压缩/裁剪
+- 每次注入后记录：`injected_tokens`，写进统计文件
+- 提供 `memory_stats` 工具：看记忆总数、L1 占多少 token、本月开销趋势
+
+### 4.6 冷热分离的检索
+- 常驻只有 L1
+- L2/L3 用 `memory_search`（BM25 + 字符 bigram，中文友好），**本地同步计算，<5ms**
+- `memory_read` 按 id 取全文，支持截断
+- 不做"每轮自动召回"（那会把上下文预算交给不可控的相关性判断）；需要时我只花一次工具调用
+
+---
+
+## 5. 存储格式（人类可读 + 机器可查）
+
+```
+memory/
+├── profile.md                 # L0，手写/我维护，很小
+├── index.json                 # L1 的机器索引 + 每条元数据（可重建）
+├── hot/                       # 置顶与近期（软链或副本）
+├── memories/
+│   └── 20261025-213821-prefer-pnpm.md
+├── archive/                   # L3：压缩前原文、被替代版本
+│   └── 20261025-213821-prefer-pnpm.md.1
+└── stats.json                 # token 账本
+```
+
+单条记忆格式（Markdown + frontmatter）：
+```markdown
+---
+id: 20261025-213821-prefer-pnpm
+created: 2026-10-25T21:38:21+08:00
+importance: 4
+hits: 0
+supersedes: 20260910-120000-use-npm
+tags: [工具链, 包管理]
+status: active        # active | superseded | archived
+---
+# 用 pnpm，不用 npm
+
+这个项目统一用 pnpm（锁文件为 pnpm-lock.yaml）。
+理由：磁盘占用小、hoisted linker 与 DSH profile 兼容。
+```
+
+**为什么不用 SQLite**：Markdown 可读、可 diff、可手工修、可 git；检索靠启动时构建内存索引（1 万条 ≈ 几 MB，毫秒级）。SQLite 作为可选加速层以后再加。
+
+---
+
+## 6. 工具面
+
+| 工具 | 作用 | 成本 |
+|---|---|---|
+| `memory_save` | 保存/更新（自动去重），带门槛提示 | 一次调用 |
+| `memory_search` | 本地关键词检索（L2+L3） | 毫秒级 |
+| `memory_read` | 读全文（超长截断 + 给路径） | 一次调用 |
+| `memory_list` | 最近 N 条（默认 8） | 一次调用 |
+| `memory_pin` | 置顶/取消置顶（进 L1 头部） | 一次调用 |
+| `memory_forget` | 遗忘（软删除 + tombstone，防复活） | 一次调用 |
+| `memory_stats` | 预算与增长统计 | 一次调用 |
+| `memory_consolidate` | 手动触发压缩（定期任务也会调） | 纯本地 |
+
+---
+
+## 7. 失败模式与对策
+
+| 失败模式 | 对策 |
+|---|---|
+| 记忆越存越多，索引爆炸 | L1 硬预算 + 自动压缩 + 衰减 |
+| 同一件事存了 5 遍 | 写入去重（相似度阈值） |
+| 过期事实被当成现状 | 有效期字段 + supersede 链 + 状态可见 |
+| 注入内容污染系统提示 | 注入块单独成节、可关闭、标注来源与日期 |
+| 模型编造记忆 | 只允许工具写入；每条带来源会话 id |
+| 删不掉 / 越删越乱 | 软删除 + tombstone + 冷档案可追溯 |
+| 检索不准 | 关键词 + 标签 + 标题加权；不追求语义搜索 |
+
+---
+
+## 8. 路线图
+
+- **M0 骨架（今晚）**：目录结构 + profile.md + index.json + `memory_save/search/read/list` + 注入 L0/L1 + 预算守卫
+- **M1 防膨胀**：去重、pin、forget、stats、压缩（规则版）
+- **M2 自动化**：定时压缩任务、衰减计算、冷热迁移
+- **M3 体验**：Memory 面板（查看/编辑/统计）、导出/备份
+- **M4 打磨**：测试（node:test）、错误处理、与 fooxe 插件共存/替代策略
+
+---
+
+## 9. 待铁凝拍板的决策
+
+1. **名字**：`dsh-memory-fish` / `小肥鱼记忆` / 其他？
+2. **自动捕获**：默认**不自动**（只在我判断值得记时写）还是允许"每轮对话后自动摘要"？
+   - 自动更省事，但增长快、噪音多；建议先手动，稳定后再加开关。
+3. **L1 预算**：400 tokens（≈13 行）够不够？还是 600？
+4. **是否要可视化面板**：M3 才有，先命令行/文件能不能接受？
+5. **和现有 `@fooxe/dsh-memory` 的关系**：先共存对比，还是直接替换？

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-memory-fish contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,121 @@
+# dsh-memory-fish 🐟
+
+![banner](https://raw.githubusercontent.com/GitHub-yxm-hub/dsh-memory-fish/main/docs/banner.png)
+
+> **Context-budgeted local memory for DeepSeek Harness.**
+> Memory can grow forever; the prompt injection stays at a fixed ~600 tokens.
+> It sleeps, it reviews, and it remembers what was true last month.
+
+[中文说明](./README.md) · [Design](./DESIGN.md) · [Research](./RESEARCH.md) · [Changelog](./CHANGELOG.md) · [Security](./SECURITY.md)
+
+## Why
+
+Most memory plugins inject an index that grows with your memory count — 500 memories, 500 lines in every prompt. It gets expensive and slow.
+
+dsh-memory-fish splits *storage* from *injection*:
+
+| Layer | Content | Injected | Budget |
+|---|---|---|---|
+| L0 profile | who you are, hard constraints | every session | ≤200 tok |
+| L1 hot index | pinned + recent entries | every session | ≤400 tok |
+| L2 warm memories | full text | on demand via tools | 0 |
+| L3 cold archive | superseded/removed versions, raw journal | never | 0 |
+
+**10 memories or 10,000 — the injected block stays the same size.**
+
+## Features
+
+- **Zero dependencies, zero servers.** Plain Markdown + JSON under `~/.dsh/memory-fish/`.
+- **Fixed token budget** (600 by default), enforced before injection.
+- **Write-time dedupe + novelty gate.** Similarity ≥0.92 → no-op, 0.75–0.92 → in-place update, below → new entry.
+- **Automatic salience scoring** (0–10): explicit "remember this", corrections, absolutes, novelty, pins.
+- **Three-stage sleep** (`memory_dream`): SWS replay & compression → SHY salience-weighted decay → REM associative links.
+- **Spaced repetition**: stability, nextReview, reviews; retrieval reinforces (×1.3 search, ×1.1 read); due items marked ⏰.
+- **Temporal validity**: `validFrom`/`validTo` + version history; `memory_search({ asOf: "2026-09-15" })` answers "what did we use last month".
+- **Auto-capture** of conversations into a raw journal (never injected, secrets redacted, 30-day retention).
+- **Dream reminder (C1)** — no scheduled tasks, no session-event writes. When the last dream is older than `dreamAfterHours` (24h default) or memories are due for review, the injection block adds a two-line nudge. Zero cost when nothing is due; nothing to clean up on uninstall.
+- **Optional visual panel**: a Settings section in DSH, plus a standalone page at `/memory-fish/panel`.
+
+## Install
+
+```bash
+# from npm (once published)
+dsh plugin --profile web add dsh-memory-fish
+
+# or from a local clone
+dsh plugin --profile web add ./dsh-memory-fish
+```
+
+Then restart DSH. Verify with a new chat: say *"remember: I prefer pnpm"* and look for a `memory_save` tool call.
+
+Requirements: Node.js ≥ 22.19, DeepSeek Harness 0.2.x (tested on 0.2.1).
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `memory_save` | Save/update a memory (dedupe, salience, versioning) |
+| `memory_search` | Keyword search; `asOf` for historical versions; `includeArchived` for cold storage |
+| `memory_read` | Read full text (>4000 chars truncated) and reinforce |
+| `memory_list` | Recent memories |
+| `memory_pin` | Pin/unpin (pinned never decays) |
+| `memory_forget` | Soft delete + tombstone |
+| `memory_profile_save` | Write the L0 profile |
+| `memory_dream` | Run the three-stage sleep; returns phases, due-review list, candidates |
+| `memory_stats` | Injection tokens, counts, salience avg, due count |
+| `memory_consolidate` | Merge near-duplicates, archive weak memories (dry-run supported) |
+
+## Architecture
+
+```
+index.mjs        plugin entry: config, system-prompt injection, auto-capture, wiring
+lib/config.mjs   defaults + config normalization
+lib/util.mjs     tokens, bigrams/Jaccard, salience, spaced repetition, redaction
+lib/store.mjs    Markdown/JSON store, journal, archive, migration
+lib/inject.mjs   L0+L1 prompt block builder (budget-limited)
+lib/core.mjs     saveMemoryCore: dedupe / novelty gate / versioning
+lib/dream.mjs    three-stage sleep
+lib/tools.mjs    model-facing tools (mutations serialized by lock)
+lib/panel.mjs    local HTTP panel + API
+lib/lock.mjs     cross-process write lock
+lib/log.mjs      opt-in debug log
+client/client.js Settings panel (browser half)
+```
+
+## Configuration
+
+Pass config through the profile's `cordis.patch.yml`:
+
+```yaml
+- id: memory-fish
+  config:
+    budgetTokens: 600
+    maxHotLines: 12
+    autoCapture: true
+    debug: false
+```
+
+Key options: `dir`, `budgetTokens`, `profileTokens`, `maxHotLines`,
+`archiveAfterDays`, `dedupeThreshold`, `noopThreshold`, `reviewEnabled`,
+`autoCapture`, `captureMaxChars`, `journalKeepDays`, `dreamDays`,
+`panelPath`, `apiBase`, `debug`.
+
+## Tests
+
+```bash
+npm test   # 46 assertions: capture, redaction, save/dedupe/NOOP, search,
+           # asOf history, sleep phases, panel routes, lock release, budget
+```
+
+CI runs on Linux and Windows with Node 22 and 24.
+
+## Security
+
+Local-first, no network. Journal writes redact API keys/tokens/passwords before
+hitting disk. The HTTP panel is localhost-only with same-origin checks but **no
+authentication** — run DSH on a trusted machine. See [SECURITY.md](./SECURITY.md).
+
+## License
+
+MIT
+

package/README.md

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# 小肥鱼记忆 · dsh-memory-fish
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![banner](https://raw.githubusercontent.com/GitHub-yxm-hub/dsh-memory-fish/main/docs/banner.png)
+
+> 上下文成本恒定的本地记忆插件。记忆可以无限长，注入永远只有 ~600 tokens。
+> 它会睡觉、会复习，也记得住"上个月我们用的什么方案"。
+
+[English](./README.en.md) · [设计](./DESIGN.md) · [调研](./RESEARCH.md) · [更新日志](./CHANGELOG.md) · [安全](./SECURITY.md)
+
+## 它解决什么
+
+现有记忆插件的通病：记忆越多 → 索引越长 → 每次会话注入越多 → 又贵又慢。
+
+小肥鱼记忆把「存储」和「注入」拆开：
+
+| 层 | 内容 | 注入 | 预算 |
+|---|---|---|---|
+| L0 画像 | 你是谁、偏好、硬约束 | 每次会话 | ≤200 tok |
+| L1 热索引 | 置顶 + 最近 10–20 条标题 | 每次会话 | ≤400 tok |
+| L2 温记忆 | 完整正文 | 按需工具读取 | 0 |
+| L3 冷档案 | 压缩前原文、被替代版本 | 从不注入 | 0 |
+
+记住 10 条和记住 1000 条，注入成本一样。
+
+## 防膨胀机制
+
+- **写入即去重**：字符 bigram Jaccard ≥ 0.75 判定同主题，原地更新，旧版本进冷档案
+- **规则压缩**：`memory_consolidate` 合并近似条目（不调 LLM，零额外 token）
+- **衰减归档**：60 天未更新、未置顶、低重要度 → 归档（可检索，不删除）
+- **硬预算**：注入前按 token 预算裁剪，超了就少注入几行
+
+## v0.2 新功能
+
+### 自动捕获（默认开）
+每次会话的 user / assistant 消息自动追加到 `journal/YYYY-MM-DD.jsonl`（L3 原始层，**永不注入**，单条最多 4000 字符）。子代理会话默认跳过。捕获只是落盘，不产生任何上下文成本。
+
+### 睡梦机制
+每天 23:30 定时触发（也可手动 `memory_dream`）：
+1. 回顾最近 N 天的全部对话 journal
+2. 按线索词（记住/我喜欢/统一用/以后都/约定…）提炼候选，相似候选自动去重
+3. 生成 `dream/YYYY-MM-DD.md` 报告
+4. Agent 逐条判断后 `memory_save` 值得留下的，再 `memory_consolidate`
+
+### 可视化面板
+宿主 webServer 上的本地页面：`/memory-fish/panel`
+- 注入 token 预算条、活跃/归档/置顶/今日对话/候选线索卡片
+- 画像编辑、记忆搜索、置顶/遗忘
+- 一键「现在做梦」「整理记忆」、查看最近睡梦报告
+
+同源校验：拒绝跨站请求（Origin/Host/Sec-Fetch-Site），只允许 localhost / 本机 IP。
+
+## v0.4 生理学调优（P0/P1/P2）
+
+### 三阶段睡眠（P0）
+`memory_dream` 现在按睡眠分期跑完整流程：
+1. **SWS 慢波**：重放 journal，合并相似记忆（原文进 archive）
+2. **SHY 稳态**：按显著性加权衰减，长期低分记忆降级归档
+3. **REM**：为共享标签/相似的记忆建立「相关链接」，不改内容
+
+报告写到 `dream/YYYY-MM-DD.md`，包含三阶段明细 + 待复习清单 + 候选记忆。
+
+### 睡梦提醒（C1：不依赖宿主调度器）
+插件**不创建任何定时任务**，也不写宿主的 session 事件日志。它只在注入块里按需提醒：
+
+```
+### 睡梦
+- 距上次做梦 26 小时 · 新增对话 12 条 → 建议先 memory_dream 做三阶段整理
+```
+
+判断条件：`dreamReminder: true`（默认）且（距上次做梦 ≥ `dreamAfterHours`（默认 24）**或**有到期复习），并且确实有新对话或复习项。没有就完全不出现，零 token 成本。
+
+好处：新会话也有效、卸载后零残留、不依赖 `dsh-schedule` 的内部协议。
+
+### 间隔重复（P1）
+每条记忆维护 `stability`（能记多久）、`nextReview`（下次复习日）、`reviews`：
+- 新记忆按重要度给初始稳定性（约 8–13 天）
+- `memory_search` / `memory_read` 命中即加固（稳定性 ×1.3 / ×1.1），这就是提取练习效应
+- 到期条目在热索引里标 `⏰`，睡眠报告里列成待复习清单
+
+### 显著性 + 新颖性门控（P2）
+- 写入时自动打分（0–10）：明说「记住」+4、纠正 +2、绝对化措辞 +1、新颖度 +0~2、置顶 +1
+- 相似度 ≥0.92 → **NOOP**：完全重复不写，只记一次复习
+- 0.75–0.92 → 原地更新；<0.75 → 新增
+
+## v0.5 时间有效性（P3）
+
+每条记忆带有效期：`validFrom` / `validTo`，同主题内容变化时：
+
+- 旧版本封存进 `history`（含自己的 validFrom → validTo），当前版本换新有效期
+- `memory_search` 默认只返回**当前有效**版本
+- `memory_search({ asOf: "2026-09-15" })` 按时间点查当时有效的版本 —— 能回答"上个月我们用什么方案"
+- 历史版本不参与复习加固，避免旧事实被强化
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `memory_save` | 保存/原地更新（自动去重、拒存密钥） |
+| `memory_search` | 本地关键词检索（含归档，可选） |
+| `memory_read` | 读全文（>4000 字符截断） |
+| `memory_list` | 最近记忆 |
+| `memory_pin` | 置顶/取消（置顶不参与衰减） |
+| `memory_forget` | 软删除 + 墓碑 |
+| `memory_profile_save` | 写 L0 画像 |
+| `memory_dream` | 睡梦：回顾对话、提炼候选、写报告 |
+| `memory_stats` | 查看注入 token / 条数 / 磁盘占用 / 捕获数 |
+| `memory_consolidate` | 手动整理（dry-run 可选） |
+
+## 数据位置
+
+```
+~/.dsh/memory-fish/
+├── profile.md      # L0
+├── index.json      # 元数据索引（可重建）
+├── memories/       # L2：每条一个 Markdown
+├── archive/        # L3：旧版本、被替代、被遗忘的原文
+├── journal/        # 自动捕获的原始对话（按天 jsonl，永不注入）
+├── dream/          # 睡梦报告（按天 md）
+└── stats.json      # 计数
+```
+
+全部人类可读、可 git、可手改。索引丢失会从 `memories/*.md` 自动重建。
+
+## 安装
+
+注册进 DSH profile：
+
+1. 把本目录复制到 `<profile>/node_modules/dsh-memory-fish/`
+2. 在 `<profile>/package.json` 的 `dsh.profile.bundles` 加入 `"dsh-memory-fish"`，
+   并在 `dependencies` 加入 `"dsh-memory-fish": "file:projects/memory-fish"`
+3. 重启 DSH（或等待 profile 热加载）
+
+## 代码结构
+
+```
+index.mjs        插件入口：配置、注入、自动捕获、装配
+lib/config.mjs   默认值 + 配置校验
+lib/util.mjs     token 估算、bigram/Jaccard、显著性、间隔重复、脱敏
+lib/store.mjs    Markdown/JSON 存储、journal、归档、迁移
+lib/inject.mjs   L0+L1 注入块（预算裁剪）
+lib/core.mjs     saveMemoryCore：去重 / 新颖性门控 / 版本
+lib/dream.mjs    三阶段睡眠
+lib/tools.mjs    模型工具（写操作加锁串行）
+lib/panel.mjs    本地 HTTP 面板 + API
+lib/lock.mjs     跨进程写锁
+lib/log.mjs      可选调试日志
+client/client.js 设置页面板（浏览器半）
+```
+
+## 测试
+
+```bash
+npm test   # 49 项断言：捕获、脱敏、保存/去重/NOOP、检索、asOf 历史、
+           # 睡眠三阶段、面板路由、锁释放、预算
+```
+
+CI 在 Linux / Windows × Node 22 / 24 上跑。
+
+## 安全
+
+本地优先、无网络。journal 落盘前会脱敏密钥；HTTP 面板仅限 localhost 且有同源校验，但**没有鉴权**——请只在可信机器上运行。详见 [SECURITY.md](./SECURITY.md)。
+
+## 设计
+
+见 [DESIGN.md](./DESIGN.md)。
+
+## License
+
+MIT
+