DSH 长期记忆插件

观测、学习、记忆。为 DeepSeek Harness (DSH) 打造的自进化记忆系统，同时也支持 OpenCode。

这个插件让 AI 助手拥有跨会话记忆能力——它会观测你的工具使用方式、提炼行为模式（「本能」），并在对话中召回相关记忆，提供上下文感知的智能辅助。

核心能力

功能概览

能力	说明
工具观测	自动捕获每次工具调用的输入和输出，记录行为数据
模式提炼	结合统计分析和语义分析，自动发现你的工作习惯和偏好
记忆注入	在对话中自动召回相关记忆，并注入到系统提示中
规则进化	高置信度的行为模式会自动生成 `auto-evolved.md` 规则文件
对话持久化	将完整对话历史存入 LanceDB，支持后续检索和分析
项目隔离	记忆按项目作用域隔离，避免跨项目污染

双记忆系统

┌────────────────────────────────────┐    ┌────────────────────────────────────┐
│     Instinct 系统（行为记忆）        │    │      Memory 系统（知识记忆）         │
├────────────────────────────────────┤    ├────────────────────────────────────┤
│ 数据来源：工具调用观测记录            │    │ 数据来源：用户与 AI 的对话内容        │
│ 提炼方式：统计 + AI 语义分析          │    │ 提炼方式：AI 语义判断                │
│ 存储格式：instincts.jsonl            │    │ 存储格式：memories.jsonl             │
│ 作用范围：全局（所有项目共享）         │    │ 作用范围：项目级（含全局记忆）        │
│ 生命周期：置信度演化 + 衰减            │    │ 生命周期：按类型 TTL 过期             │
│ 注入方式：auto-evolved.md            │    │ 注入方式：会话预加载 + 实时召回       │
└────────────────────────────────────┘    └────────────────────────────────────┘

安装与使用

DSH 插件命令安装（推荐）

npx @deepseek-ai/dsh plugin --profile web add dsh-plugin-long-term-memory@latest

一条命令完成安装与注册：DSH 加载 bundle 时自动读取包内 dsh.bundle.patch 声明的 cordis.patch.yml，将插件挂载为 profile layer。无需手动在项目根创建 cordis.yml 或指向构建产物路径。

验证安装：

npx @deepseek-ai/dsh plugin --profile web list

关于 peer dep 警告：DSH 自身的 web profile 自带 @deepseek-ai/[email protected]，期望的 [email protected] 与本插件用 [email protected] 期望的 [email protected] 不兼容。pnpm 会同时装两个 minor-rc 版本（无害），最终日志里会出现 Conflicting peer dependencies。这是 DSH 生态自身的版本漂移，与本插件无关——dsh web 仍可正常启动，本插件按 [email protected] 的 API 编写，无法也不应降级。此外 apache-arrow@17 的 bin 路径已从 .cjs 改为 .js/.mjs，pnpm 的 Failed to create bin at ... arrow2csv 是无害警告（不影响 lancedb 运行时 require）。

配置文件：~/.config/dsh/long-term-memory.jsonc（首次启动自动生成模板）
数据目录：默认 ~/.local/share/dsh/long-term-memory/
验证加载：export LONG_TERM_MEMORY_DEBUG=1 后启动 DSH，查看 ~/.local/share/dsh/long-term-memory/plugin.log 应出现 plugin loaded (tools + hooks + prompt registered)
沙箱兼容：若终端沙箱（TRAE/EDR）拦截 ~/.dsh 写入，可用 HOME=$PWD/.fake-home npx @deepseek-ai/dsh plugin --profile web add dsh-plugin-long-term-memory@latest 临时重定向

已知限制：DSH preview API 易变（锁 @deepseek-ai/[email protected]）；turn/end 触发的本能分析带 5 分钟防抖。

从源码构建

git clone https://github.com/yuqiangcn/dsh-plugin-long-term-memory.git
cd dsh-plugin-long-term-memory
pnpm install
pnpm build:dsh

OpenCode — 兼容

本插件也保留了 OpenCode 入口（src/index.ts），与 DSH 共享同一套引擎。

pnpm build

配置方式与 DSH 侧类似，配置文件位于 ~/.config/opencode/opencode-plugin-long-term-memory.jsonc。

配置方式

插件支持两种配置方式：

方式	适用场景	难度
什么都不配	想快速体验，默认 TF-IDF + 全功能开	⭐
JSONC 配置文件（推荐）	日常使用，团队统一配置	⭐⭐

配置文件位置

DSH 侧：

~/.config/dsh/long-term-memory.jsonc

OpenCode 侧：

~/.config/opencode/opencode-plugin-long-term-memory.jsonc

Linux/macOS 遵循 XDG 规范，可用 XDG_CONFIG_HOME 环境变量覆盖基目录
JSONC 格式（支持 // 注释、尾随逗号、${ENV_VAR} 环境变量引用）
任何字段缺失或类型错误 → 降级到默认值 + error 日志，不影响插件启动

顶层字段

字段	类型	默认值	说明
`dataDir`	string	`~/.local/share/dsh/long-term-memory`	数据存储目录。更改后旧数据不自动迁移，需手动复制
`observationEnabled`	bool	`true`	开启工具观测。记录每次工具调用的输入/输出到 `observations.jsonl`
`autoInject`	bool	`true`	自动将相关记忆注入系统提示（会话预加载 + 实时召回）
`autoAnalyze`	bool	`true`	会话结束后自动分析行为模式，生成 Instinct
`autoExtractMemory`	bool	`false`	从对话内容自动提炼记忆。需要配置 `ai` 块
`semanticAnalysis`	bool	`false`	启用 LLM 语义分析提炼行为模式。需要配置 `ai` 块
`maxRecallCount`	number	`5`	每次对话最多召回多少条记忆
`recallThreshold`	number	`0.3`	召回最低相似度（0=不召回，1=完全匹配）
`injectPosition`	enum	`"system"`	注入位置：`"system"` 注入系统提示 / `"user"` 注入用户消息
`statisticalMinOccurrences`	number	`3`	行为模式最少出现几次才被统计检测为 Instinct
`analyticsEnabled`	bool	`true`	启用 Analytics 埋点。`memory_analytics` 工具可生成质量报告
`ai`	object	-	AI 模型配置（控制语义分析 / 记忆提炼 / 沉淀整理）。见下
`embedding`	object	-	Embedding 配置（控制语义检索质量）。不配则用本地 TF-IDF（零依赖）。见下
`autoMaterialize`	object	-	项目知识沉淀配置（把决策/Bug/模式沉淀到 `docs/`）。见下

`ai` 块 — AI 模型配置

控制三个 AI 行为：语义分析、记忆提炼、沉淀整理。只要开启 semanticAnalysis 或 autoExtractMemory 或 autoMaterialize.organization.enabled，就必须配置此块。

字段	类型	默认值	说明
`provider`	enum	`"openai"`	`"openai"` / `"zhipu"`（智谱，国内推荐）/ `"custom"`（OpenAI 兼容端点）
`model`	string	`"gpt-4o-mini"`	模型名。OpenAI 例：`gpt-4o-mini` / `gpt-4o`；智谱例：`glm-4-flash` / `glm-4-plus`
`apiKey`	string	-	API key。建议用 `"${ENV_VAR}"` 引用环境变量
`baseUrl`	string	-	自定义端点。`custom` 必填；`openai`/`zhipu` 留空则用默认值
`temperature`	number	-	生成温度（0-2）。建议 0.1-0.3 保持稳定
`maxTokens`	number	-	最大输出 tokens

`embedding` 块 — 向量嵌入配置

控制语义检索质量。留空 = 本地 TF-IDF（关键词匹配，零依赖）。

字段	类型	默认值	说明
`provider`	enum	`"openai"`	`"openai"` / `"zhipu"` / `"custom"`
`model`	string	`"text-embedding-3-small"`	模型名
`apiKey`	string	-	API key。写法同 `ai` 块
`baseUrl`	string	-	自定义端点。`custom` 必填
`dimensions`	number	-	输出向量维度。仅智谱 `embedding-3` 有效（256/512/1024/2048）

`autoMaterialize` 块 — 项目知识沉淀配置

把高价值记忆（决策 / 项目 / Bug / 模式）沉淀到 docs/project-context.md，作为团队共享文档。

字段	类型	默认值	说明
`mode`	enum	`"assisted"`	`"disabled"` 纯手动 / `"assisted"` 会话结束提示候选（默认） / `"auto"` 满足阈值自动写入
`types`	array	`["decision", "project", "bug", "pattern"]`	允许沉淀的记忆类型。不能包含 `user` / `profile` / `feedback`（隐私保护）
`thresholds.minConfidence`	number	`0.85`	`auto` 模式的最低置信度门槛
`thresholds.minAccessCount`	number	`3`	`auto` 模式的最低访问次数门槛
`output.path`	string	`"docs/project-context.md"`	输出文件路径（相对项目根目录）
`output.autoGeneratedMark`	string	`"[Auto-generated]"`	自动生成条目的前缀标记
`organization.enabled`	bool	`true`	是否用 LLM 整理。关闭后直接拼接。需要 `ai` 块
`organization.temperature`	number	`0.2`	LLM 整理温度
`autoReferenceInAgents`	bool	`true`	沉淀成功后是否在项目根 `AGENTS.md` 中追加 `## Project Knowledge` 章节

完整配置示例

最小可用（啥都不配）：

{}

推荐配置（语义检索 + 自动沉淀，国内环境）：

{
  "dataDir": "~/.local/share/dsh/long-term-memory",

  "observationEnabled": true,
  "autoInject": true,
  "autoAnalyze": true,
  "semanticAnalysis": true,
  "autoExtractMemory": true,
  "maxRecallCount": 5,
  "recallThreshold": 0.3,

  "ai": {
    "provider": "zhipu",
    "model": "glm-4-flash",
    "apiKey": "${ZHIPU_API_KEY}",
    "temperature": 0.2
  },
  "embedding": {
    "provider": "zhipu",
    "model": "embedding-3",
    "apiKey": "${ZHIPU_API_KEY}",
    "dimensions": 1024
  },
  "autoMaterialize": {
    "mode": "assisted",
    "types": ["decision", "project", "bug", "pattern"],
    "autoReferenceInAgents": true
  }
}

海外环境（OpenAI）：

{
  "ai": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "apiKey": "${OPENAI_API_KEY}"
  },
  "embedding": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "apiKey": "${OPENAI_API_KEY}"
  }
}

常见坑点

apiKey 用 "${ENV_VAR}"：插件启动时同步解析，环境变量没设 → undefined → 请求失败并打 error 日志。建议用 direnv / .env / 1Password CLI 管理
开了 semanticAnalysis / autoExtractMemory 但没配 ai 块：AI 调用会失败，相关功能静默失效（不报错也不生效）
改了 dataDir 旧数据不迁移：需要手动复制旧目录下的 memories/ observations/ instincts/ dialogues.lance/ 到新目录
Embedding 模型换了后旧记忆不兼容：新模型的向量维度和旧的可能不同，旧记忆会自动 fallback TF-IDF 检索
LanceDB 对话表维度固定：dialogues.lance 表的 embedding 维度是建表时定的。换 Embedding 模型后，需要删除 ~/.local/share/dsh/long-term-memory/dialogues.lance/ 让插件重建
Monorepo 项目标识冲突：多个子包共用 git remote，会被识别为同一个项目。插件支持自动检测 monorepo 并生成 rootId:leafName 的作用域 ID
JSONC 字段类型写错：插件不会崩溃，会打 error 日志并降级默认值

提供的工具

安装后，插件会注册以下工具供 AI 使用：

工具	用途
`memory_save`	将知识、偏好或决策保存到长期记忆。支持 `scope` 参数指定作用域
`memory_search`	搜索已存储的记忆内容
`memory_list`	列出所有记忆（可按类型过滤）
`memory_delete`	按 ID 删除指定记忆
`memory_restore`	恢复软删除的记忆（30 天内可恢复）
`memory_set_scope`	在 monorepo 中切换子包作用域；独立项目中传入项目名可确认当前项目作用域
`memory_status`	查看系统状态、当前作用域与配置
`memory_open`	打开 MEMORY.md 摘要文件
`memory_demo`	保存测试记忆并验证端到端管道
`memory_analytics`	生成记忆质量报告（命中率、误存候选）
`instinct_list`	查看已学习的行为模式
`memory_analyze`	手动触发行为模式分析
`memory_evolve`	从高置信度模式生成进化规则
`memory_export_rules`	将学习到的规则导出到 `AGENTS.md`（人工审核+确认）
`memory_materialize`	预览项目知识候选清单
`memory_materialize_stage`	暂存候选记忆，返回 id+摘要清单；含内容级重复预检
`memory_materialize_apply`	写入选中的记忆到 `docs/project-context.md`
`memory_materialize_discard`	清空 staging 区

架构设计

┌──────────────────────────────────────────────────────────────┐
│                      宿主适配层                               │
├──────────────────────────────────────────────────────────────┤
│  ┌───────────────────┐    ┌───────────────────────────────┐  │
│  │  DSH (Cordis)     │    │  OpenCode (Hooks)            │  │
│  │  src/dsh/         │    │  src/index.ts                │  │
│  └────────┬──────────┘    └────────┬──────────────────────┘  │
│           │                       │                          │
│           └───────────┬───────────┘                          │
│                       ▼                                      │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                   引擎层 (共享)                        │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────┐   │   │
│  │  │   观测引擎    │─▶│   本能引擎    │─▶│  记忆引擎 │   │   │
│  │  │(observation) │  │  (instinct)  │  │ (memory) │   │   │
│  │  └──────────────┘  └──────────────┘  └──────────┘   │   │
│  │       │                   │                │         │   │
│  │       ▼                   ▼                ▼         │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────┐   │   │
│  │  │observations  │  │  instincts   │  │ memories │   │   │
│  │  │  .jsonl      │  │  .jsonl      │  │  .jsonl  │   │   │
│  │  └──────────────┘  └──────────────┘  └──────────┘   │   │
│  │                                                      │   │
│  │  ┌───────────────────────────────────────────────┐  │   │
│  │  │  dialogue-store.ts  (LanceDB 向量表)          │  │   │
│  │  │  └─ 持久化对话历史                              │  │   │
│  │  └───────────────────────────────────────────────┘  │   │
│  └──────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘

文件结构

src/
├── index.ts               # OpenCode 插件入口（兼容）
├── dsh/
│   ├── index.ts           # DSH Cordis 插件入口（主入口）
│   ├── tools.ts           # 工具注册（DSH DSL）
│   ├── hooks.ts           # 事件桥接
│   └── prompt.ts          # 系统提示注入
├── observation-engine.ts  # 观测引擎：Hook 捕获 + 会话追踪
├── instinct-engine.ts     # 本能引擎：模式提炼（统计 + AI 语义）
├── memory-engine.ts       # 记忆引擎：召回 + 上下文注入
├── memory-store.ts        # 存储层：JSONL + TF-IDF/Embedding + 检索
├── dialogue-store.ts      # LanceDB 向量表：对话历史持久化
├── embedding-provider.ts  # 可插拔 Embedding 层（TF-IDF / Remote / Local）
├── ai-provider.ts         # 声明式 AI/Embedding 配置 → fetch 调用函数
├── config-loader.ts       # 独立配置加载器（JSONC → Zod 校验）
├── project-utils.ts       # 项目标识符推断
├── materializer.ts        # 项目知识沉淀（docs/project-context.md）
├── agents-exporter.ts     # 规则导出到 AGENTS.md
├── analytics.ts           # 埋点与质量报告
└── logger.ts              # 日志系统

Monorepo 作用域

插件会自动检测 git 仓库下的 package.json 数量。若存在多个被 git 追踪的 package.json，则视为 monorepo：

项目 ID 格式：rootId:leafName，例如 acme:acme-web、acme:acme-shared
根作用域：rootId（如 acme）下的记忆可被所有子包召回
子包作用域：rootId:leafName 下的记忆默认只在该子包召回
全局作用域：不绑定 project 的记忆在所有项目召回

显式切换

memory_set_scope name=acme-web

独立（非 monorepo）项目中没有子包概念，作用域始终是项目自身。传入项目名（如 package.json 的 name）即可确认并锁定当前项目作用域：

memory_set_scope name=wallet-h5

`memory_save` 的 `scope` 参数

取值	含义
`current`	写入当前作用域（默认）
`leaf`	写入当前子包作用域（同 `current`）
`root`	强制写入根作用域，所有子包共享
`global`	不绑定 project，全局共享

Embedding 提供者

插件支持三种语义检索后端，默认使用本地 TF-IDF（零依赖）。

提供者	配置方式	适用场景	维度
TF-IDF（默认）	无需配置	零依赖、隐私安全、关键词匹配	词汇维度
远程 API	配置文件 `embedding` 块（推荐）	语义质量最优	模型决定
本地模型	预留接口	未来接入 transformers.js / ollama	模型决定

方式一：配置文件（推荐）

{
  "embedding": {
    "provider": "openai" | "zhipu" | "custom",
    "model": "...",
    "apiKey": "明文key 或 ${ENV_VAR}",
    "baseUrl": "...",          // 可选，custom 必填
    "dimensions": 1024         // 可选，仅 zhipu embedding-3 有效
  }
}

1. OpenAI

{
  "embedding": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "apiKey": "${OPENAI_API_KEY}"
  }
}

2. 智谱 AI（Zhipu）— 中国大陆友好

{
  "embedding": {
    "provider": "zhipu",
    "model": "embedding-3",
    "apiKey": "${ZHIPU_API_KEY}",
    "dimensions": 1024
  }
}

默认端点：https://open.bigmodel.cn/api/paas/v4/embeddings，自动路由。

3. Custom（任何 OpenAI-compatible 端点）

{
  "embedding": {
    "provider": "custom",
    "model": "any-model",
    "apiKey": "${CUSTOM_API_KEY}",
    "baseUrl": "https://my-proxy.example.com/v1"
  }
}

如何选择

场景	推荐
不想折腾，关键词匹配够用	啥都不配（默认 TF-IDF）
国内 + 中文场景	智谱 embedding-3（国内访问稳、价格便宜）
海外 + 追求质量	OpenAI text-embedding-3-small
企业内部代理 / 私有部署	Custom + baseUrl 指向代理

数据存储

所有数据均存储在本地数据目录（默认 ~/.local/share/dsh/long-term-memory/，可通过 dataDir 配置）：

文件/目录	内容
`memories/memories.jsonl`	知识记忆（含可选的 `_embedding` 稠密向量）
`observations/observations.jsonl`	工具调用观测记录
`instincts/instincts.jsonl`	行为模式（本能）
`dialogues.lance/`	LanceDB 向量表：对话历史
`auto-evolved.md`	自动生成的高置信度规则

隐私说明：默认情况下所有数据保存在本地，不需要任何云服务。只有显式配置远程 Embedding API 时才会向外部发送数据。

技术栈

运行时: Bun（构建） / Node.js ≥ 22.19（DSH 加载）
语言: TypeScript 5.8.2（严格模式）
Schema: Zod 4.1.8
向量数据库: LanceDB 0.30.x
宿主框架: Cordis 4.0.1（DSH）/ @opencode-ai/plugin（OpenCode 兼容）

开发

# 安装依赖
pnpm install

# 类型检查
pnpm typecheck       # npx tsc --noEmit

# 构建 DSH 插件（主入口）
pnpm build:dsh       # bun build src/dsh/index.ts --outdir dist-dsh --target node

# 构建 OpenCode 插件（兼容）
pnpm build           # bun build src/index.ts --outdir dist --target bun

# 开发运行
pnpm dev             # bun run src/index.ts

重要：生产构建使用 bun build。tsc 仅用于类型检查（--noEmit），不要用它编译代码。

项目级上下文隔离

记忆系统支持项目级作用域隔离：

自动推断：从当前目录自动推断项目标识
- 优先级：git remote URL → package.json name → 目录名
检索过滤：searchMemories 优先召回同项目记忆（分数 +0.15 提升）
- 全局记忆 +0.05，跨项目 +0
- 同项目不足 topK 时自动 fallback 跨项目 + 全局
配置覆盖：defaultProject?: string 可覆盖自动推断（用于 monorepo 子包）

项目知识沉淀

高价值的项目知识可以通过 memory_materialize_* 工具沉淀到 docs/project-context.md，作为团队共享的可读文档。

三步流程

# 1️⃣ 暂存：列出所有候选
memory_materialize_stage

# 2️⃣ 选你想沉淀的
memory_materialize_apply ids=["mem_xxx", "mem_zzz"]

# 3️⃣ （可选）不想沉淀了？清空 staging
memory_materialize_discard

重复预检（团队协作防护）

memory_materialize_stage 阶段会自动做内容级相似度预检，使用字符级 3-gram + Jaccard 相似度，零外部依赖：

similarity ≥ 0.7 → 🔴 strong match（强烈建议排除）
0.5 ≤ similarity < 0.7 → 🟡 warning match（关注）

隐私保护

docs/project-context.md 通常提交到 git 并团队共享，因此个人类型不允许沉淀：

类型	是否允许沉淀	原因
`decision` `project` `bug` `pattern`	✅ 允许	项目相关知识
`workflow` `tool-usage` `reference`	✅ 允许	项目相关行为/资源
`custom`	✅ 允许	兜底类型
`user` `profile` `feedback`	❌ 禁止	隐私泄露风险

许可

MIT

安装

源码

标签

作者

说明文档