Skip to content
Back to search

dsh-neo4j-memory

A long-term graph memory plugin for DeepSeek Harness (DSH), powered by Neo4j.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shuuno-o--dsh-neo4j-memory/badge.svg)](/listings/shuuno-o--dsh-neo4j-memory)

HTML

<a href="/listings/shuuno-o--dsh-neo4j-memory"><img src="/api/listings/shuuno-o--dsh-neo4j-memory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

桌面版插件页(推荐):

1. 打开 **插件 → 添加插件**。 2. 输入 `dsh-neo4j-memory`,按提示安装。 3. 安装完成后重启 DSH(或按插件页提示重载),在 **设置 → Neo4j 记忆** 配置 Key。

命令行安装(PowerShell;路径按你的实际安装位置调整):

$cli = "D:\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd"
& $cli plugin --profile desktop add dsh-neo4j-memory

也可以直接从 GitHub 安装:

$cli = "D:\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd"
& $cli plugin --profile desktop add github:shuunO-O/dsh-neo4j-memory

`--profile desktop` 是桌面版默认 profile;如果你用的是其他 profile,换成对应名称。

Linux / WSL(`dsh` 在 PATH 中;web 版 profile 通常为 `web`):

dsh plugin --profile web add dsh-neo4j-memory
# 或从 GitHub 安装
dsh plugin --profile web add github:shuunO-O/dsh-neo4j-memory

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 276 lines
  1. # dsh-neo4j-memory
  2. 给 DeepSeek Harness(DSH)用的长期图记忆插件。
  3. 只向模型提供两个工具:
  4. - `memory_database_save(content)`:提取事件、人物、概念、地点和关系,写入 Neo4j。
  5. - `memory_database_search(...)`:摘要与原文两路混合检索(RRF 融合 + MMR 去冗),默认返回 8 个事件的紧凑证据,不附额外候选索引;支持读取原文、沿概念继续检索和补读来源附近记录。
  6. 记忆按“事件 + 实体 + 关系”组织,不是聊天记录切片。只有显式调用保存工具的内容才会被写入;插件不扫描聊天记录。
  7. > 说明:这是一个纯 vibe coding 项目,使用 `GPT6.1-Sol` 与 `deepseek-v4.1-flash-1017` 完成。功能和主要链路在真实环境里跑过;请把它当成一个可读、可改的开源原型,而不是生产级产品。
  8. ## 特性
  9. - 四类节点:`Event`、`Person`、`Concept`、`Location`;四类关系:`PARTICIPATED_IN`、`OCCURRED_AT`、`MENTIONS`、`HAS_ATTITUDE`
  10. - 首次调用自动下载本地 Neo4j 5.26.30 + Temurin JRE 21(约 211 MB;Windows 用 zip,Linux 用 tar.gz),无需系统 Java;也可连外部 Neo4j
  11. - 设置页:三组模型 Key 与端点、概念对齐开关与阈值、向量维度、重新向量化
  12. - 只读图谱页:查看实际写入的节点、关系和属性(导入上限 5,000 节点 / 30,000 关系)
  13. - 写入是一个 Neo4j 事务,失败回滚
  14. - Key、端点、模型、阈值、维度保存后下一次调用生效
  15. - 节点 ID 按类型自增:`event_1`、`person_2`、`concept_3`……
  16. ## 测试结果
  17. 在 [chat-memory-benchmark](https://github.com/Ornn8/chat-memory-benchmark) 六人物正式测试集上,完成 714 道题;抽查修正后暂为 **686 / 714(96.08%)**。其中 26 题经过人工复核,其余使用模型判分,不能视为全量人工复核结果。
  18. 本轮按人物和自然日合并历史入库,使用 1024 维向量;作答时提供最近六轮,由模型自主检索。处理、检索和作答按记录用量估算约 **¥7.35**,不含判分费用。详细配置、题目、实际回答和判分依据见 [公开测试报告](public/chat-memory-benchmark/index.html)及 [JSON 数据](public/chat-memory-benchmark/results.json)。
  19. ## 效果
  20. 以下截图由一段合成对话生成,人物、地点与数值均为虚构。
  21. <img src="docs/images/graph-overview.png" width="1200" alt="记忆图谱总览:事件、人物、概念与地点的关系">
  22. 点击节点查看属性与一跳关系:
  23. <img src="docs/images/graph-node.png" width="1200" alt="节点详情:属性与关联关系">
  24. ## 要求
  25. - Windows 10/11 x64 或 Linux x64(含 WSL2)
  26. - DSH `>=0.2.1-rc.2 <0.3.0`
  27. - Node.js 22+(宿主内置)
  28. - 首次下载运行时需要访问 `dist.neo4j.org` 与 GitHub Release,或通过归档 URL 变量指向镜像
  29. - Linux 托管运行时在插件内解压归档,无需系统 Java 或 `tar`
  30. - 提取与向量 API Key;概念对齐 Key 可选
  31. ## 安装
  32. 桌面版插件页(推荐):
  33. 1. 打开 **插件 → 添加插件**。
  34. 2. 输入 `dsh-neo4j-memory`,按提示安装。
  35. 3. 安装完成后重启 DSH(或按插件页提示重载),在 **设置 → Neo4j 记忆** 配置 Key。
  36. 命令行安装(PowerShell;路径按你的实际安装位置调整):
  37. ```powershell
  38. $cli = "D:\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd"
  39. & $cli plugin --profile desktop add dsh-neo4j-memory
  40. ```
  41. 也可以直接从 GitHub 安装:
  42. ```powershell
  43. $cli = "D:\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd"
  44. & $cli plugin --profile desktop add github:shuunO-O/dsh-neo4j-memory
  45. ```
  46. `--profile desktop` 是桌面版默认 profile;如果你用的是其他 profile,换成对应名称。
  47. Linux / WSL(`dsh` 在 PATH 中;web 版 profile 通常为 `web`):
  48. ```bash
  49. dsh plugin --profile web add dsh-neo4j-memory
  50. # 或从 GitHub 安装
  51. dsh plugin --profile web add github:shuunO-O/dsh-neo4j-memory
  52. ```
  53. ## 配置
  54. 安装并启用后打开 **设置 → Neo4j 记忆**:
  55. - **API Key**(默认折叠):提取、向量、概念对齐三组
  56. - **模型端点与阈值**(默认折叠):三组 Base URL 与模型名、概念对齐阈值(80%–99%)
  57. - **向量维度**:默认 1024,必须与向量模型实际输出一致;修改后点「重新向量化」
  58. - **数据库**:本地/外部模式、外部 Neo4j 密码、本地数据目录
  59. | 用途 | 默认服务 / 模型 |
  60. |---|---|
  61. | 提取 | DeepSeek / `deepseek-flash` |
  62. | 向量 | DashScope / `qwen3.7-text-embedding`,1024 维 |
  63. | 概念对齐 | TypeSafe / `jev`,阈值 0.95 |
  64. 概念对齐填的是**完整 endpoint**:TypeSafe 为 `https://api.typesafe.ai/v1/systemone`,OpenRouter 为 `https://openrouter.ai/api/alpha/decisions`。用 OpenRouter 时模型可填 `typesafe/jev-1.14`;换模型后建议重新校准阈值。
  65. 保存后,Key、端点、模型、阈值、维度在下一次调用时生效;本地数据目录、Neo4j 模式、外部密码需要重启 DSH。
  66. 设置页通过 **DSH Credentials 服务**保存 API Key 和外部 Neo4j 密码,不再把新密钥写进 `cordis.patch.yml`。每次调用按以下顺序读取:**非空进程环境变量 → 插件独立的 DSH 凭据 → 旧插件配置(兼容)**。其余字段仍是插件配置优先。
  67. | 用途 | 优先使用的环境变量 | 插件的 DSH 凭据引用(也可用作环境变量) |
  68. |---|---|---|
  69. | 提取模型 | `DEEPSEEK_API_KEY` | `DSH_NEO4J_MEMORY_EXTRACTION_API_KEY` |
  70. | 向量模型 | `EMBEDDING_API_KEY` | `DSH_NEO4J_MEMORY_EMBEDDING_API_KEY` |
  71. | 概念对齐 | `TYPESAFE_API_KEY` | `DSH_NEO4J_MEMORY_ALIGNMENT_API_KEY` |
  72. | 外部 Neo4j | `NEO4J_PASSWORD` | `DSH_NEO4J_MEMORY_NEO4J_PASSWORD` |
  73. 两列环境变量同时存在时,左列优先;空白值视为未设置。插件使用独立的凭据引用,不覆盖 DSH 主模型的 Key;这些凭据由同一 DSH home 下的各 profile 共享。设置页只显示是否配置及当前是否使用环境变量,不回显值;「清除」删除已保存凭据和旧配置值,不修改环境变量。
  74. 打开设置页或首次调用工具时,会尝试把旧配置 Key 迁移到 DSH:先写入、读回确认,再清除旧配置。写入或清理失败保留旧配置供重试;已有不同的 DSH 凭据时不覆盖,也不静默丢弃旧 Key,设置页会提示尚未完成迁移,可重新保存或清除对应项。环境变量的值不会被迁移或自动持久化。
  75. ### 向量维度与重新向量化
  76. 不同模型或不同维度的向量不能比较,Neo4j 的向量索引也固定维度。插件把当前模型与维度记录在 `MemoryMeta` 节点里;配置变化后,保存和语义搜索会被拒绝,直到重新向量化。
  77. 设置页「向量索引」区域会显示当前库的模型、维度、节点数,并提供「重新向量化」按钮。操作会重算所有记忆节点的向量、重建四个向量索引;新向量先暂存,全部计算成功后才替换旧向量并更新元数据。
  78. ### 本地 Neo4j
  79. 默认 `DSH_NEO4J_MEMORY_NEO4J_MODE=auto`:没有配置外部 URI/密码时使用本地实例,首次调用工具时下载并启动。数据、日志、`state.json` 位于 Windows 的 `%LOCALAPPDATA%\dsh-neo4j-memory\`,Linux 为 `~/.local/share/dsh-neo4j-memory/`(可用 `XDG_DATA_HOME` 覆盖),可在设置页改到其他可写目录(需重启)。
  80. 本地数据目录还需要支持 Neo4j 的文件重命名和原子写入。部分 Windows 目录可能无法完成这些操作,即使文件都在同一目录下,也可能出现 `EXDEV` 或 `AtomicMoveNotSupportedException`。如果首次启动遇到这类错误,可以在 **设置 → Neo4j 记忆 → 数据库 → 本地数据目录**中指定其他可写目录(推荐),例如 `D:\dsh-neo4j-memory-data`,保存后重启 DSH。目录不一定要在 D 盘,也不需要移动 DSH 或插件;选择时请注意目录的访问权限和加密设置。
  81. 更改目录不会自动迁移原有记忆数据库:新目录会作为新的本地数据库使用,原目录的数据仍留在原处。
  82. 同一时间只建议运行一个使用托管模式的 DSH 实例。想让本地实例在 DSH 退出后继续运行,设置 `DSH_NEO4J_MEMORY_NEO4J_KEEP_RUNNING=1`。
  83. #### Linux 与 WSL
  84. Linux 首次调用会下载 `neo4j-community-5.26.30-unix.tar.gz` 与 Temurin 21 Linux JRE,并在插件内解压。归档中指向同一发行版内普通文件的符号链接会复制为普通文件;越界链接、目录链接、链接链、硬链接与特殊文件仍会被拒绝。默认数据目录在用户主目录下,一般无需额外权限。
  85. WSL 中请把数据目录放在 ext4 文件系统(如 `~/.local/share` 或项目目录),不要放在 `/mnt/c` 等 DrvFs 挂载点:跨文件系统的重命名会报 `EXDEV`,部分目录也无法完成原子写入。内存较小的 WSL 实例可减少同时运行的服务,或改用外部 Neo4j。
  86. Neo4j 5.26 启动时会按空白拆分自己的启动命令,数据目录以及插件所在路径都不要包含空格或制表符,否则密码初始化或启动会失败;可用 `DSH_NEO4J_MEMORY_RUNTIME_DIR` 指向不含空格的目录,或改用外部 Neo4j。
  87. 无法访问官方下载源时,可用 `DSH_NEO4J_MEMORY_NEO4J_ARCHIVE_URL` / `_SHA256` 与 `DSH_NEO4J_MEMORY_JRE_ARCHIVE_URL` / `_SHA256` 指向镜像归档;也可以用系统 Java 加外部 Neo4j,跳过托管下载。
  88. 排障日志:
  89. - Windows:`%LOCALAPPDATA%\dsh-neo4j-memory\provision.log`、`...\logs\console.log`
  90. - Linux:`~/.local/share/dsh-neo4j-memory/provision.log`、`.../logs/console.log`
  91. 如果设置了其他本地数据目录,请在该目录下查找相同的日志文件。
  92. Neo4j Community 采用 GPLv3,Temurin JRE 采用 GPLv2+CE;插件不随包分发这些二进制,首次运行时从官方地址下载(下载失败可考虑设置代理,或用归档 URL 变量改用镜像)。
  93. ## 环境变量(可选)
  94. 密钥类字段**非空进程环境变量优先于 DSH 凭据,再回退旧插件配置**,具体名称见上表。其余字段仍是插件配置优先。
  95. | 变量 | 默认值 |
  96. |---|---|
  97. | `DSH_NEO4J_MEMORY_NEO4J_MODE` | `auto`(`auto` / `managed` / `external`) |
  98. | `DSH_NEO4J_MEMORY_NEO4J_URI` | `bolt://localhost:7687`(external) |
  99. | `NEO4J_PASSWORD` | 无;external 必填 |
  100. | `DSH_NEO4J_MEMORY_RUNTIME_DIR` | Windows 为 `%LOCALAPPDATA%\dsh-neo4j-memory`,Linux 为 `$XDG_DATA_HOME` 或 `~/.local/share/dsh-neo4j-memory` |
  101. | `DSH_NEO4J_MEMORY_JAVA` | 无;Java 17+ 可执行文件,未下载 JRE 时使用 |
  102. | `DSH_NEO4J_MEMORY_NEO4J_ARCHIVE_URL` / `_SHA256` | 官方 Neo4j 归档地址与校验和;用于镜像或离线安装 |
  103. | `DSH_NEO4J_MEMORY_JRE_ARCHIVE_URL` / `_SHA256` | 官方 Temurin 归档地址与校验和;用于镜像或离线安装 |
  104. | `DSH_NEO4J_MEMORY_EXTRACTION_URL` / `_MODEL` | `https://api.deepseek.com` / `deepseek-flash` |
  105. | `DSH_NEO4J_MEMORY_EMBEDDING_URL` / `_MODEL` | DashScope compatible / `qwen3.7-text-embedding` |
  106. | `DSH_NEO4J_MEMORY_EMBEDDING_DIMENSIONS` | `1024` |
  107. | `DSH_NEO4J_MEMORY_ALIGNMENT_URL` / `_MODEL` | `https://api.typesafe.ai/v1/systemone` / `jev` |
  108. | `DSH_NEO4J_MEMORY_ALIGNMENT_THRESHOLD` | `0.95`(0.80–0.99) |
  109. | `DSH_NEO4J_MEMORY_CONCEPT_ALIGNMENT` | `true`;设为 `0`/`false` 关闭 |
  110. | `DSH_NEO4J_MEMORY_TIMEZONE` | `Asia/Shanghai` |
  111. 外部 Neo4j 需支持向量索引与 `vector.similarity.cosine`(如 Neo4j 5.23+)。
  112. ## 工作方式
  113. ```text
  114. 保存:content
  115. → 提取事件/实体/关系
  116. → 生成事件摘要与实体名向量
  117. → 概念对齐(可选)
  118. → 一个 Neo4j 事务写入
  119. 检索:query / entity / date
  120. → 摘要与原文两路向量候选(各 40)
  121. → RRF 融合 + MMR 去冗
  122. → 原摘要 + 短原文 + 共享 Concept + 继续入口
  123. → 主 Agent 按需读取原文、沿 Concept 追查、补读来源记录
  124. ```
  125. 图谱页:**设置 → Neo4j 记忆 → 展开图谱**,或访问 `/dsh-neo4j-memory/graph/`。只读,不写回 Neo4j;导出 JSON 只影响浏览器视图。
  126. ### 可撤销的概念合并
  127. 语义对齐采用等价组:不同叫法保留各自的 Concept,Event 始终连接原来的 Concept。对齐召回先按组去重,模型结合整组成员的名称、上下文和事件摘要判断新概念是否入组。多个不同组都被判为相同或证据不足时,不自动合并。Event 的实体筛选、共享概念统计与 `expand` 均按组处理,组内事件去重。
  128. 确定的书写变体仍复用同一节点:去首尾空白、全角 ASCII 转半角、Unicode NFC;仅 `Neo4j / TypeScript / JavaScript / PostgreSQL / MySQL / Docker` 忽略大小写。保留标点及其他名称的大小写,不把 `US/us`、`C/C++` 或 `①/1` 自动合并。启用语义对齐时,其他同名概念仍结合上下文消歧。
  129. 组成员存于 `Concept.equivalence_group`,缺失时以自身 ID 作为单独一组。维护接口 `backend.call('memory_database_concept_detach', { concept_id: 'concept_12' })` 将该节点移到新的单独组,不调用模型、不修改 Event 关系,并清除当前服务的追查游标。图谱仍为只读页面,可在节点属性中检查组 ID;本次未增加界面上的撤销按钮。
  130. 旧库不改动 Event 关系,也不拆解历史 `aliases`;启动索引初始化时只补名称比较键。过去已经硬合并的别名无法凭现有信息恢复原来的 Event 归属,新的语义合并才具有上述可撤销性。
  131. ### 检索算法
  132. 一次 `search`(`target_label=Event`)分五步,全部在本地完成,不额外调用模型:
  133. 1. **两路候选**:问题向量分别检索事件摘要与原文分块,各取前 40,合并后最多 80 个不同候选;候选先按实体、写入日期和已交付 ID 过滤。
  134. 2. **融合重排**:两路名次用 RRF 融合(`k = 60`),再加查询词项覆盖 `0.10`。
  135. 3. **控制冗余**:完整原文相同的事件只保留一个代表;MMR 在相关性与已选证据的相似度之间折中(`λ = 0.75`,冗余取向量余弦与来源分块重叠的较大值)。
  136. 4. **分层交付**:前 8 个事件给摘要 + 最多 120 字符的原文摘录(整包预算 1,000 字符),默认不交付额外候选索引;追查链剩余额度不足时按余额交付,失败的调用不占用名额。
  137. 5. **按需核对**:模型再用 `read` / `nearby` / `expand` 补读原文、同章邻近记录或经共享 Concept 扩展。
  138. 接口与升级细节见[检索接口](docs/retrieval.md),混合检索与纯向量检索的逐题对照见 [public/dawn-retrieval-study](public/dawn-retrieval-study/README.md)。
  139. ### 检索和继续追查
  140. 首次调用方式不变,例如 `{"query_text":"Neo4j 的部署方式和方案演进"}`。默认 `target_label=Event`,每次返回 8 个事件的摘要与原文摘录(每个事件最多 120 个字符,全包预算 1,000 字符),并提供每条事件的 `read event_id=<id> limit=<原文长度>`;可用 `chapter`(如“第81章”传 81)把检索硬限定到某一章,完整来源按需读取。模型看到紧凑结构化文字。
  141. | operation | 参数 | 用途 |
  142. |---|---|---|
  143. | `search`(默认) | `query_text` / `entity_filter` / `time_hint` / `chapter` / `source_session` 至少一项 | 返回最多 8 个事件的摘要、原文摘录和追查入口 |
  144. | `read` | `event_id`,可选 `start` / `limit` | 按范围读取事件的 content;无需模型 Key |
  145. | `expand` | `cursor` / `concept_id`,可选 `limit` | 经返回的 Concept 补取事件,默认 3 个;只返回新增内容 |
  146. | `nearby` | `cursor` / `event_id`,可选 `before` / `after` | 有章号和导出记录号时,补读同章相邻编号;只返回新增内容 |
  147. 按来源会话查询可传 `{"source_session":"conversation-123","query_text":"部署进展"}`,精确匹配 `Event.raw_session`;也可只传 `source_session`,无需模型 Key。它可与章节、实体、日期条件组合,`expand` / `nearby` 自动沿用这个范围。该参数与内部管理当前调用会话的 `session_id` 分开,来源会话 ID 可从事件的 `session` 字段获得;没有来源会话时省略该字段。
  148. cursor 绑定当前会话,15 分钟内有效,重启后需重新检索;每条追查链累计最多 20 个事件。
  149. `Person` / `Concept` 的定向实体检索继续使用原来的前三条和一跳上下文。详细返回格式、边界和升级兼容说明见 [检索接口](docs/retrieval.md)。
  150. ## 当前限制
  151. - 提取与合并较粗:仅单次抽取;概念按名称/别名 + 向量 + 两两判同,不保证一定准确。
  152. - 初始事件召回依赖摘要与原文分块向量;旧记忆没有原文分块时只能靠摘要命中。沿概念扩展不能补回数据库里缺失的关系,也不保证关键事实完整。
  153. - 图谱只读:没有删除、合并、编辑节点/关系的 UI。
  154. - 测试覆盖范围有限:六人物成绩包含模型判分,仍可能存在误判;[小说检索对照](public/dawn-retrieval-study/README.md)只覆盖《黎明之剑》前 500 章、18 道开发题与 6 道新题。插件在 Windows x64 与 WSL2 Ubuntu x64 上完成测试,其他 Linux 发行版未逐一验证。
  155. ## 开发
  156. ```bash
  157. npm ci --legacy-peer-deps
  158. npm run build
  159. node selfcheck.mjs
  160. node tests/backend.test.mjs
  161. npm pack
  162. ```
  163. Windows PowerShell 下命令相同。
  164. - `src/` 是 TypeScript 源码,`lib/` 是编译产物,`assets/` 是提取提示词,`web/graph/` 是图谱页面。
  165. - `npm test` 使用 `node --test`;`DSH_NEO4J_MEMORY_INTEGRATION=1 node tests/integration.test.mjs` 可跑真实 Neo4j 集成测试(首次会下载托管运行时)。
  166. - 无法访问官方下载源时,用已解压的发行版与系统 Java 离线跑集成测试:
  167. ```bash
  168. DSH_NEO4J_MEMORY_TEST_NEO4J_HOME=/path/to/neo4j \
  169. DSH_NEO4J_MEMORY_TEST_JAVA=/path/to/java \
  170. DSH_NEO4J_MEMORY_INTEGRATION=1 node tests/integration.test.mjs
  171. ```
  172. - Linux 托管运行时的下载、校验、解压、守护与持久化由单独用例覆盖:
  173. ```bash
  174. DSH_NEO4J_MEMORY_TEST_NEO4J_ARCHIVE=/path/to/neo4j-community-5.26.30-unix.tar.gz \
  175. DSH_NEO4J_MEMORY_TEST_JRE_ARCHIVE=/path/to/OpenJDK21U-jre_x64_linux_hotspot_21.0.12.1_1.tar.gz \
  176. node tests/linux-runtime.test.mjs
  177. ```
  178. - `npm publish` 会先执行 `prepublishOnly`:构建 + selfcheck + 后端测试;`npm pack` 会先构建。
  179. ## 隐私
  180. - 记忆库在本机,但提取/向量/对齐会把内容发给你配置的模型 API。
  181. - API Key 与外部 Neo4j 密码由 DSH 凭据服务管理;插件不把密钥返回设置页、写进对话或存入记忆库。旧插件配置会在确认迁移后清除;若旧值来自自定义 bundle 等继承层,迁移只在当前 profile 屏蔽该值,原始继承文件需自行清理。本地托管 Neo4j 自动生成的密码仍在数据目录的 `state.json`。
  182. - 不要把密码、密钥或不想发给模型服务的内容存进记忆库。
  183. ## 许可证
  184. MIT,见 [LICENSE](LICENSE)。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.