前言¶
在 DeepSeek Harness（DSH）里跑智能体时，常见做法是依赖会话上下文或把聊天记录切成片段做检索。这类方式能应付短对话，但人物、事件、地点和概念之间的关系很难稳定保留，跨会话也容易丢细节。下面介绍社区插件 dsh-neo4j-memory：它把显式保存的内容整理成「事件 + 实体 + 关系」写入 Neo4j，并提供语义与实体维度的召回，适合需要本机长期图记忆、又愿意自己配置提取与向量 API 的 Windows 桌面用户。
这是什么¶
dsh-neo4j-memory 由 shuunO-O 维护，分类为「记忆」，当前 npm 版本 0.6.0，许可证 MIT。简介为：A long-term graph memory plugin for DeepSeek Harness (DSH), powered by Neo4j.
插件只向模型暴露两个工具，不扫描聊天记录；只有模型显式调用保存工具时才会写入记忆库。
| 工具 | 作用 |
|---|---|
memory_database_save(content) |
从文本提取事件、人物、概念、地点及关系，写入 Neo4j |
memory_database_search(query_text?, target_label?, entity_filter?, time_hint?) |
按语义、实体或日期召回，返回主匹配及一跳关系 |
README 说明：这是一个可读、可改的开源原型，主要链路在真实环境跑过，并非生产级产品；仅在 Windows 10/11 x64 上测试，DSH 要求 >=0.2.1-rc.2 <0.3.0，Node.js 22+（桌面宿主内置）。
核心功能¶
图模型¶
记忆按图组织，而非聊天切片：
- 四类节点：
Event、Person、Concept、Location - 四类关系：
PARTICIPATED_IN、OCCURRED_AT、MENTIONS、HAS_ATTITUDE - 节点 ID 按类型自增，例如
event_1、person_2、concept_3
本地 Neo4j 与外部库¶
首次调用相关工具时，可在 auto / managed 模式下自动下载 Neo4j 5.26.30 与 Temurin JRE 21（约 211 MB），无需系统已装 Java；也可连接支持向量索引的外部 Neo4j（需 Neo4j 5.23+ 及 vector.similarity.cosine）。
默认数据与日志目录为 %LOCALAPPDATA%\dsh-neo4j-memory\，可在设置页修改（改目录需重启 DSH）。
设置页与图谱页¶
安装后在 设置 → Neo4j 记忆 可配置：
- 提取、向量、概念对齐三组 API Key 与 Base URL / 模型名
- 概念对齐开关与阈值（80%–99%）、向量维度（默认 1024，须与向量模型输出一致）
- 本地 / 外部 Neo4j 模式、外部密码、本地数据目录
- 「重新向量化」：模型或维度变更后须执行，否则保存与语义搜索会被拒绝
默认模型参考（可在设置或环境变量中覆盖）：
| 用途 | 默认服务 / 模型 |
|---|---|
| 提取 | DeepSeek / deepseek-flash |
| 向量 | DashScope / qwen3.7-text-embedding，1024 维 |
| 概念对齐 | TypeSafe / jev，阈值 0.95 |
只读图谱：设置 → Neo4j 记忆 → 展开图谱，或访问 /dsh-neo4j-memory/graph/，可查看已写入的节点与关系；无删除、合并、编辑 UI。
写入与检索链路¶
保存与检索的大致流程如下（与 README 一致）：
保存：content
→ 提取事件/实体/关系
→ 生成事件摘要与实体名向量
→ 概念对齐（可选）
→ 一个 Neo4j 事务写入
检索：query / entity / date
→ 向量 top-3，或按实体/日期过滤
→ 取最相关节点的一跳邻居
→ 返回主匹配 + 次要匹配 + 上下文
写入失败时整笔事务回滚。配置中的 Key、端点、模型、阈值、维度在保存后于下一次工具调用生效；本地数据目录、Neo4j 模式、外部密码变更需重启 DSH。
安装与启用¶
DSH 生态采用「一切皆插件」；社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。安装前建议浏览 GitHub 仓库 源码与 MIT 许可证；插件以当前 DSH 进程权限运行，请勿把密钥或不愿发给模型服务的内容写入记忆。
桌面版插件页（推荐）：
- 打开 插件 → 添加插件。
- 输入
dsh-neo4j-memory，按提示安装。 - 安装完成后重启 DSH（或按插件页提示重载），在 设置 → Neo4j 记忆 配置 Key。
命令行（PowerShell；CLI 路径按实际安装位置调整）：
$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，请替换为对应名称。
典型用法¶
在对话中由模型按需调用工具即可，无需额外脚本。典型模式如下：
- 写入：用户说明希望记住的事实或经历后，模型调用
memory_database_save(content)，传入自然语言内容；插件抽取图结构并写入 Neo4j。 - 召回：后续会话中，模型调用
memory_database_search，可传query_text做语义检索，或用entity_filter、time_hint、target_label缩小范围；返回主匹配节点及其一跳关系，供模型组织回答。 - 核对：在图谱页查看实际落库的节点与边，确认提取是否符合预期。
README 未提供固定 prompt 模板；行为依赖模型是否、何时调用上述工具。提取与合并为单次抽取，概念对齐为可选；检索为向量 top-3 加一跳，在几十条记忆规模上验证过，无公开 benchmark。
适用场景与注意¶
适合：
- 已在 Windows 上使用 DSH 桌面版，需要跨会话保留结构化记忆（谁、何时、何地、涉及哪些概念）。
- 愿意配置 DeepSeek（或自定义）提取 API、DashScope 兼容向量 API，以及可选的概念对齐 endpoint。
- 接受本机 Neo4j 托管或自备外部 Neo4j，并理解记忆库在本机、但提取/向量/对齐请求会发往所配置的模型 API。
务必留意：
- 平台限制：
package.json声明仅 win32 / x64；其他系统未在资料中声明支持。 - 隐私：API Key 保存在当前 DSH profile 配置中，不回显、不进入对话；记忆内容经第三方 API 做抽取与向量化，勿存入密码或敏感密钥。
- 限制：图谱只读；同一时间建议只运行一个使用托管本地 Neo4j 的 DSH 实例；向量维度变更后必须「重新向量化」。
- 可选环境变量（插件设置优先于环境变量）包括
DSH_NEO4J_MEMORY_NEO4J_MODE、DEEPSEEK_API_KEY/EMBEDDING_API_KEY/TYPESAFE_API_KEY等，完整列表见仓库 README。
排障时可查看 %LOCALAPPDATA%\dsh-neo4j-memory\provision.log 与 logs\console.log。若希望 DSH 退出后本地 Neo4j 仍运行，可设置 DSH_NEO4J_MEMORY_NEO4J_KEEP_RUNNING=1。
结尾¶
dsh-neo4j-memory 把 DSH 智能体的长期记忆落到 Neo4j 图模型上：显式保存、结构化抽取、语义与实体召回，并附带设置页与只读图谱。适合在 Windows 桌面 Harness 里做可读的图记忆原型与二次开发。
