安装 Neo4j 与配置科学记忆

科学记忆（ScienceMemory）是 ScienceDiscovery 的可选功能，把一个会话的研究目标、每一步任务、运行的代码、产出的文件，到最终报告里每条带引用的断言及其证据，存成一张图谱，让"这个结论是怎么来的"可被点击回溯。源码、Docker 与单文件新安装均自动启动 memory-graph 服务，本地文件后端无需 Neo4j。单文件包内置服务及 Python 依赖；如果该可选服务启动失败，启动器报告原因并在关闭科学记忆的情况下继续启动。

单文件发行包

照常运行 ScienceDiscovery serve 即可。图谱保存在 <数据目录>/memory-graph/，不在解包缓存内，升级程序时保留。该服务无需额外安装系统 Python 或 Neo4j。已在系统设置中关闭记忆的用户需要自行开启，启动器不会覆盖已有设置。

设置 SCIENCE_AGENT_MEMORY_GRAPH_AVAILABLE=0 可跳过服务启动。
多实例使用 SCIENCE_AGENT_MEMORY_GRAPH_PORT（默认 17674）区分端口；已有图谱可用 SCIENCE_AGENT_MEMORY_GRAPH_DATA_DIR 指向原目录，不自动迁移数据。
内置服务仅监听 127.0.0.1。启动器自动生成与 API 共享的内部令牌，不是浏览器登录令牌。
连接自行部署的服务时，设置 SCIENCE_AGENT_MEMORY_GRAPH_URL 和匹配的 SCIENCE_AGENT_MEMORY_GRAPH_INTERNAL_TOKEN；启动器不会启动或停止外部服务。
服务失败后，修正原因并重启。使用不含该服务的旧 payload 时仍默认不可用，除非配置外部服务地址。

本文讲内置的本地文件存储、怎么装 Neo4j 并在系统设置里配置、怎么在前端用。功能本身的架构、节点/边类型、API 接口见科学记忆说明；环境变量与端口见配置参考。

0. 零配置：本地文件存储

科学记忆不需要任何外部服务。默认（“系统配置 → 记忆 → 存储后端”选“本地文件”）图谱由 memory-graph 侧车自己维护，并以纯文本落盘到 ~/.science-agent/memory-graph/（可用 SCIENCE_AGENT_MEMORY_GRAPH_DATA_DIR 修改）：

nodes.jsonl：每个节点一行 JSON（id、labels、props）；删除的节点是一行 {"id": ..., "deleted": true}。
edges.jsonl：每条关系一行 JSON（id、type、src、dst、props）。

回放按 id 取最后一次写入，所以文件只追加，写到一半崩溃也不丢数据（损坏的末行会被跳过），加载时还会压缩。可以直接 grep、jq、diff，也方便附在问题报告里。所有会话共用一个存储，每个节点都带 session_id。/health 返回 {"status": "healthy", "backend": "local"}。

后端是一项设置：在“存储后端”里选“Neo4j 服务”，才会出现 Neo4j HTTP 地址、用户名、密码等字段（见第 2 节）。只保存凭据不会切换存储；选了 Neo4j 但连不上时保持 degraded，不会悄悄回退，两边的历史不会分叉。SCIENCE_AGENT_MEMORY_GRAPH_BACKEND（local 或 neo4j）只决定侧车在 API 首次推送之前的取值。

本地存储适合单用户、每个会话几千个节点以内的图。更大或多人共享的部署，或想用 Neo4j Browser 时，请选 Neo4j。要把本地历史迁到 Neo4j（单向、可重复执行）：

NEO4J_PASSWORD=yourpassword python -m sciencediscovery_memory_graph.export_to_neo4j \
  --http http://127.0.0.1:7474 --user neo4j

下面各节只有在你想用 Neo4j 时才需要。

1. 可选：安装 Neo4j

需要的是：

一个 Neo4j 5.x 服务（Community 版即可）；
它的 HTTP 端口 7474 可被 ScienceDiscovery 进程访问（默认都在同一台机器、走回环）；
用户名（默认 neo4j）和密码。

注意：连接走的是 Neo4j 的 HTTP 端口（7474），不是 Bolt 端口（7687）。Bolt 端口不用配。Neo4j 装好后会在 7474 提供 HTTP、7687 提供 Bolt，科学记忆只用前者。

1.1 方式 A：用 Docker（推荐，最简）

这是 UI 里也提示的快速启动方式。在装好 Docker 的机器上：

docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/你的密码 \
  -v neo4j-data:/data \
  neo4j:5

-e NEO4J_AUTH=neo4j/你的密码：首次启动设置初始用户名（固定 neo4j）与密码。把"你的密码"换成你自己的强密码，这个密码稍后要填进 ScienceDiscovery 的系统设置。
-p 7474:7474：暴露 HTTP 端口，科学记忆用这个端口连。
-v neo4j-data:/data：用 Docker 命名卷持久化图数据，删容器不丢数据。

启动后等几十秒，访问 http://127.0.0.1:7474 能打开 Neo4j Browser 登录页即说明 Neo4j 已就绪（用 neo4j / 你设的密码登录验证）。

如果要随 ScienceDiscovery 一起拉起、一起停，把上面的 Neo4j 容器加进你自己的 Compose 文件即可，但不要改 ScienceDiscovery 自带的 docker-compose.yml，那个文件只负责 ScienceDiscovery 自己。

1.2 方式 B：Linux 原生安装（不想用 Docker 时）

以 Debian/Ubuntu 为例，安装 Neo4j 官方仓库后用 apt 安装：

# 导入 Neo4j 官方签名 key 与仓库
sudo install -d /etc/apt/keyrings && \
wget -qO- https://keyserver.ubuntu.com/4046BCA5E2F9A889B1A6FDB0E8E8F9A1B5A3C9F5 | \
  sudo gpg --dearmor -o /etc/apt/keyrings/neo4j.gpg
echo "deb [signed-by=/etc/apt/keyrings/neo4j.gpg] https://deb.neo4j.com stable latest" | \
  sudo tee /etc/apt/sources.list.d/neo4j.list
sudo apt-get update && sudo apt-get install -y neo4j

上面的 key 指纹与仓库地址以 Neo4j 官方安装文档为准，不同发行版步骤不同，请按官方文档对号入座。RHEL/openEuler 用 dnf，Alpine 用 apk。

安装后设初始密码并启动：

sudo neo4j-admin dbms set-initial-password 你的密码   # 首次设置
sudo systemctl enable --now neo4j                       # 开机自启 + 立即启动

启动后同样访问 http://127.0.0.1:7474 验证。如果需要远程访问或改端口，编辑 /etc/neo4j/neo4j.conf 后 sudo systemctl restart neo4j，但本地部署默认回环配置即可，不用改。

1.3 验证 Neo4j 就绪

不管哪种安装方式，确保这两点成立：

curl -s http://127.0.0.1:7474 返回 JSON（含 neo4j_version）；
能用 neo4j / 你设的密码登录 http://127.0.0.1:7474。

Neo4j 不必与 ScienceDiscovery 同时启动，但科学记忆要写图或读图时它必须在线。Neo4j 临时不可达时科学记忆会静默降级，不报错、不阻断对话。

2. 在系统设置里配置科学记忆

Neo4j 跑起来后（并把“存储后端”设为“Neo4j 服务”），配置全部在系统设置 → 记忆（Memory）里完成，不用改 .env、不用重启 stack。

2.1 打开设置

打开 ScienceDiscovery Web UI（默认 http://127.0.0.1:4310）并登录。
点左侧栏底部的系统配置（System configuration）按钮，打开系统设置对话框。
左侧分组列表里选记忆（Memory）。

2.2 填写四项

记忆设置区有这些字段：

字段	填什么	默认占位
启用科学记忆（开关）	关闭后不再记录	开（新安装；Docker 中为关）
存储后端	本地文件（默认）或 Neo4j 服务；只有选 Neo4j 时才显示下面三项	本地文件
Neo4j HTTP	Neo4j 的 HTTP 地址	`http://127.0.0.1:7474`
Neo4j 用户	Neo4j 用户名	`neo4j`
Neo4j 密码	你在 1.1/1.2 里设的密码	—

要点：

只填 HTTP 地址、用户、密码，没有 Bolt 地址、端口或数据库名字段。本地部署前三项都用默认占位即可，密码填你设的那个。
密码只写不回。后端用 AES-256-GCM 加密存进数据目录，浏览器永远拿不到原文。已存密码时，密码框会提示"已设置 · 输入新密码以替换"，旁边有"移除已存密码"按钮。
顶部有一句依赖说明，带一个 Neo4j 安装指南链接，可直接跳转官方文档。
如果 Neo4j 还没起或连不上，设置区底部会出现一条降级提示，含 docker run 快速启动命令，照着跑即可。

2.3 保存

点底部保存（或"保存并关闭"）。保存时后端会把 HTTP 地址、用户名、密码经回环、Bearer 保护的内部端点推给记忆图侧车（sidecar），侧车立刻用它连 Neo4j。保存成功会弹出"科学记忆设置已更新"提示。

2.4 确认连上了

回到会话工作区，展开右侧“记忆 → 科学记忆”，缩略卡的健康状态会显示当前连接情况。未启用时该入口隐藏；启用后连接异常仍显示状态提示。状态取自 /health，取值：

状态	含义	处理
`healthy`	Neo4j 可达、密码已配	正常，可读写图
`needs-password`	后端选了 Neo4j，但侧车还没收到密码	把密码填上并保存，或把“存储后端”改回“本地文件”
`degraded`	配了密码但 Neo4j 连不上	检查 Neo4j 是否在跑、7474 端口是否通、地址/密码是否对
`disabled`	功能开关关着	打开开关

暂停（关开关）不删已有图数据，重新打开即恢复视图。

3. 在前端使用科学记忆

配置为 healthy 且开了开关后，会话执行过程中会自动把任务链、产物、引用链写进图。前端只读，所有读请求经控制 API 反向代理到侧车，浏览器不直连 7474 或 17674。

3.1 打开图谱

有两种入口：

会话工作区缩略卡：启用后在右侧“记忆”分区中展开“科学记忆”，查看节点/边数量与任务完成情况，再点缩略卡打开本次会话的图谱全屏视图。一级分区默认展开，科学记忆二级详情默认收起。
从具体产物进入（看链路的推荐入口）：打开某个产物预览，点「在科学记忆中查看此产物」，会直接打开图谱并定位到该产物的链路视图。

3.2 默认视图：研究主线

刚打开时，图谱默认只显示研究主线：研究目标 → 子任务 → 工具调用，按执行先后排成一条线。每个任务产出的代码、论文、产物，以及引用链里的证据、观点节点，默认折叠不显示，避免一上来糊成一团。

3.3 双击展开 / 折叠

双击任务节点（子代理作用域）展开它内部含有的工具调用链。
双击其他节点（工具调用、代码、论文、证据、观点、产物）展开它直接产出的下一层，一次一层。再双击则折叠，会连带收起因此变成孤儿的下游节点。
鼠标悬停节点会有"双击展开 / 双击收起"提示。节点右上角的 +N 表示它后面还折叠着 N 个节点，展开后变成 −N。
画布右上角的「展开全部」一次展开所有折叠的节点，「折叠全部」回到研究主线。头部的“可见 / 总数”会随之变化。

3.4 链路按钮（按节点类型）

选中一个节点后，节点旁或顶部会出现该节点类型专属的链路按钮。点一个按钮，就高亮该节点到相关节点的那条链路，其余节点雾化淡出。不同类型节点能看的链路不同，举例：

产物（Artifact）节点：可看"包含的观点""引用该产物的观点""相关的运行代码""引用的论文""相关任务"等。
论文（Paper）节点：可看"抽取的证据""引用该论文的观点""搜索出该论文的任务"等。
任务（Task）节点：可看"上一个任务""下一个任务""任务目标"。

按钮按存在性动态显示：某条链路在图里没有对应数据时，对应按钮会直接隐藏，不会点了报空。看完点顶部 ← 返回全图回到完整图谱。

3.5 色块类型筛选

图谱顶部有一排色块条，每个色块代表一种节点或边类型。点某个色块只看这一类的节点/边，再点取消；可以同时筛多类。悬停色块会弹出该类型的含义说明。

节点颜色（供对照）：研究目标红、任务青、工具调用橙、论文粉、证据绿、观点橙、代码紫、产物青绿。

3.6 节点详情面板

点一个节点选中它，右侧详情面板显示该节点的字段（如代码内容、文件路径、论文标题、观点正文）与它相关的关系列表，可直接跳转到关联节点。

3.7 首次导览

第一次打开图谱时，会有一个两步的操作指引弹窗：第一步讲默认研究主线视图与双击展开，第二步讲顶部色块筛选。可按"下一步"看完，或"跳过"。之后想再看可重新触发。

4. 报告里的引用 chip

科学记忆开启后，智能体写最终总结报告时会带可点击的 [alias] chip（引用标签）。报告正文里的每个 chip 对应一段被引用的内容，可能是从论文抽取的证据，也可能是代码跑出的产物。点 chip 即弹出该证据/产物的详情与来源链路，可逐条核验"结论从哪来"。无 chip 的报告会被视为未完成。

5. 排查

现象	排查方向
设置区显示 `degraded`	Neo4j 没起或 7474 不通。`curl -s http://127.0.0.1:7474` 看是否返回 JSON；检查 `docker ps` / `systemctl status neo4j`。
显示 `needs-password`	密码没推到侧车。回设置把密码填上、保存；若已填，确认密码和 Neo4j 里设的一致。
改了 `src` 重新跑还是旧行为	改源码后要先 `pnpm build` 重建再重启，否则跑的是旧产物。
图谱是空的	本会话还没产生执行事件（任务链是在代码执行/文献检索完成时才镜像写图的）。先跑一个任务再说。
Docker 里连不上宿主 Neo4j	容器走回环时，`127.0.0.1:7474` 指的是容器自己。把 Neo4j HTTP 地址改成宿主在容器内可达的地址（如 `host.docker.internal:7474` 或宿主 IP），并确保 Neo4j 监听非回环。

6. 下一步

功能架构、节点/边类型、完整 API：科学记忆说明
端到端文献调研案例（含科学记忆实战）：文献调研案例指南
环境变量、端口、数据布局：配置参考