# dsh-memory

> 为 DSH 接入灵枢（AEIS）长期记忆：自动把用户对话沉淀进 SQLite 知识库，并动态暴露记忆、推理、反思、飞轮等工具。

## Metadata

- Author: [@FuRongJun-1999](https://github.com/FuRongJun-1999)
- Repo: <https://github.com/FuRongJun-1999/dsh-memory.git>
- GitHub: [FuRongJun-1999/dsh-memory](https://github.com/FuRongJun-1999/dsh-memory)
- Stars: 25
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `agent-safety`, `agentic-ai`, `agi`, `ai-agent-framework`, `deepseek`, `dsh-plugin`, `explainable-ai`, `guardrails`, `knowledge-graph`, `mcp`, `multi-agent`, `persistent-memory`, `rag`, `spatiotemporal-graph-neural-network`
- Forks: 1
- Open Issues: 2
- Last push: 2026-08-19T11:50:57.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add @furongjun1999/dsh-memory
```

## Wiki

## 一句话定位
为 DeepSeek Harness 接入"灵枢（AEIS）"长期记忆引擎：DSH 的对话会自动沉淀进本地 SQLite 知识库，Agent 也能调用记忆检索、推理、反思、知识飞轮等近 40 个工具，实现跨会话的自我连续性。

## 核心能力
- 自动把真实用户消息写入灵枢知识库（带去重与重要性评分），Agent 回复与工具结果可按需开启
- 跨会话检索：remember / recall / search / timeline / session_recall / compact_context 等记忆工具
- 推理与认知：think / reason / relate / predict_routes / self_check / cognition / cognition_report / emotional_bias / self_reliability / recursive_reflect
- 学习与飞轮：blindspots / learn / induce / distill / flywheel_report / transfer_test / calibrate，越用越强
- 摄取外部知识：ingest_text / ingest_file / ingest_url / web_search
- 进程自愈：灵枢 Python 子进程崩溃后会自动指数退避重启并重新握手；可选开启互维维护（心跳 + 守护 + 任务验证双通道）

## 技术实现
- **语言**: TypeScript（ESM）
- **关键依赖**: `@deepseek-ai/cordis`（插件框架）、`@deepseek-ai/dsh-tools`（defineTool/ParameterSchemaSpec）、`@deepseek-ai/dsh-session`（session/event 事件源）
- **架构模式**: 插件进程 spawn 一个 Python 灵枢子进程（`python -m aeis.mcp.server`），通过 stdio + 逐行 JSON-RPC（2024-11-05 协议子集）通信；运行时拉取灵枢工具清单，按 Schema 转换为 DSH 工具并注册到 `ctx.tools`，工具升级无需改 DSH 端
- **入口文件**: `src/index.ts`（导出 `name` / `inject` / `apply` / `Config`），`src/bridge.ts`（Python 子进程 + JSON-RPC 桥），`src/tools.ts`（工具注册），`src/hooks.ts`（自动记忆），`src/mutual.ts`（互维维护，可选）

## 适用场景
当你希望同一个 Agent 在多次重启、不同会话之间仍记得用户的偏好与历史对话，并能在回答前主动检索相关记忆时，使用本插件。它适合把 DSH 从"每次开新窗口都失忆"升级为有持续人格和累积知识的助手——尤其是长程项目、陪伴型角色、知识管理工作流这类需要跨会话上下文的场景。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness | >= 0.1.0-rc.6 | peer 依赖锁定 `@deepseek-ai/dsh-session` 与 `@deepseek-ai/dsh-tools` ^0.1.0-rc.6 |
| 灵枢 Python 库（aeis） | 0.3.0 | 必须额外 `pip install` 安装，否则 Python 子进程无法启动 |
| Node.js | >= 18（engines） | README 同时声明 DSH 宿主需 Node ≥ 22.19 |
| 平台 | 跨平台 | spawn 使用 `windowsHide: true`，macOS/Windows/Linux 均可 |
| 原生模块 | 无 | 插件本身零原生依赖；灵枢 Python 侧核心也声明零外部依赖 |

## 安装方式
```bash
dsh plugin --profile web add @furongjun1999/dsh-memory
```

> 必须通过 `dsh plugin --profile <name> add` 走 pnpm 协调入口，不要直接 `npm install` 进 profile 的 node_modules，否则 peer 包版本会污染。装完插件后还需独立 `pip install aeis`（离线 wheel 或 git+ 安装均可）。

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `serverName` | string | 工具名前缀，注册到 DSH 后是 `<前缀>_<工具名>` | `lingshu` |
| `python` | string | Python 可执行文件路径 | `python` |
| `moduleArgs` | string[] | 传给 python 的启动参数 | `['-m', 'aeis.mcp.server']` |
| `dbPath` | string | 灵枢 SQLite 记忆库路径，目录不存在会自动创建 | `data/lingshu.db` |
| `identity` | string | 灵枢的身份标识，写入自我模型 | `灵枢` |
| `env` | object | 追加到子进程的环境变量（API Key 等密钥可经 `!!js process.env.X` 注入） | `{}` |
| `tools` | `'core'` \| `'brain'` \| `'all'` \| 工具名数组 | 暴露给 Agent 的工具集合；`core` 12 个精选，`brain` 38 个默认，`all` 全量 | `brain` |
| `charter` | string | 接入即接受的护栏宪章版本号（详见 `docs/guardrail-charter.md`） | `v2.0-published` |
| `memory.userMessage` | boolean | 是否自动把用户消息写入记忆库 | `true` |
| `memory.assistantMessage` | boolean | 是否把 Agent 回复写入记忆库（默认关闭防噪音） | `false` |
| `memory.toolResult` | boolean | 是否把工具调用结果写入记忆库（默认关闭防噪音） | `false` |
| `memory.importance` | number | 自动写入记忆的重要性分（0~1） | `0.6` |
| `toolCallTimeoutMs` | number | 单次工具调用超时时间（毫秒） | `60000` |
| `maxRetryDelayMs` | number | 灵枢进程崩溃后重试的最大退避间隔（毫秒） | `30000` |
| `failOnStartupError` | boolean | 启动失败时是否让 DSH 插件激活失败；关掉则告警后继续后台重试 | `false` |
| `mutual.enabled` | boolean | 是否启用互维维护（心跳 + 守护 + 任务验证双通道，需双沙箱部署） | `false` |
| `mutual.heartbeatMs` | number | 互维维护心跳间隔（毫秒） | `600000` |

## 常见问题

**Q: 装完插件就能直接用吗？**

A: 还不行。插件只是 TypeScript 端的桥，灵枢本身是 Python 程序，必须再装一次 `pip install aeis`（离线 wheel 或 `git+` 安装均可），否则 Python 子进程启动失败，插件会告警并循环重试。

**Q: 能不能直接 `npm install` 装到 profile 的 node_modules 里？**

A: 不建议。README 明确要求用 `dsh plugin --profile <name> add` 走 pnpm + `autoInstallPeers: false` 的协调入口，否则 `@deepseek-ai` 系列 peer 包会被装成错误版本，导致插件加载或浏览器报错。

**Q: 记忆存放在哪里？如何迁移或备份？**

A: 全部在 `dbPath` 指向的 SQLite 文件里（默认 `data/lingshu.db`，目录不存在会自动创建）。备份直接拷贝这个 `.db` 文件即可；卸载插件不会删除数据，重新启用后历史记忆仍在。

**Q: 默认会记住哪些内容？Agent 回复会进记忆库吗？**

A: 默认只记忆真实用户消息（`source.kind === 'user'`），跳过插件注入的 AGENTS.md、文件变更通知等系统上下文。Agent 回复与工具结果默认关闭，需要时把 `memory.assistantMessage` 或 `memory.toolResult` 设成 `true` 才会写入。

**Q: 启动时找不到 python 或 aeis 会发生什么？**

A: 插件不会让 DSH 启动失败——`failOnStartupError` 默认是 `false`，会在日志里告警并按指数退避（最长 `maxRetryDelayMs`）持续重试；想要快速失败就把 `failOnStartupError` 改成 `true`。

**Q: 38 个工具太多了，如何只暴露常用的一批？**

A: 把 `tools` 字段从默认的 `'brain'` 改成 `'core'`（12 个精选：remember / recall / search / timeline / think / relate / predict_routes / ingest_text / ingest_url / session_note / self_check / service_info），或者直接传一个工具名数组做白名单。

**Q: 灵枢 Python 进程崩了会自愈吗？**

A: 桥接层会按指数退避自动重启并重新走 MCP 握手（`initialize` → `notifications/initialized`），但崩溃瞬间挂起的请求会一次性失败。若部署在双沙箱里，把 `mutual.enabled` 设成 `true` 可以额外获得 10 分钟心跳写戳、守护进程拉起与任务验证双通道。

**Q: 这个插件和 DSH 自带的 session-persistence 有什么区别？**

A: session-persistence 保存的是会话日志原文，按时间回放；dsh-memory 把消息做语义沉淀——写入灵枢的 SQLite 知识图谱、带重要性评分和去重，可以跨会话做语义检索、关系推理、归纳蒸馏，而不是仅仅回放历史消息。

## 上手难度
进阶 — 需要理解 DSH 插件机制，还要在宿主机上正确安装并启动灵枢 Python 后端；如果想做深度定制（如自定义工具集、调整宪章、启用互维维护），还需要读懂 Schema 配置与文档化的护栏宪章。

## 已知问题与限制
- **强依赖灵枢 Python 后端**：插件本身只是桥，灵枢 Python 库未安装或版本不匹配时会持续重试启动；源码中无自动检测/安装手段，需用户自行 `pip install`
- **进程崩溃瞬间的请求会失败**：自动重启只对后续请求生效，重启窗口内正在进行的 `tools/call` 会被 reject
- **`npm install` 直装会污染 peer 包**：README 多次强调必须经 `dsh plugin --profile <name> add` 入口，否则 `@deepseek-ai/dsh-session` 等核心包版本错配
- **记忆内容来源过滤依赖事件结构**：自动记忆的"只记真实用户消息"靠 `event.data.source?.kind === 'user'` 判定；如果上游事件流结构变化，去重/过滤逻辑会失效
- **互维维护仅在双沙箱部署下完整可用**：单实例运行开启 `mutual.enabled` 也只能获得心跳写戳，守护 A 与任务验证需要与对侧 guardian.py 配对
- **默认 `tools: 'brain'` 工具数量较多**：38 个工具会让 Agent 上下文变大，需要精简时改 `'core'` 或自定义数组

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-memory](https://deepseek-plugin.org/plugins/FuRongJun-1999/dsh-memory)
Wiki generated by AI (model: `MiniMax-M3`)