内容
<p align="center">
<img src="docs/cover.png" alt="BDH 图形框架" width="100%">
</p>
# BDH 图形框架
基于图的检索系统，适用于 Obsidian 知识库，结合赫布学习。
## 功能
将 Obsidian 知识库转化为一个动态的知识图谱：
- **笔记 → 神经元** — 每个笔记都嵌入 `nomic-embed-text-v2-moe`（Ollama，本地）
- **维基链接 → 突触** — 图谱边缘来自 `[[维基链接]]`
- **赫布学习** — 共同激活的笔记会随着时间的推移加强它们的突触权重（频率 + 最近度 + 激活相关性）
- **混合检索** — 向量相似度（α=0.7）+ BM25 词汇搜索（β=0.3）
- **自适应阈值** — `max(Q75, mean+1std, 0.15)` 动态过滤噪声
- **神经发生** — 大型语言模型从查询中提取新概念，并在知识库中创建笔记
- **大型语言模型响应** — OpenRouter（`openrouter/free`）或本地 Ollama，带有源笔记的引用
- **实时可视化** — vis.js 网络显示节点激活，边缘脉动，赫布权重在查询期间更新
## 架构
```
Obsidian 知识库 → 嵌入（Ollama）→ ChromaDB + 图谱
↓
查询 → 混合搜索（向量 + BM25）→ 注意力扩散（max_hop=2）
↓
赫布更新（共同激活加强）→ 大型语言模型响应（OpenRouter）
↓
WebSocket → vis.js 可视化（节点亮起，突触脉动）
```
## 包结构
```
bdh_graph_harness/
├── __main__.py # CLI 入口点（--serve, --mcp, --query, --refresh）
├── config.py # 配置加载，环境变量扩展，重试逻辑
├── mcp_server.py # MCP 服务器（FastMCP，stdio + HTTP 传输）
├── graph/
│ ├── parser.py # 前面元数据 + 维基链接解析
│ ├── builder.py # 图谱构造 + 增量缓存
│ └── cache.py # 图谱缓存序列化
├── retrieval/
│ ├── embeddings.py # Ollama 嵌入客户端
│ ├── chroma_store.py # ChromaDB 向量存储
│ ├── bm25.py # BM25 词汇索引
│ ├── hybrid.py # 向量 + BM25 融合
│ └── attention.py # 种子选择 + k-hop 扩散 + 自适应阈值
├── memory/
│ ├── hebbian.py # 突触权重更新 + 衰减
│ └── state_store.py # 持久状态（文件锁定）
├── llm/
│ ├── providers.py # 大型语言模型工厂 + 载荷构建
│ ├── ollama.py # Ollama 后端
│ ├── openrouter.py # OpenRouter 后端（OpenAI 兼容）
│ └── prompt.py # 系统提示 + 上下文格式化
├── neurogenesis/
│ ├── creator.py # 概念提取 + 笔记创建
│ └── dedupe.py # 模糊重复检测
├── api/
│ ├── server.py # aiohttp 应用设置 + WebSocket
│ ├── routes.py # REST 端点
│ └── ws.py # WebSocket 处理器
└── visualization/
└── templates/index.html # vis.js 实时图谱 UI
```
`harness.py` 是一个兼容性垫片，重新导出自包 — 测试使用 `import harness`。
## 设置
1. **Ollama** 在本地运行，拉取 `nomic-embed-text-v2-moe`
2. **OpenRouter API 密钥** 在环境变量 `OPENROUTER_API_KEY` 中（或在配置中切换 `llm_provider: ollama`）
3. **Python 3.11+** 带有依赖项：
```bash
pip install -r requirements.txt
```
4. **配置** 知识库路径：
```bash
cp bdh-config.yaml bdh-config.local.yaml
# 编辑 vault_path 以指向您的 Obsidian 知识库
```
## 使用
```bash
# 启动服务器
python -m bdh_graph_harness --serve
# 单次查询（CLI）
python -m bdh_graph_harness --query "come funziona l'apprendimento Hebbian?"
# 强制图谱重建
python -m bdh_graph_harness --refresh
# 打开可视化
open http://localhost:8643
```
### 作为服务运行（macOS）
```bash
# 安装 launchd 服务
cp ai.bdh.graph-harness.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/ai.bdh.graph-harness.plist
```
服务在崩溃时自动重启（`KeepAlive: true`）。日志位于 `~/.hermes/logs/bdh-server.log`。`start-server.sh` 包装器在启动前从 `~/.hermes/.env` 导出 `OPENROUTER_API_KEY`。
## 配置
查看 `bdh-config.yaml` 获取所有参数。主要参数：
| 参数 | 默认值 | 描述 |
|-----------|---------|-------------|
| `seed_count` | 5 | 种子节点的前 k 个嵌入匹配 |
| `max_hop` | 2 | 种子图的遍历深度 |
| `active_threshold` | 0.25 | 最小激活分数（被自适应覆盖） |
| `alpha` | 0.7 | 赫布学习中的频率权重 |
| `beta` | 0.3 | 赫布学习中的最近度权重 |
| `decay` | 0.95 | 未使用突触的每会话衰减 |
| `hybrid_alpha` | 0.7 | 向量搜索权重 |
| `hybrid_beta` | 0.3 | BM25 搜索权重 |
| `llm_provider` | `openrouter` | `openrouter` 或 `ollama` |
| `llm_model` | `openrouter/free` | 自动选择可用的免费模型 |
| `api_port` | 8643 | 服务器端口 |
## 测试
```bash
pytest tests/ -v
```
108 个测试覆盖图谱构建、注意力扩散、自适应阈值、BM25、混合搜索、赫布更新、大型语言模型提供者（Ollama + OpenRouter）、神经发生和 API 端点。
## 可视化
`:8643` 处的 Web UI 显示：
- **节点** 按类型着色（笔记、概念、种子、激活）
- **维基链接边缘** 为蓝色
- **赫布突触** 为青色，宽度与突触权重成比例
- **实时激活级联** — 节点依次亮起，边缘脉动绿色（`#39d353`），当赫布权重在查询期间加强
- **暗色主题** 带有交错动画（120ms 级联，2.5s 内 4 步淡入）
## MCP 服务器
该框架包含一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，将赫布图谱作为工具暴露给任何 MCP 兼容的客户端（Claude Desktop, Cursor, Windsurf, Continue）。
```bash
# stdio 模式（Claude Desktop, Cursor）
python -m bdh_graph_harness --mcp
# HTTP 模式（Web 客户端）
python -m bdh_graph_harness --mcp --mcp-transport http --mcp-port 8644
```
**工具：** `query`（基础 Q&A，带有引用）、`stats`（图谱概览）、`hebbian`（学习突触）、`graph`（完整网络）、`refresh`（重建嵌入）。
MCP 服务器直接导入包 — 不依赖于 HTTP API 服务器。两者可以独立或同时运行。
查看 [`docs/mcp-server.md`](docs/mcp-server.md) 获取客户端配置（Claude Desktop, Cursor 等）。
## Hermes 代理集成
该框架附带一个 [Hermes 代理](https://hermes-agent.nousresearch.com) 技能，允许您从聊天中查询图谱。技能定义在 [`docs/hermes-skill.md`](docs/hermes-skill.md) — 复制它到 `~/.hermes/skills/research/bdh-graph-harness/SKILL.md` 以激活它。
安装后，您的 Hermes 代理可以：
- 通过自然语言查询图谱（“bdh query: Hebbian 学习如何工作？”）
- 显示图谱统计和赫布突触状态
- 启动/停止 API 服务器
- 用源引用呈现答案
## 许可证
MIT
