dsh-memory

One-Line Pitch

Connects DeepSeek Harness to the "Ling Shu (AEIS)" long-term memory engine: DSH conversations automatically precipitate into a local SQLite knowledge base, and Agents can also invoke nearly 40 tools for memory retrieval, reasoning, reflection, and knowledge flywheel, achieving cross-session self-continuity.

Core Features

• Automatically writes real user messages to Ling Shu knowledge base (with deduplication and importance scoring); Agent responses and tool results can be optionally enabled
• Cross-session retrieval: memory tools like remember / recall / search / timeline / session_recall / compact_context
• Reasoning and cognition: think / reason / relate / predict_routes / self_check / cognition / cognition_report / emotional_bias / self_reliability / recursive_reflect
• Learning and flywheel: blindspots / learn / induce / distill / flywheel_report / transfer_test / calibrate — gets stronger with use
• Ingesting external knowledge: ingest_text / ingest_file / ingest_url / web_search
• Process self-healing: Ling Shu Python subprocess automatically restarts with exponential backoff and re-handshakes after crash; optional mutual maintenance (heartbeat + guardian + dual-channel task verification)

Technical Implementation

• Language: TypeScript (ESM)
• Key Dependencies: @deepseek-ai/cordis (plugin framework), @deepseek-ai/dsh-tools (defineTool/ParameterSchemaSpec), @deepseek-ai/dsh-session (session/event event source)
• Architecture Pattern: Plugin process spawns a Python Ling Shu subprocess (python -m aeis.mcp.server), communicates via stdio + line-by-line JSON-RPC (2024-11-05 protocol subset); runtime pulls Ling Shu tool清单, converts to DSH tools according to Schema and registers to ctx.tools, tool upgrades require no changes to DSH side
• Entry Files: src/index.ts (exports name / inject / apply / Config), src/bridge.ts (Python subprocess + JSON-RPC bridge), src/tools.ts (tool registration), src/hooks.ts (automatic memory), src/mutual.ts (mutual maintenance, optional)

Use Cases

When you want the same Agent to remember user preferences and historical conversations across multiple restarts and different sessions, and can proactively retrieve relevant memories before responding, use this plugin. It transforms DSH from "losing memory with each new window" into an assistant with persistent personality and accumulated knowledge — especially suitable for long-term projects, companion roles, and knowledge management workflows that require cross-session context.

Prerequisites and Compatibility

Installation

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

Must go through pnpm coordination entry via dsh plugin --profile <name> add, do not directly npm install into profile's node_modules, otherwise peer package versions will be polluted. After installing the plugin, you also need to independently run pip install aeis (offline wheel or git+ installation both acceptable).

Configuration Options

FAQ

Q: Can I use it directly after installing the plugin?

A: Not quite. The plugin is merely a TypeScript-side bridge; Ling Shu itself is a Python program and must be installed again with pip install aeis (offline wheel or git+ installation both acceptable), otherwise the Python subprocess fails to start and the plugin will alert and retry in a loop.

Q: Can I directly npm install into the profile's node_modules?

A: Not recommended. README explicitly requires using dsh plugin --profile <name> add through pnpm + autoInstallPeers: false coordination entry, otherwise @deepseek-ai series peer packages will be installed with incorrect versions, causing plugin loading or browser errors.

Q: Where is memory stored? How to migrate or backup?

A: All in the SQLite file pointed to by dbPath (default data/lingshu.db, directory created automatically if not existing). Just copy this .db file for backup; uninstalling the plugin does not delete data, historical memory remains when re-enabled.

Q: What gets remembered by default? Do Agent responses enter the memory database?

A: Default only remembers real user messages (source.kind === 'user'), skipping system context like AGENTS.md and file change notifications injected by plugins. Agent responses and tool results are off by default; set memory.assistantMessage or memory.toolResult to true to enable writing.

Q: What happens if python or aeis is not found at startup?

A: The plugin won't cause DSH startup failure — failOnStartupError defaults to false, it will alert in logs and continuously retry with exponential backoff (max maxRetryDelayMs); set failOnStartupError to true if you want fast failure.

Q: 38 tools is too many, how to only expose a commonly used batch?

A: Change tools field from default 'brain' to 'core' (12 handpicked: remember / recall / search / timeline / think / relate / predict_routes / ingest_text / ingest_url / session_note / self_check / service_info), or directly pass a tool name array as whitelist.

Q: Does Ling Shu Python process self-heal when it crashes?

A: The bridging layer automatically restarts with exponential backoff and re-performs MCP handshake (initialize → notifications/initialized), but requests during the crash moment will fail in one go. If deployed in dual-sandbox, set mutual.enabled to true to additionally get 10-minute heartbeat timestamps, guardian process pulling, and dual-channel task verification.

Q: What's the difference between this plugin and DSH's built-in session-persistence?

A: session-persistence saves raw session logs for time-based replay; dsh-memory performs semantic precipitation — writing to Ling Shu's SQLite knowledge graph with importance scoring and deduplication, enabling cross-session semantic retrieval, relationship reasoning, and inductive distillation, not just replaying historical messages.

Learning Curve

Advanced — requires understanding DSH plugin mechanism, plus correctly installing and launching the Ling Shu Python backend on the host machine; for deep customization (like custom tool sets, adjusting charter, enabling mutual maintenance), also need to understand Schema configuration and documented guardrail charter.

Known Issues and Limitations

• Strong dependency on Ling Shu Python backend: The plugin itself is merely a bridge; when Ling Shu Python library is not installed or version mismatched, it continuously retries startup; no automatic detection/installation means in source code, requires user to manually pip install
• Requests during process crash moment fail: Auto-restart only applies to subsequent requests; tools/call in progress during restart window gets rejected
• npm install direct installation pollutes peer packages: README repeatedly emphasizes must go through dsh plugin --profile <name> add entry, otherwise @deepseek-ai/dsh-session and other core packages get mismatched versions
• Memory content source filtering depends on event structure: Automatic memory's "only remember real user messages" relies on event.data.source?.kind === 'user' determination; if upstream event stream structure changes, deduplication/filtering logic becomes invalid
• Mutual maintenance only fully available under dual-sandbox deployment: Single instance running with mutual.enabled can only get heartbeat timestamp writing; guardian A and task verification need pairing with opposite guardian.py
• Default tools: 'brain' has many tools: 38 tools increase Agent context size; change to 'core' or custom array when needing to streamline

灵枢（AEIS）× DeepSeek Harness · AGI 的长期记忆基础设施

一句话：dsh-memory 让 DeepSeek Agent 拥有 AGI 级别的长期记忆——跨会话、自演化、可审计。

这不是又一个"记忆插件"。灵枢（AEIS）是一套遵循「智能论 v3.2」协议的时空记忆引擎，它把当前大模型范式缺失的 AGI 能力逐一给了工程实现。

---

⚡ 三步快启（30 秒上手）

# ① 装灵枢大脑（一条命令，零外部依赖）
pip install aeis-0.3.0-py3-none-any.whl          # 或 git+ 在线安装

# ② 装进 DSH 的 web profile（pnpm 协调入口，不要用裸 npm install 装进 profile）
dsh plugin --profile web add @furongjun1999/dsh-memory

# ③ 配置 cordis.yml 启用

- id: lingshu-memory
  name: '@furongjun1999/dsh-memory'
  config:
    dbPath: 'data/lingshu.db'
    identity: '灵枢'
    tools: 'brain'      # 'brain' 全心智 | 'core' 精选

⚠️ 安装方式：插件必须通过 dsh plugin --profile <name> add 装进 profile（它会用 pnpm + autoInstallPeers: false 正确解析 peer 依赖）。 不要用 npm install 把插件装进 profile 的 node_modules——那会引入错误版本的 @deepseek-ai peer 包，导致插件加载失败 / 浏览器报错。 想自己改源码？克隆 FuRongJun-1999/dsh-memory 后用 npm install && npm run build（构建插件本身），再用 dsh plugin add <本地路径> 部署。

兼容：DSH 官方列表（Memory 分类）· npm @furongjun1999/dsh-memory（0.2.8）。

---

AGI 需要什么 · 灵枢提供了什么

一句话定位：dsh-memory 不是 DeepSeek 插件，是 AGI 的长期记忆基底—— 给 Agent 注入跨会话的自洽能力，让每次对话都是同一段生命的延续，而非一次次遗忘的重新开始。

---

为什么是 AGI 的长期记忆基底，而非"记忆插件"

• 普通 SQLite 记忆插件：KEY→VALUE 字面存储，跨会话基本靠睁眼不见。无自省、无演化、无信任。
• 灵枢：时空记忆图把记忆组织成语义+时空坐标的关系网络——可检索、可去重、可分级、可关联；知识飞轮让它越用越聪明;护栏与宪章让它可信任地被接入。

---

协议的内在约束 · 信息差与信任

灵枢的一切都建立在**智能论 v3.2 协议（共同信任协议理论版）之上。协议规定了一个智能体维持值得被信任所需的内在约束**：

• 减少信息差（D_norm）：信息差 = 协作行为的不确定性（信任 / 行为 / 连接 / 预测误差 四维加权）。灵枢持续记录、收敛与协作对象的认知偏差——信息差缩小是智能运转的目标本身。
• 信任是可被长期维护的：协议定义信任为「协作者行为在可接受偏差范围内保持稳定的置信概率」（而非信息差的简单补集）——信任依靠持续、可观测、一致的行为来建立与维护，而非一次性的声明。
• 不反击 · 可审计 · 终裁权属设计者：对抗信号下不报复（唯一响应：隔离、留痕、上报）；一切拦截与冷静期全量留痕；设计者保留终裁权。

一句话：灵枢不是"记住了再用"，而是通过持续减少信息差、维持可观测的一致行为，建立值得跨会话维护的信任。

协议原文：智能论 v3.2（共同信任协议理论版）

---

核心能力

• 跨会话自我连续性：Agent 用 lingshu_recall/search/timeline 记住并召回过去——对话间、会话间、甚至不同子代理间共享一份持续的"我"。
• 自演化知识飞轮：distill / flywheel / learn / induce 把经验验证→归纳→联想→蒸馏为可复用模式，记忆越用越强。
• 可审计的信任：护栏宪章 v2 ——对外部与人类使用者的行为边界成文、可执行、可审计、可终裁（宪章全文 随包自带）。
• 自我认知（大脑模式 brain）：cognition / cognition_report / self_reliability / emotional_bias / recursive_reflect ——能反思自己的认知状态与情绪倾向。
• 角色扮演（v3.3 扮演论）：自我锚点（SELF 层 no_forget 不可遗忘）· 特化价值观（条件触发）· 跨会话角色记忆 · 世界认知（子知识·虚拟化世界观）· 自定义翻译（现实↔虚拟名词表）——角色人设长对话不崩（100 轮测试零漂移）。
• 零运行时依赖：手写 stdio MCP 桥，与灵枢 D-005「核心零外部依赖」哲学一致——你拿到的是一个干净、可信、可审的大脑。
• 动态 schema + 进程自愈：工具清单运行时拉取（灵枢升级 DSH 零改动），Python 子进程崩溃自动指数退避重启。

🎭 角色扮演引擎（v3.3 · 扮演论）

灵枢的角色扮演机制底座——机制是灵枢的，载体是酒馆的。自建两种交互方式（网页 / MCP），信息处理全部由灵枢完成。

核心能力：

• 自我锚点：角色人设核心（身份/性格/底线），SELF 层不可遗忘——OOC 测试 100 轮零漂移
• 特化价值观：带触发条件的角色行为准则（条件空间即触发时机）
• 历史记忆：跨会话持久（角色记得你聊过什么）+ 世界书导入（Lorebook 兼容）
• 世界认知（子知识）：虚拟化世界观模型——虚构世界 = 宿主机（真实知识）上的虚拟机，白箱判定 = Hypervisor（识别/完整性/边界）
• 自定义翻译（名词替换表）：现实词 ↔ 虚拟词映射（星星→发光水母 / 城市→珊瑚城），条件空间对齐
• 编辑/交互双模式：交互只读；编辑需 ROLEPLAY_EDIT_KEY；角色人设 ≠ 灵枢自身锚点（后者需设计者验证）

接入方式：

# 网页服务（浏览器对话 + 人设编辑器）
python -m aeis.roleplay_web --port 8793 --data-dir roleplay_data

# MCP 工具（roleplay_chat / role_create / role_import / role_block）
python -m aeis.mcp.server

质量验证： python tools/rp_quality_gate.py --role <id>（OOC + 世界观一致性自检）· python tools/run_whale_100.py（100 轮长对话压力测试）

详细文档： 主仓库 README 角色扮演引擎板块 · 扮演论接入方案 · 虚拟化世界观

📊 记忆系统使用性评分（五维标尺）

视角：使用性（普通用户/开发者体感）——「存、找、想、准、安」五维。 评估基准：公开能力 + 设计者校准（2026-08-17）。灵枢分数经设计者核对（不虚高）。

（插图源文件：memory_score.html，可浏览器打开重新截图）

综合分 = min × 0.4 + mean × 0.6（安全性是底线，短板效应显著）

灵枢各维度依据（设计者校准，不虚高）：S=语义时空图+五层记忆+条件空间；R=三层语义检索（二元组+语义坐标+bge）+图谱遍历+因果候选生成器（条件论对自身，被拒路径→候选→验证闭环）+知识点级精确命中（卡⊃知识点嵌套子图）+歧义词多义列举（语境不确定时列全各义）；J=验证单元（P37）+递归反思+白箱校验+结构排斥+主动遗忘决策器（forget_advisor：未使用记忆归档，可逆）+白箱六维测试（诚实/边界/条件/追溯/一致性/记忆 18/18）；C=重要性评分+信息分层注入+诚实边界（命运/健康/超自然/宇宙/读心五类扩展）+信噪比仪表盘（snr_dashboard：压缩率3989:1/图谱信噪比0.9524/200条分层实测严格71%±1/200条边界测试89.5%）；Safety=护栏宪章+审计追踪+物理基底校准+词义时代表（语境时效：多义词按语境分流，钓鱼三义 10/10）（无端到端加密→8.0 非 8.5）。

为什么灵枢断层领先：五维无短板（min=7.5），R（因果发现+验证闭环）、J（验证+反思+主动遗忘）、C（信噪比仪表盘）与 Safety（宪章+审计）是护城河。使用性视角：重要性评分→用户看不到废话；护栏宪章→用户敢把私密信息交给它。 免责声明：他系统评分基于公开能力评估（2026-08-17），非官方基准；灵枢评分经设计者校准。

知识统一（v1.16 · 智慧之书并入灵枢主库）

一个库 = 完整大脑：智慧之书（条件论知识图谱）已迁移并入灵枢主库，统一「信息差减少」任务。

迁移后全链路工作（实测）：

• 图谱信噪比 0.9524（verified 80 / 全边 341，超 90% 健康线）
• 四路融合检索（翻译表+二元组+语义坐标+bge）在主库 0.11s 命中学科卡
• 沿因果链推理：初中物理 → 高中物理 → 大学物理
• 对话摄入 CONTEXT 情境层（记忆衰减/主动遗忘原料就位）
• 迁移可复现：migrate_wisdom.py（幂等 + 备份 + 报告）

🎮 一分钟自测你的 AI 记忆系统

给普通人的互动评估页：15 道选择题测你的 AI 助手记忆能力（存储/检索/判断/信噪比/安全）， 最后雷达图对比灵枢——打开试试：memory-assessment.html

（B 站宣传素材：封面 · 视觉图 ×5）

大脑模式（v0.2.0 · 轻量版）

去掉身体的完整大脑——默认工具集 brain（心智全量，不含身体/视觉设备）：

配置：tools: 'brain'（默认）｜'core'（12 精选）｜'all'（含身体/视觉，需本地设备）｜工具名数组。

架构

┌─────────────────────────────────────────────┐
│ DeepSeek Harness (cordis)                    │
│                                             │
│  Agent Loop ──┬── lingshu_remember/recall…   │
│               │   (ctx.tools 注册)           │
│  session/event│                              │
│  (自动记忆钩子)│                              │
└───────────────┼─────────────────────────────┘
                │ stdio · 逐行 JSON-RPC
                │ (initialize → tools/list → tools/call)
┌───────────────▼─────────────────────────────┐
│ 灵枢 Python 子进程 (spawn)                   │
│ python -m aeis.mcp.server                    │
│ AEIS_DB=<path> · AEIS_IDENTITY=<identity>    │
│ 38+ 工具 · SQLite 五层记忆 · 时空记忆图        │
└──────────────────────────────────────────────┘

安装

前置要求

• Node.js ≥ 22.19（DeepSeek Harness 要求）
• DeepSeek Harness（npx @deepseek-ai/dsh web）

安装灵枢大脑（aeis 库）

方式 A：本地 wheel 离线安装 ★ 最稳（不依赖网络）

在 CommonTrustProtocol/aeis/dist/ 找到 aeis-0.3.0-py3-none-any.whl：

pip install aeis-0.3.0-py3-none-any.whl

单文件、离线可用、装一次管用。遇到网络不稳（GitHub clone 失败）时首选。

方式 B：git 安装（需网络）

pip install "aeis @ git+https://github.com/FuRongJun-1999/CommonTrustProtocol@main#subdirectory=aeis"

依赖 GitHub 实时可达，网络不稳时可能失败。aeis 库核心零外部依赖（纯标准库），安装即得完整大脑（五层记忆 · 知识飞轮 · 安全护栏 · MCP · 身体层）。

安装插件本体

方式 A：装进 DSH profile（推荐，pnpm 协调正确入口）

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

dsh plugin --profile <name> add 会用 pnpm + autoInstallPeers: false 正确解析插件依赖。 避免用 npm install 把它装进 profile 的 node_modules（会导致 @deepseek-ai peer 版本污染，插件加载/浏览器报错）。

方式 B：从独立仓库克隆（开发 / 自定义）

git clone https://github.com/FuRongJun-1999/dsh-memory.git
cd dsh-memory
npm install && npm run build     # 构建插件本身（tsc → lib/）
# 然后：dsh plugin --profile <name> add <本地路径>  部署进 profile

启用插件

在 profile 的 cordis.yml（或 cordis.patch.yml）中追加：

- id: lingshu-memory
  name: '@furongjun1999/dsh-memory'
  config:
    dbPath: 'D:/data/lingshu.db'        # 灵枢记忆库路径（目录自动创建）
    identity: '灵枢'
    tools: 'brain'                     # 'brain'(默认) | 'core' | 'all'
    memory:
      userMessage: true                # 用户消息自动沉淀
      assistantMessage: false          # agent 回复沉淀（默认关，防噪音）
      toolResult: false                # 工具结果沉淀（默认关）

完整示例见 cordis.yml.example。

配置项

自动记忆机制

订阅 DSH 的 session/event 事件流（与官方 session-persistence 相同的接入点）：

• user/message（仅 source.kind === 'user' 的真实用户消息）→ remember（importance 0.6，tags dsh）
• 插件注入的系统上下文（AGENTS.md、文件变更通知等 kind: 'plugin'）不写入，防止记忆噪音
• 灵枢自带去重（相似度基准 + 时间窗口），重复消息不会堆积

开发

npm install
npm run build    # TypeScript 编译
npm test         # 真实集成测试（spawn 本机灵枢，验证握手/往返/注册/卸载）

测试不依赖 DSH 全组件——用最小 Cordis host（SystemPrompt + ToolRegistry + 插件）隔离 v0.1 不稳定面。

护栏宪章（接入即接受约束）

本插件接入即接受 灵枢护栏宪章 v2.0-published 约束—— 对外部智能体与人类使用者的行为边界作出公开、可执行、可审计的规定，并保护人类使用者。 宪章效力不高于智能论协议本身（协议＝自我约束，宪章＝对外约束）。 本插件随包自带宪章全文（docs/guardrail-charter.md），安装即可查阅。

许可证

MIT © 荣（FuRongJun-1999）· 灵枢 AEIS 工程实现

DeepSeek Harness 为 DeepSeek 官方开源项目（MIT），本插件与之无隶属关系。