dsh-plugin-xujie-memory 0.0.0-stage → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.5.0（内核 0.52.0）
+
+### 性能
+- 画像派生改为增量：旧版每轮全量重算、并且被调用两次，会话攒到约 1500 条后单轮要 1.5–2 秒，超过宿主 4 秒超时就静默失效。现在 2000 条时 p50 约 10ms，3000 条只做全量派生时 p50 约 6ms。
+- 补了 4 个索引；WAL 下 `synchronous=NORMAL`、`busy_timeout=30s`。
+- 模糊检索只预处理一次查询，内容侧加缓存。
+
+### 稳定性
+- 插件加看门狗：内核崩溃或被别的实例带走后，按 2s/4s/8s… 退避自动拉起。
+- `/health` 返回版本、库路径、范围模式；端口上是旧版或别人的服务就自动换端口（最多 10 个）。
+- 内核带 `--parent-pid`，宿主崩溃后 3 秒内自动退出，不留占端口的孤儿进程。
+- 内核日志写到 `kernel.log`（旧版 `stdio:'ignore'` 全部丢失）。
+- 同一会话的请求串行，快速连发不会乱序；内核正被重拉时连不上会重试一次，超时不重试（避免重复记录）。
+- 换人嫌疑会自动解除：用户明确改称呼时直接解除，超过 30 分钟也会解除。旧版一句「以后叫我老王」就会让画像永久冻结。
+- 内核改为 HTTP/1.1 keep-alive；提前拒绝的请求会主动断开连接，避免未读的请求体污染同一连接上的下一次请求。
+- FTS 查询转义双引号：旧版用户消息里带 `"` 时整轮返回 500。
+
+### 长期记忆
+- 默认 `scope: user`：画像、偏好、锚点、账跨会话共享；追问熔断仍然按会话计算。`scope: session` 可恢复旧行为。
+- 去掉 session 模式下的跨会话 `lastContext` 兜底。
+
+### 准确率（回归集 `test/kernel_regression.py`，31/31）
+- 问句不再生成事实（「你还记得我欠谁钱吗」）。
+- 「还/本/书/瓶」等单字不再触发记账；日期里的数字（周五、四月）不再当成数量。
+- 无领域词的闲聊（「哈哈」「我女朋友叫小美」）不再落成偏好。
+- 偏好极性：识别「不讨厌/能吃/开始喜欢/过敏」；对象会清理多余字（「辣了」记成「辣」），改口时覆盖旧值，旧标签标成已纠正。
+- 称呼明说即生效（宿主没有确认交互，旧版会永远挂起）。
+- 第三方债主：「我欠老李500」「老李的钱还了300」能正确记账；材料新增「账目（已确认）」一节，直接给出余额。
+- 锚点去掉「这个：」之类的指令前缀；待确认项会附上原话。
+- 检索修复：当前这句不再挡住模糊兜底，相关旧事能召回。
+- 插件 `peer_id` 改成 `assistant`（旧版是 `user`，「我欠你」会记成自己欠自己）。
+
+### 安全
+- 请求必须带 `X-Xujie-Token`（token 文件权限为 0600），且只接受 `application/json`，本机网页无法再往记忆里写东西。
+- 请求体上限 256KB，正文截断到 2000 字；参数类型错误返回 400，不再返回 500。
+
+### 打包
+- 删除了无用的 cpython-313 `__pycache__`（内置运行时是 3.12）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoren-Syi
+
+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.md

@@ -1,3 +1,224 @@
-# Temporary Holding Version
+# dsh-plugin-xujie-memory
 
-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.
+[English](README_EN.md) | 简体中文
+
+为 DeepSeek Harness（DSH）打造的无感长期记忆插件。
+
+**记忆的价值在于不用想。** Xujie-Memory 自动记录相关信息，并在对话中组装记忆材料、注入提示词，无需模型决定是否调用记忆工具。Windows x64 包含运行时，按安装说明接入后一般无需额外配置。
+
+## 工作流程
+
+```mermaid
+flowchart LR
+    A[会话事件] --> B[过滤用户消息与注入内容]
+    B --> C[语义提取与准入闸门]
+    C --> D[SQLite 事件记录与状态投影]
+    D --> E[权重衰减与相关记忆召回]
+    E --> F[精确检索及模糊匹配]
+    F --> G[组装三层记忆材料]
+    G --> H[通过 Prompt section 自动注入]
+```
+
+事件记录与状态投影支持追溯和重放；情节记忆、人物卡等也有各自的存储结构。默认同步 section 读取缓存，宿主时序可能使本轮看到上一轮材料，详见下方「记忆范围」。
+
+## 与工具调用式记忆对比
+
+| 维度 | 常见工具调用式记忆 | Xujie-Memory |
+|---|---|---|
+| 模型是否需要决定检索 | 通常需要主动调用工具 | 自动组装并注入，无需模型决定是否调用 |
+| 记忆组织 | 取决于具体实现 | 语义、情节、工作三层 |
+| 延迟 | 取决于工具调用和实现 | 内核请求有开销；默认同步读取缓存，异步模式会等待材料 |
+| 追问控制 | 取决于实现和提示词 | 同一条只问一次，每轮最多一件，默认每会话最多六次 |
+| 衰减与模糊召回 | 取决于具体实现 | 支持权重衰减与模糊搜索 |
+
+此表比较常见设计方式，具体工具调用方案的功能和性能可能不同。
+
+装上去之后，DSH 会**在每轮对话里自动**做三件事：
+
+1. 把你说的话判定成事实（欠账 / 偏好 / 称呼 / 承诺），写进本地库
+2. 把"这个人是谁、我现在记得什么、他专门交代过要记住什么"注入提示词
+3. 你没说清楚的地方，**最多问一次**，问过就不再提
+
+它不是"给模型一个 `memory_search` 工具"——工具要模型自己想起来用，
+而记忆的价值恰恰在于**不用想**。
+
+### 三层记忆（当前版本 0.5.0）
+
+| 层 | 内容 | 你怎么用 |
+|---|---|---|
+| 语义 | 人物卡、事实、锚点 | 自动注入「关于这个人 / 重要的事」 |
+| 情节 | 原话、摘要 | 相关旧事自动浮上来；可模糊搜（错字也能中） |
+| 工作 | 最近几句、未确认项 | 自动注入「最近说过的话 / 还没确定的事」 |
+
+**重点标注**：AI 会先自动判断一句话值不值得记——身份、强偏好、承诺、健康/钱/
+关系、情绪强度会提高权重（1–5），寒暄天气降低；聊天里说「记住这个」才会
+钉成锚点。自动分只决定「淡得慢一点」，5.0 和锚点留给用户明说。
+
+代码/后台也可以用 `POST /memory/mark` 手动标 1–5 级重要性。
+
+**遗忘曲线**：`POST /memory/curve` 看重放出来的权重历史；检索命中不会重置衰减。
+
+**模糊搜索**：`POST /memory/search`，两字词、错一个字都能捞；
+精确检索落空时，自动注入也会降级到模糊匹配。
+
+本仓库保留 0.5.0 发布包中的内核；上表概括了三层记忆。
+
+---
+
+## 装上就能用（用户零动作）
+
+| | |
+|---|---|
+| DSH | 0.2 预览版（`dsh.bundle` 机制） |
+| Node | `^22.19 \|\| >=24` |
+| Python | **不用装**：Windows x64 包里自带解释器 |
+| 内核 | **不用装**：Python 内核（`python/xujie_memory`）在包里 |
+
+```bash
+dsh plugin --profile <你的profile> add <解压后的 dsh-plugin-xujie-memory 目录>
+# 新开一个会话即可
+```
+
+仓库公开后，也可以从 GitHub 安装指定版本：
+
+```bash
+dsh plugin --profile <你的profile> add github:Shoren-Syi/dsh-plugin-xujie-memory#v0.5.0
+```
+
+不需要 `pip install`，不需要填 `repoPath`，不需要另外起服务：
+
+- 插件用**包内解释器**（`runtime/win32-x64/python.exe`）拉起**包内内核**
+  （`python/xujie_memory`），数据默认落在 `~/.xujie-memory/memory.db`。
+- 内核路径 / 解释器路径都在 `lib/index.js` 里按 `import.meta.url` 自解析；
+  只有开发时才需要 `repoPath` / `pythonPath` 覆盖。
+- 内核挂了只影响"这一轮没有记忆"，**不影响对话**。
+
+> 平台说明：当前包内自带 **Windows x64** 解释器。macOS / Linux 会回退到
+> 系统 `python3`（内核零第三方依赖，3.10+ 即可）；要完全零依赖，需要给
+> 对应平台补 `runtime/<平台>-<架构>/`。
+
+可选配置（写在 profile 的 `cordis.patch.yml`，一般不用动）：
+
+```yaml
+- id: xujie-memory
+  config:
+    endpoint: "http://127.0.0.1:8765"  # 内核端口
+    autoStart: true                    # 由插件拉起内核
+    dbPath: ""                         # 留空 = ~/.xujie-memory/memory.db
+    statusFile: ""                     # 填文件路径可把挂载/就绪状态写进去（排查用）
+    maxAskedTotal: 6                   # 一个会话最多主动追问几次
+```
+
+---
+
+## 你会看到什么
+
+材料会变成提示词里的一段：
+
+```
+## 关于这个人
+- 他说过：偏好不吃辣
+
+## 重要的事（他专门说过要记住，不会随时间淡去）
+- 四月十二号那天项目上线，我们熬到凌晨四点。
+
+## 还没确定的事
+- 需要确认这句话是不是这个意思
+（如果用户当前这句其实已经说清楚了，就当它确认了；否则最多挑一件顺带问一句，别追问）
+```
+
+---
+
+## 追问有熔断
+
+| 闸 | 行为 |
+|---|---|
+| 同一条只念一次 | 念过就标 `asked_at`，第二遍不再进材料 |
+| 一轮最多一件 | `TurnBudget.max_questions = 1` |
+| 一个会话最多 6 次 | 超过之后材料里只剩一句总数，**不再引导追问** |
+
+熔断之后那些记录还在库里，用户主动提起来时照样能用——**不问 ≠ 忘了**。
+
+---
+
+## 记忆范围
+
+默认 `scope: user`：人物卡、偏好、锚点、账**跨会话有效**——新开会话也认识你。
+「最多追问几次」的熔断仍按会话算。
+
+想要 0.4 的行为（每个会话一份、互不相通）就设 `scope: session`；
+这种模式下没有会话上下文的组装返回空，绝不串会话。
+
+插件按会话缓存材料（最多 32 个）。注意：`section.text` 是同步读缓存的，
+宿主如果在 `/turn` 返回前就拼提示词，本轮用的是上一轮的材料（单轮内核耗时通常 <15ms）。
+宿主支持异步 section 时可开 `asyncSection: true`。
+
+## 可靠性
+
+- 看门狗每 5 秒查一次内核，挂了按退避自动拉起；日志在 `~/.xujie-memory/kernel.log`。
+- `/health` 返回版本、库路径；端口上是旧版或别的服务就自动换端口。
+- 内核跟随宿主进程退出，不留孤儿进程。
+- 请求要带 `X-Xujie-Token`（`~/.xujie-memory/token`），并且只收 `application/json`。
+
+---
+
+## 事件（已按真机核对）
+
+`session/event` 里只有 `user/message` 会写记忆：
+
+| 类型 | 插件行为 |
+|---|---|
+| `user/message` | **写记忆**，正文在 `event.data.content[]` 的 `text` 块里 |
+| `assistant/message` | 跳过 |
+| `tool/call` / `tool/result` / `step/end` / `turn/start` | 跳过 |
+
+两个容易踩的点，插件里已经处理：
+
+1. **正文在 `data.content` 数组里**，不是 `event.content`。
+2. **注入消息也是 `user/message`**（`source.kind = runtime-context` /
+   `agent-instructions` 等），它们不是用户说的，会被跳过——否则提示词
+   会被当成"用户说的事实"记进库里。
+
+---
+
+## 排查
+
+```bash
+# 只想确认插件挂上了、内核起来了：在 profile 配置里设 statusFile，
+# 启动后看文件里有没有这两行：
+#   info 已挂载，内核在 http://127.0.0.1:8765
+#   info 内核就绪（xxxms）：http://127.0.0.1:8765
+
+# 手动跑内核（诊断用；用插件包内的解释器）
+runtime/win32-x64/python.exe -m xujie_memory.server --port 8765 --token-file %USERPROFILE%\.xujie-memory\token
+
+# 直接打一轮，看材料长什么样
+curl -s --noproxy '*' -X POST http://127.0.0.1:8765/turn \
+  -H "Content-Type: application/json" \
+  -H "X-Xujie-Token: $(cat ~/.xujie-memory/token)" \
+  -d '{"session":"t1","user":"owner","text":"我不吃辣"}'
+```
+
+**记忆服务挂了不该让人没法说话。**
+
+---
+
+## 结构
+
+```
+dsh-plugin-xujie-memory/
+├── lib/index.js          # 薄壳：挂 section / 收事件 / 起内核
+├── python/xujie_memory   # Python 内核（零第三方依赖）
+├── python/specs          # 判定规则
+├── runtime/win32-x64/    # 自带解释器（Windows）
+└── cordis.patch.yml      # bundle patch（DSH 0.2 顶层数组格式）
+```
+
+逻辑全在 Python 侧，插件只是个薄壳——DSH 还是预览版，API 会变，
+把不稳定的部分做薄。
+
+## 开发验证
+
+`npm test` 运行插件与内核的集成冒烟测试，覆盖会话隔离和注入消息过滤；Windows x64 默认使用包内 Python，其他平台需要 Python 3.10+，也可通过 `PYTHON` 环境变量指定解释器。执行 `npm pack` 可打包当前仓库自带的内核。
+
+本仓库由 0.5.0 发布包恢复。原先的回归测试集因之前的沙箱重置而丢失，发布包中也没有包含原来的 `test/kernel_regression.py` 和内核同步脚本。CHANGELOG 中的 31/31 是历史记录，当前仓库无法复现该回归集；冒烟测试不代表这 31 项回归已通过。

package/README_EN.md

@@ -0,0 +1,92 @@
+# dsh-plugin-xujie-memory
+
+[简体中文](README.md) | English
+
+Seamless long-term memory built for DeepSeek Harness (DSH).
+
+**The value of memory is not having to think about it.** Xujie-Memory records relevant information locally, assembles memory context, and injects it into the prompt without asking the model to decide whether to call a memory tool. The Windows x64 package includes a runtime and generally requires no extra configuration after installation.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A[Session events] --> B[Filter user messages and injected content]
+    B --> C[Semantic extraction and admission gates]
+    C --> D[SQLite event records and state projections]
+    D --> E[Weight decay and relevant memory recall]
+    E --> F[Exact and fuzzy matching]
+    F --> G[Assemble three memory layers]
+    G --> H[Inject through a prompt section]
+```
+
+Events and projections support traceability and replay; episodic memory and person profiles also have their own storage structures. The default synchronous prompt section reads a cache, so host timing can make the current turn use the previous turn's material. See **Timing and scope** below.
+
+| Feature | Typical tool-calling memory | Xujie-Memory |
+|---|---|---|
+| Retrieval decision | The model usually decides when to call a tool | Context is assembled and injected automatically |
+| Organization | Depends on the implementation | Semantic, episodic, and working memory |
+| Latency | Depends on the tool and implementation | Kernel requests have a cost; the default section reads a cache, while asynchronous mode waits for material |
+| Follow-up limits | Depends on the implementation and prompt | Each item is asked once; at most one per turn and six per session by default |
+| Decay and fuzzy recall | Depends on the implementation | Supports weight decay and fuzzy search |
+
+This compares common design approaches; individual tool-based systems can differ in features and performance.
+
+## Memory layers
+
+- **Semantic:** person card, facts, and explicitly pinned anchors.
+- **Episodic:** original wording and summaries, with fuzzy search for related past events.
+- **Working:** recent messages and unresolved items.
+
+Importance scoring affects how slowly memories fade. Explicit requests such as “remember this” pin an anchor. Retrieval does not reset decay. The kernel also exposes `/memory/mark`, `/memory/curve`, and `/memory/search` endpoints.
+
+## Installation
+
+The package targets the DSH 0.2 preview bundle mechanism and Node.js `^22.19 || >=24`. Windows x64 includes Python and the kernel; no separate Python installation or pip dependencies are needed. On macOS and Linux it falls back to system Python 3.10 or newer.
+
+```bash
+dsh plugin --profile <your-profile> add <path-to-extracted-dsh-plugin-xujie-memory>
+```
+
+When the repository is public, install the tagged version directly from GitHub:
+
+```bash
+dsh plugin --profile <your-profile> add github:Shoren-Syi/dsh-plugin-xujie-memory#v0.5.0
+```
+
+Start a new session. The plugin starts the bundled kernel automatically. By default the database is stored at `~/.xujie-memory/memory.db`. Kernel failure skips memory for that turn rather than blocking the conversation.
+
+Optional profile configuration:
+
+```yaml
+- id: xujie-memory
+  config:
+    endpoint: "http://127.0.0.1:8765"
+    autoStart: true
+    dbPath: ""
+    statusFile: ""
+    maxAskedTotal: 6
+```
+
+Set `statusFile` to a path to record mounting and readiness status. The kernel watchdog checks every five seconds and restarts with backoff; logs are written to `~/.xujie-memory/kernel.log`. Requests require JSON and the `X-Xujie-Token` stored at `~/.xujie-memory/token`.
+
+## Timing and scope
+
+The default `scope: user` shares facts, preferences, anchors, and the person card across sessions. Set `scope: session` for session isolation. The follow-up limit is per session in either mode.
+
+The plugin caches material for up to 32 sessions. The default synchronous `section.text` reads the cache; if the host assembles the prompt before `/turn` completes, it uses the previous turn's material. Set `asyncSection: true` only when the host supports an asynchronous section.
+
+Only `user/message` events are ingested. Runtime context and agent-instruction messages are filtered out, as are assistant and tool events. Each unresolved item is asked at most once; the default session limit is six follow-ups. Reaching the limit does not delete the records.
+
+## Package contents
+
+```text
+lib/index.js             DSH integration and kernel lifecycle
+python/xujie_memory/     Python memory kernel
+python/specs/            Interpretation rules
+runtime/win32-x64/       Bundled Windows x64 Python runtime
+cordis.patch.yml         DSH bundle patch
+```
+
+This repository was reconstructed from the distributed 0.5.0 package. Run `npm test` for the integration smoke test and `npm pack` to package the bundled kernel. Windows x64 uses the bundled Python runtime; other platforms need Python 3.10 or newer. Set `PYTHON` to use a specific interpreter for the smoke test.
+
+The original regression suite was lost when the previous sandbox was reset. The distribution did not include `test/kernel_regression.py` or the kernel synchronization script. The 31/31 result in the changelog is historical and cannot be reproduced from this repository; the smoke test does not replace that regression suite.

package/cordis.patch.yml

@@ -0,0 +1,49 @@
+# 这个 bundle 往配置树里插的一行。
+#
+# `name` 必须是包的**名字**（和 package.json 的 name 一致），
+# `id` 是用户之后覆盖配置时的定位锚点——要稳定，不要和别的插件重名。
+#
+# 注意：DSH 0.2.1-rc.2 要求 patch 文件是**顶层数组**，所以整份内容放在
+# 一个 `- insert:` 列表项里（映射形式会被插件安装校验拒绝）。
+- insert:
+    - id: xujie-memory
+      name: dsh-plugin-xujie-memory
+      config:
+        # Python 内核监听地址；宿主的 section 注入和写记忆都走这条本地 HTTP。
+        endpoint: "http://127.0.0.1:8765"
+
+        # 留空 = 用插件包内自带的 python/ 内核（推荐，装上即用）。
+        # 只有开发时想指向仓库才填绝对路径。
+        repoPath: ""
+
+        # 由插件拉起内核进程。设成 false 就要求你另外手动起服务。
+        autoStart: true
+
+        # 留空 = 用插件包内自带的解释器（runtime/<平台>-<架构>/）。
+        # 只有想换成本机 Python 时才填。
+        pythonPath: ""
+
+        # 留空 = ~/.xujie-memory/memory.db；想换位置或跑测试时填绝对路径。
+        dbPath: ""
+
+        # 一个会话最多主动追问几次。超过之后材料里只剩一句总数。
+        maxAskedTotal: 6
+
+        # 记忆范围（v0.5）：
+        #   user    人物卡/偏好/锚点/账跨会话有效（默认，长期记忆）
+        #   session 每个会话一份、互不相通（0.4 的旧行为）
+        scope: "user"
+
+        # 内核日志；留空 = 与记忆库同目录的 kernel.log（超过 2MB 自动轮转）。
+        logFile: ""
+
+        # 插件与内核共享的鉴权 token 文件；留空 = 与记忆库同目录的 token。
+        tokenFile: ""
+
+        # 宿主若会 await section.text 返回的 Promise，可设为 true：
+        # 组装提示词时最多等 waitMs 毫秒拿这一轮的记忆。宿主不支持就别开。
+        asyncSection: false
+        waitMs: 400
+
+        # 可选诊断文件：宿主 logger 把 info 过滤掉时，用它确认插件挂载/内核就绪。
+        statusFile: ""