介绍 Memory Stargraph——GBrain 的 AI 记忆可视化工具

Memory Stargraph 是一款本地 Web 服务，可通过交互式星云实体图探索 GBrain 知识库。我构建它的原因是：我的本地智能体集群现在跨多个主机和运行时共享同一个 GBrain 支持的记忆基础设施。智能体不再需要携带越来越长的上下文，而是依赖一个共享的、不断发展的知识图谱，该图谱保持紧凑、可搜索且长期有用。Memory Stargraph 让这种共享记忆变得可见。你可以查看智能体在 GBrain 中创建的内容，检查实体，探索关系，创建新节点，连接它们，修改链接，附加媒体，并在地图按需加载新邻域时跟随它。它既是调试工具，又是知识浏览器，还能带来“等等，智能体记住了所有这些？”的时刻。而且它出奇地迷人。非常感谢 @garrytan 在 GBrain 上的工作，我很高兴成为 #GBrain 的认真用户之一！如果你有兴趣为自己的智能体搭建它：https://github.com/techtony2018/memory-stargraph… #AI #AIAgents #KnowledgeGraph #LocalAI #OpenSource #BuildInPublic #Codex #OpenClaw

techtony2018/memory-stargraph

来源：https://github.com/techtony2018/memory-stargraph

Memory Stargraph

Memory Stargraph 是一款本地 Web 服务，用于以交互式星云实体图的形式探索 gbrain 知识库。它使用 Python 标准库以及纯 HTML/CSS/Canvas JavaScript 构建，因此无需 npm install 即可运行。

演示

Memory Stargraph 演示预览（https://youtu.be/GbWZo7g1ZBA）

在 YouTube 上观看演示视频（https://youtu.be/GbWZo7g1ZBA）

运行

python3 server.py

可选：

python3 server.py --host 127.0.0.1 --port 8788

打开：

http://127.0.0.1:8788

日常功能

1. 搜索与深入探索

• 按 slug、标题、标签或摘要搜索。
• 按 Return 键或点击 Search 按钮执行 gbrain 搜索。
• 搜索过程中，输入框和按钮会被禁用。
• 点击任意图节点以选中它并加载其直接邻居。
• 双击节点打开只读原始详情。
• 根节点 index 会被主动加载，因此图一开始就具有真实结构。

2. 就地理解关系

• 节点大小随直接连接数缩放。
• 选中节点后，会显示所有直接邻居的标签。
• 悬停直接关联的节点时，鼠标附近会显示一个 60% 透明度的弹出窗口。
• 在移动端 Safari 上，点击节点可在手指附近显示相同的悬停式弹出窗口。
• 在移动端 Safari 上，长按节点仅显示悬停式弹出窗口。
• 在移动端使用选中节点面板中的 ... 按钮打开节点操作菜单。
• 悬停弹出窗口显示实体名称/类别、简短摘要以及关系类型。
• 悬停直接邻居时，该关系也会在选中节点的边上绘制。
• 侧边栏中的直接链接芯片在悬停/聚焦时显示关系类型。

3. 导航星云图

• 拖拽图可旋转 3D 星云视角。
• 使用 + / - 按钮缩放。
• 使用 Cmd + 鼠标滚轮 快速缩放。
• 可组合使用类别/类型/最小链接数过滤器；过滤器之间是 AND 关系，且可清除。
• 切换 Only show matches 以减少视觉干扰。

4. 从节点菜单使用 GBrain

右键单击节点，或点击节点摘要旁的 ... 按钮。View 刻意排在首位以便快速阅读，其后是 Ask GBrain 用于上下文提问。

支持的节点操作：

1. View - 以只读方式渲染节点的 gbrain markdown，包含 wiki 样式的 [[Entity]] 链接。
2. Ask GBrain - 打开聊天式 Q&A 面板，利用直接的图上下文、相关时检测到的媒体以及针对性的 gbrain query 检索来回答问题。
3. View media - 打开节点 markdown 或 frontmatter 中检测到的图片/视频/音频/PDF 链接。
4. Show backlinks - 使用 gbrain backlinks 显示入链。
5. Graph query from here - 执行类型/方向化的图遍历。
6. View history - 显示页面版本历史。
7. Add relationship - 搜索/选择目标节点和关系类型，同时允许输入新的关系类型。
8. Remove relationship - 仅从现有关系中搜索/选择，然后用 gbrain unlink 移除该边。
9. Edit tags - 选择已有标签来添加，接受新标签，并移除已应用于实体的标签。
10. Add timeline event - 使用 gbrain timeline-add 写入一条带日期的记录。
11. Attach file - 打开浏览器文件选择器，上传所选文件，追加 markdown 媒体引用，并预览支持的媒体类型。
12. Refresh embedding - 如果当前后端支持，则运行 gbrain embed <slug>。
13. Modify markdown - 使用 gbrain put 编辑页面。
14. Hide - 仅在 Web UI 中隐藏节点。
15. Copy slug - 复制精确的 gbrain slug。
16. Delete from gbrain - 在确认精确节点名称后删除。

节点操作 API 约定：

• GET /api/node-operations - 列出支持的操作端点。
• GET /api/entity-media/<slug> - 列出从节点 markdown/frontmatter 检测到的媒体引用。
• GET /media/<path> - 以只读方式提供配置的本地媒体文件。
• POST /api/entity-ask/ - 询问 gbrain 关于某个节点。
• POST /api/entity-backlinks/ - 显示反向链接。
• POST /api/entity-graph-query/ - 执行类型/方向化图遍历。
• POST /api/entity-history/ - 显示页面历史。
• POST /api/entity-link/ - 添加有类型的关系。
• POST /api/entity-unlink/ - 移除关系。
• POST /api/entity-tags/ - 添加/移除标签。
• POST /api/entity-timeline/ - 添加时间线事件。
• POST /api/entity-attach-file/ - 向节点附加文件。
• POST /api/entity-embed/ - 在支持的情况下刷新嵌入。

5. 保持视图整洁

• 从星云中隐藏节点而不修改 gbrain。
• 隐藏的节点出现在侧边栏 Hidden List 中。
• 隐藏的节点可通过 Show 恢复。
• 隐藏列表状态在本地 Web 后端跨启动持久化。
• 重复的日期报告（如 agent/reports/gbrain-usage-YYYY-MM-DD）会折叠为一个聚合节点。
• 文档部分（如 The RFC - JTuner - Part xx）会折叠为一个父节点。
• 路径风格的标签会被人性化处理，例如 companies/uber 变为 Uber。

本地媒体 URL

当媒体已经托管时，使用正常的 HTTP/HTTPS 链接：

cover_image: https://example.com/assets/project-cover.jpg

对于本地 gbrain 媒体，在节点中保留相对路径：

cover_image: projects/example-project/project-cover.jpg

当 View media 打开时，Memory Stargraph 首先检查该文件是否已在 media_roots 下。如果不在，则搜索 media_discovery_roots，将文件复制到第一个媒体根目录中，然后提供该文件。默认情况下，发现操作停留在应用拥有的目录（如 media、data/media 和 data/uploads）内，因此 macOS 不会请求访问用户文件夹（如 Downloads 或 Desktop）。仅在明确本地选择加入的情况下添加用户文件夹。

如果 gbrain 能生成签名 URL，该服务也可以将该 URL 获取到媒体根目录中。

当 Web 服务运行在与 gbrain 数据/媒体主机不同的主机上时，请在 Web 主机上配置 remote_media_base_urls。每个基础 URL 应指向能访问原始媒体文件的机器上的可信只读 /media/ 端点。Web 主机将从该端点获取缺失的媒体，缓存到自己的第一个 media_roots 条目中，然后本地提供。

示例配置：

{
  "media_roots": ["media", "data/media"],
  "media_discovery_roots": ["media", "data/media", "data/uploads"],
  "remote_media_base_urls": ["https://gbrain-media.example.com/media/"],
  "media_fetch_timeout_seconds": 8,
  "max_upload_bytes": 26214400
}

日常使用中，从节点菜单中选择 Attach file，在 Finder 中选择文件，并可选添加简短描述。该服务会保存上传，将支持的媒体复制到 media_roots 中，在节点页面上追加一个 ## Attachments markdown 引用（使用描述作为标题或替代文本），并返回 /media/... 预览 URL。主机本地路径附加仍可通过 JSON API 用于自动化。

Memory Stargraph 在以下路径以只读方式提供支持的图片/视频/音频/PDF 文件：

http://<host>:8788/media/projects/example-project/project-cover.jpg

媒体路由会拒绝路径遍历和非媒体扩展名。

6. 刷新与新鲜度

• Refresh Graph 是幂等的，刷新进行中会禁用。
• 从右上角控件可选择启用自动刷新。
• 自动刷新间隔可编辑（以分钟为单位）。
• 头部显示最近的刷新时间。
• /api/health 特意保持轻量，不消耗额外的 gbrain 图/查询预算。

GBrain 集成

默认后端路径：

/opt/homebrew/bin/gbrain

加载策略：

1. gbrain list -n 140
2. 主动根扩展：gbrain graph index --depth 1 和 gbrain backlinks index
3. 惰性节点扩展：gbrain graph <slug> --depth 1 和 gbrain backlinks <slug>
4. 搜索丰富：gbrain search <query>
5. 按需原始详情：gbrain get <slug>

如果实时 gbrain 访问失败，服务会：

1. 尝试上次成功加载的 data/graph_cache.json。
2. 回退到捆绑的演示数据。
3. 在 UI 中显示缓存/演示/错误状态。

本地配置

已提交的示例：

config/local.example.json

本地覆盖（被 Git 忽略）：

config/local.json

支持的配置键包括：host、port、public directory、data directory、gbrain path、list count、graph depth、cache staleness、command limit 和 command pause。

运行时状态（仅本地）：

data/graph_cache.json
data/hidden_entities.json
data/deleted_entities.json

部署注意事项：

• 保持 config/local.json 不被提交，且每台机器专用。
• 对于局域网或远程访问，在 config/local.json 中设置 "host": "0.0.0.0"，或传递 --host 0.0.0.0。
• 将 "gbrain_path" 设置为目标机器上 gbrain 二进制文件的绝对路径。
• 如果 gbrain 安装在用户本地的包管理器路径中，请在启动或测试服务前导出该路径。
• 如果 Web 主机不是媒体存储主机，请将 "remote_media_base_urls" 设置为存储主机上可信的媒体端点。
• 保持媒体根目录在目标机器本地，并避免提交上传的媒体或运行时缓存文件。

AI Agent 设置提示

当要求 AI 编码 agent 设置、验证或继续 Memory Stargraph 时，使用以下提示：

你正在处理 Memory Stargraph，从 `[email protected]:techtony2018/memory-stargraph.git` 的干净克隆开始。

目标：
- 设置并验证用于 gbrain 实体图的本地 Memory Stargraph Web 服务。
- 保持本地运行时状态与公共仓库文件分离。
- 不要提交 `data/*.json`、`config/local.json`、`.DS_Store`、缓存、截图或私有的 `.project/` 笔记。

仓库和公共布局：
- 公共仓库目标：`[email protected]:techtony2018/memory-stargraph.git`
- Python 服务：`server.py`
- 公共 Web 文件：`public/index.html`、`public/styles.css`、`public/app.js`
- 配置示例：`config/local.example.json`
- 本地覆盖：`config/local.json`（被 Git 忽略）
- 运行时状态：`data/graph_cache.json`、`data/hidden_entities.json`、`data/deleted_entities.json`（被 Git 忽略）

期望的本地服务：
- URL：`http://127.0.0.1:8788`
- 健康检查：`curl -sS http://127.0.0.1:8788/api/health`
- 默认 gbrain 路径：`/opt/homebrew/bin/gbrain`
- 在其他机器上，将 `"gbrain_path"` 设置为已安装的 gbrain 二进制文件，仅在需要远程访问时设置 `"host": "0.0.0.0"`，当媒体位于另一台主机时设置 `"remote_media_base_urls"`，并在启动服务前导出任何必需的包管理器路径。

设置步骤：
1. 检查 `git status --short`，不要还原无关的用户更改。
2. 如有需要，将 `config/local.example.json` 复制为 `config/local.json`，并仅调整本地机器值。
3. 在远程或共享机器上，设置 `config/local.json` 以使用目标机器的 `"gbrain_path"`，并为任何本地 gbrain 图片文件夹添加一个 `media_roots` 条目。如果媒体存储在不同主机上，请将该主机的 `/media/` 端点添加到 `"remote_media_base_urls"`。
4. 使用 `python3 server.py --host 127.0.0.1 --port 8788` 启动服务。
5. 打开 `http://127.0.0.1:8788` 并验证图是否加载。
6. 在 gbrain 中搜索已知实体，选中它，悬停一个直接邻居，确认鼠标附近弹出窗口显示关系类型。
7. 确认 `View` 是第一个节点菜单项，并且所有节点操作都能正常渲染。

验证命令：
- export PATH="$HOME/.bun/bin:/usr/local/bin:/opt/homebrew/bin:$PATH"
- python3 -m py_compile server.py
- python3 -m unittest discover -s tests
- node --check public/app.js
- node --check tests/browser_smoke.mjs
- node tests/browser_smoke.mjs
- 如果 Playwright 本地无法解析，使用 `npx --yes --package playwright node tests/browser_smoke.mjs`。

需要保留的节点操作：
1. View
2. Ask GBrain
3. View media
4. Show backlinks
5. Graph query from here
6. View history
7. Add relationship
8. Remove relationship
9. Edit tags
10. Add timeline event
11. Attach file
12. Refresh embedding
13. Modify markdown
14. Hide
15. Copy slug
16. Delete from gbrain

行为要求：
- 根节点 `index` 应始终主动加载。
- 搜索应通过按 Return 或点击 Search 按钮明确执行。
- 刷新图应在进行中时禁用。
- 隐藏节点仅影响 UI，并在本地后端持久化。
- 悬停时，关系应在 60% 透明度的鼠标附近弹出窗口中可见。
- 选中节点时，直接邻居标签应可见。
- 路径风格的标签应人性化处理，例如 `companies/uber` 变为 `Uber`。
- 聚合的部分/报告节点应保持折叠状态。

安全性：
- `Hide` 仅影响 UI。
- `Delete from gbrain`、markdown 编辑、关系编辑、标签、时间线事件和文件附件会修改 gbrain。
- `Refresh embedding` 在瘦客户端模式下可能不可用；应显示真实的 gbrain 错误而非隐藏它。
- 在验证命令通过并且浏览器冒烟测试已运行或报告了特定阻塞问题之前，不要推送。

项目布局

• server.py - Python 标准库 Web 服务和 gbrain 命令适配器
• public/index.html - 应用外壳
• public/styles.css - 视觉系统和响应式布局
• public/app.js - 图渲染、交互和节点操作
• tests/test_graph_parsing.py - 后端解析器和命令构建测试
• tests/browser_smoke.mjs - Playwright 端到端冒烟测试
• dashboard-integration.json - All Things Codex Dashboard 启动器元数据

验证

python3 -m py_compile server.py
python3 -m unittest discover -s tests
node --check public/app.js
node --check tests/browser_smoke.mjs
node tests/browser_smoke.mjs

有用的实时检查：

curl -sS http://127.0.0.1:8788/api/health
curl -sS http://127.0.0.1:8788/api/graph

许可证

Memory Stargraph 以 MIT 许可证发布。参见 LICENSE。

说明

• Refresh embedding 取决于活动的 gbrain 后端。瘦客户端后端可能报告 embed 是主机侧/不可路由的。
• Hide 仅影响 UI；不会修改 gbrain。
• Delete from gbrain、markdown 编辑、关系编辑、标签编辑、时间线编辑和文件附件会修改 gbrain。