hivemind

<div align="center"> <img src="docs/assets/hivemind-banner.svg" alt="hivemind — 知识凝聚引擎" width="100%"> <p><em>连接每个笔记、每个决策、每个会话的共享网络，形成单一的超级有机体。<br>将 AI 编程代理的瞬时上下文转化为持久、自我改进的知识库。</em></p> [](https://github.com/alexiagnocco/hivemind/actions/workflows/ci.yml) [](LICENSE)    [](https://alexiagnocco.github.io/hivemind/) **[进入 hive — 查看文档站点&nbsp;→](https://alexiagnocco.github.io/hivemind/)** </div> --- ## 60 秒了解 hivemind - **AI 编程代理的工作记忆层** — 一个 Python/FastMCP MCP 服务器（23 个工具，207 个测试），任何 MCP 客户端都可以加载。 - **学习检索**：关键词 + 稠密向量融合（Reciprocal Rank Fusion），通过强化学习效用信号重新排序，奖励实际在后续工作中**引用**的笔记。 - **完整的代理行为栈**：22 种技能，15 个钩子，8 条规则和 3 个子代理，使代理在行动前检索，工作时持久化，之后提取学习成果。 - **五分钟演示**：克隆 → 在 Claude Code 中打开 → 排名检索，知识健康指标和跨领域合成，基于 53 个笔记的种子语料库，无需外部服务。 <img src="docs/assets/demo-retrieve.png" alt="hive_retrieve 在演示语料库上：三个排名笔记，带有每个组件的得分分解，混合 RRF 模式和记录的 retrievalId — 顶部命中结果显示为零关键词重叠" width="100%"> --- hivemind 是一个**自主平台基础设施**：使 AI 编程代理在使用的过程中变得明显更好。Python MCP 服务器实现了**混合检索和强化学习反馈环**；分层技能、钩子、规则和子代理模式使代理在**行动前检索，在工作时持久化，并在之后学习实际有用的知识**；整个环路被监控 — 检索覆盖率、精度和知识健康是可衡量的指标。hivemind 在任何 MCP 客户端上运行。 主题灵感来自 *Stranger Things* 中的 hive mind：一个单一的超心理网络连接每个节点成为一个有机体。这里的节点是 Markdown 笔记，连接的线索是 `[[wikilinks]]`，中心智能是 MCP 服务器（**Vecna**），检索延伸到 **the Void**，学习环路 — 随着每次使用而变得更加敏锐的部分 — 自然是 **Eleven**。完整的命名映射在 [CLAUDE.md](CLAUDE.md) 中。 hivemind 配备了**种子 53 笔记演示语料库**，涵盖代理平台工程 — 代理环路设计，MCP 服务器和网关模式，评估和可观察性，可靠性防护 — 因此检索排名，链接图，MOC 和健康指标都在现实内容上进行演示，而无需外部服务。每个种子笔记都标记为 `seed: demo` 并在 [`30-resources/demo-corpus-readme.md`](30-resources/demo-corpus-readme.md) 中公开为合成语料库；语料库作为系统自身工程思维的-readable 导览。 论文核心思想： > 知识库只有在快速呈现正确的信息方面做得比遗忘更快时才会增值：**σ · ρ > δ / 100**。 - **σ** — 检索**覆盖率**：你知道多少信息并且实际呈现出来。 - **ρ** — 检索**精度**：呈现的信息有多实用。 - **δ** — **衰减**：未使用的知识变 stale 的速度。 当 `σ·ρ` 超过 `δ/100` 时，系统处于**逃逸速度** — 它积累有用的、可检索的知识的速度比遗忘的速度更快。hivemind 的每一层都旨在推动其中一个指标朝着正确的方向发展。 > **致谢**：此复合模型 — 方程，**逃逸速度** 和 σ/ρ/δ 项 — 改编自 [AgentOps · *The Science*](https://boshu2.github.io/agentops/the-science/) by [`boshu2`](https://github.com/boshu2/agentops) （Apache-2.0）。hivemind 是该想法的独立实现。参见 [CREDITS.md](CREDITS.md)。 --- ## 工程核心 检索引擎（`hive_retrieve`）是一个**两阶段混合排名器，带有学习效用信号**： 1. **融合 / 候选资格**。每个合格的笔记同时通过两种方式评分 — 关键词复合评分（`match·3 + freshness·2 + connectivity·1`）和查询嵌入的稠密向量余弦相似度 — 然后通过 **Reciprocal Rank Fusion** 融合（二者取 `sum(1/(k+rank))`；如果设置 `HIVEMIND_FUSION=znorm`，则保留之前的 z-norm 评分融合）。由于候选资格不再需要关键词匹配，**概念**相关的笔记即使没有共享关键词也能被检索到。 2. **MemRL 重新排序**。顶部池通过**强化学习效用信号**重新排序：`+ LAMBDA_UTILITY · zNorm(utility)`。每次检索的笔记在后续工作中被**引用**时，其效用就会被奖励；当它被检索但被忽略时，则不会。效用跟踪为每个笔记的指数移动平均值（`α = 0.3`），因此排名器不断学习哪些笔记实际上值得被检索 — 而不仅仅是哪些笔记与关键词匹配。 这是使系统**复合**的环路：检索提供工作，工作发出反馈信号，反馈信号使下一次检索更准确。 ```mermaid flowchart LR Q["查询"] --> F["融合<br/>关键词复合 + 稠密余弦 · RRF"] F --> RR["MemRL 重新排序<br/>+ λ · 效用"] RR --> O["排名笔记"] O --> W["工作引用笔记"] W --> FB["hive_feedback<br/>奖励 · EMA α=0.3"] FB -.->|使下一次检索更准确| RR ``` `hive_feedback` 记录奖励；`hive_sigma_rho` 读取累积的反馈数据作为衡量的覆盖率/精度；`hive_health` 报告整个系统是否处于逃逸速度。即使在没有 Obsidian 的情况下，学习环路仍然保持活跃 — 在 `fs_only` 模式下，文件系统是事实来源，MemRL 写入生效。 三个检索改进建立在排名器之上： - **块粒度**。`hive_retrieve(granularity="chunk")` 返回章节锚定命中结果和摘录。笔记在标题边界处分割，带有 **Contextual Chunk Headers**（标题/路径/breadcrumb/tags 嵌入到每个块的向量中），增量缓存到持久的块索引中，只有当内容或上下文哈希更改时才重新嵌入。 - **响应投影层级**。每个返回列表的工具都接受 `detail: minimal|standard|full` — `minimal` 消耗约 30 个 token，每个项目，`full` 携带每个组件的得分分解。 - **一次性上下文包**。`hive_context` 带有查询返回项目内存，评分最高的命中结果，顶级命中结果的链接图邻居和记录的 `retrievalId`，所有这些都在单个 ≤1200-token 调用中 — 会话的第一个工具调用已经可以关闭 MemRL 环路。 嵌入是可插拔的：一个依赖无关的**哈希**后端（确定性 SHA-1 特征哈希，始终可用）或一个**语义 ONNX** 后端（通过 `onnxruntime` 的真正句子转换器）。每个笔记和块的向量都增量缓存并按内容哈希键控；只有更改的笔记重新嵌入。 --- ## 架构 四个可组合的定制层，加上它们所操作的数据基质。 ```mermaid flowchart TD subgraph layers["Claude Code 定制层"] direction LR S["技能 · 22<br/>斜杠命令工作流"] H["钩子 · 15<br/>确定性生命周期自动化"] R["规则 · 8<br/>始终加载的约定"] A["代理 · 3<br/>上下文隔离的子代理"] end layers -->|读写| MCP["hivemind MCP 服务器 — Vecna<br/>23 个工具 · Python / FastMCP<br/>混合检索 · MemRL · 健康度"] MCP -->|操作于| V["hive<br/>PARA 有组织的 Markdown 笔记"] V -.->|反馈信号| MCP ``` | 层级 | 它是什么 | 为什么它独立 | |---|---|---| | **MCP 服务器** (`_meta/mcp-server-py/`) | 一个 23 工具的 Python [FastMCP](https://github.com/jlowin/fastmcp) 服务器：检索，链接图，知识健康和读写工具。`HIVEMIND_PROFILE=lean` 注册精简版 8 工具核心，用于 token 计量的客户端。 | 访问 + 计算。独立于任何 MCP 客户端。 | | **技能** (`.claude/skills/`) | 斜杠命令工作流（`/boot`，`/recall`，`/evolve`，`/wrap`，...），将 MCP 工具组合成运行手册。 | 教导代理**如何**一致地使用工具。 | | **钩子** (`.claude/hooks/`) | 连接到生命周期事件的 shell 脚本（`PreToolUse`，`PostToolUse`，`Stop`，...）。 | 强制执行**无论模型如何** — 例如阻止活动笔记的 `rm`。 | | **规则** (`.claude/rules/`) | 始终加载的行为约定（检索顺序，frontmatter 模式，提示系统）。 | 在没有斜杠命令的情况下塑造默认行为。 | | **代理** (`.claude/agents/`) | 上下文隔离的子代理定义，用于分工（规划，研究，LLM 工程）。 | 将大型子任务排除在主上下文窗口之外。 | MCP 服务器本身是干净分层的：**调度器**将每个调用路由到文件系统实现或可选的 Obsidian Local REST API，并在 REST 不可用时优雅降级；**连接监视器**在后台轮询跟踪 REST 健康状况；**清单构建器**维护元数据 + 链接图索引（并在启动时自动构建）；**评分**包包含检索数学，嵌入后端，MemRL 效用和健康方程；**状态**层处理增量嵌入/块/效用缓存，具有原子写入。参见 [`_meta/mcp-server-py/README.md`](_meta/mcp-server-py/README.md) 以了解模块级游览。 --- ## 参考 <details> <summary><b>23 个 MCP 工具</b></summary> <br> **读取 / 搜索** | 工具 | 描述 | |---|---| |hive_status|连接状态，插件版本，服务器健康度和活跃的嵌入后端（语义 vs 词典备用）。| |hive_search|按元数据筛选器和/或文本查询搜索 hive 笔记。`detail: minimal\|standard\|full`.| |hive_read|按路径读取一个或多个 hive 笔记的完整内容。| |hive_recent|获取最近 N 天修改的笔记。| |hive_related|获取笔记的双向链接邻居。| |hive_manifest|返回 hive 清单索引。| |hive_rebuild|重建清单索引并预热笔记嵌入和块索引。| |hive_document_map|获取笔记的标题/块/frontmatter 骨架。需要 REST。| |hive_tags|列出所有标签及其分层计数。需要 REST。| |hive_active|读取、追加或替换 Obsidian 中当前打开的笔记。需要 REST。| <br> **检索 + 知识健康** | 工具 | 描述 | |---|---| |hive_retrieve|混合 RRF 融合关键词 + 稠密检索，带有 MemRL 重新排序。`granularity: note\|chunk` 用于章节锚定命中结果。| |hive_health|计算知识健康指标：K，I(t)，delta，sigma，rho，phi，逃逸速度，dK/dt。| |hive_context|一次性预会话上下文包：项目内存 + 评分最高的命中结果 + 顶级命中结果的邻居 + 记录的 retrievalId。| |hive_session_check|会话后验证：检查知识是否正确持久化。| |hive_feedback|记录检索的笔记是否实际有帮助（MemRL 反馈环路）。在 fs_only 模式下工作。| |hive_sigma_rho|从 MemRL 反馈数据计算真正的 sigma 和 rho。| |hive_prune_dryrun|干预式修剪扫描：按类别计算候选者而不移动任何内容。| |hive_unmined_sessions|检查应处理的未挖掘会话以进行知识提取。| <br> **写入** | 工具 | 描述 | |---|---| |hive_checkpoint|会话中途增量项目内存更新。| |hive_patch|通过 REST PATCH 进行外科手术式标题/块/frontmatter 编辑。需要 REST。| |hive_periodic|每日/每周/每月/每年/每年的笔记 CRUD。需要 REST。| |hive_command|列出或运行 Obsidian 命令。需要 REST。| |hive_open|将笔记聚焦到 Obsidian UI 中。需要 REST。| **精简版配置文件** (`HIVEMIND_PROFILE=lean`) 只注册 8 个核心工具：`hive_status`，`hive_search`，`hive_read`，`hive_related`，`hive_retrieve`，`hive_context`，`hive_feedback`，`hive_rebuild`. </details> <br> <details> <summary><b>22 个技能</b></summary> <br> **会话生命周期** | 技能 | 描述 | |---|---| |boot|会话启动：获取日期，加载上下文，检查健康状况，并显示相关知识 — 打开 Gate。| |wrap|会话结束：回顾，反馈，交接，提交，退出 — 关闭 Gate。| |handoff|捕获会话上下文以实现会话间的连续性。| <br> **检索 & 反馈** | 技能 | 描述 | |---|---| |recall|带有相关性排名的结构化 hive 检索。| |retrieve|带有 MemRL 效用加权的复合评分 hive 检索。| |feedback|记录检索的 hive 笔记是否有帮助（MemRL 反馈环路）。| |sigma-rho|从 MemRL 反馈数据计算真正的 sigma 和 rho。| <br> **知识健康** | 技能 | 描述 | |---|---| |health|从知识复合方程快速获取知识健康指标。| |health-check|快速进行 hive 健康扫描，检查孤立笔记，损坏的链接，缺少的 frontmatter 和过时内容。| |prune|存档过时笔记，清理已完成的项目，并维护 hive 规模 — 修复后的健康检查。| |link-repair|修复损坏的 wikilinks，链接孤立笔记到 MOC，并修复 escape-character 错误。| <br> **智能与进化** | 技能 | 描述 | |---|---| |evolve|提出 hive 结构改进建议，并将捕获的学习成果传播到操作表面（技能，规则，钩子）。| |connect|查找笔记之间的跨领域连接和合成机会。| |think-deep|复杂决策的扩展推理 — 收集上下文，深入推理，并持久化思考链。| |weekly-review|生成'hive 状态'评估，说明什么有效，什么正在衰减，以及接下来要做的事情。| <br> **捕获** | 技能 | 描述 | |---|---| |new-note|创建带有适当 frontmatter，命名和链接的新笔记。| |retro|捕获开发工作的学习成果和回顾。| |mine-sessions|查找并从未挖掘的 Claude Code 会话中提取知识 — 项目 NINA。<br> **工程** | 技能 | 描述 | |---|---| |frame|设计项目脚手架，目录层次结构和命名约定 — 或审计和重组现有代码库。| |execute|任务前纪律：思考后编码，优先考虑简单性，手术式更改，目标驱动执行。| |readme|生成一个全面的，研究-backed 的 README.md 任何项目，通过分析代码库。| |ai-engineer|LLM 应用手册： | Skill | 描述 | |---|---| |ai-engineer|LLM 应用手册：RAG，代理，提示/上下文工程，工具使用，结构化输出，评估。 与 `ai-engineer` 子代理配对。| </details> <br> <details> <summary><b>嵌入后端</b></summary> <br> | 后端 | 依赖 | 注释 | |---|---|---| | 哈希（默认备用）| 无 | 确定性 SHA-1 特征哈希。始终可用。**词典，非语义**。| | ONNX | `embeddings` 额外 | 真正的句子转换器（例如 all-MiniLM-L6-v2）通过 onnxruntime。**语义**。| 每个笔记和每个块的向量都增量缓存（按内容哈希键控）；只有更改的笔记重新嵌入。 </details> --- ## 快速开始 ```bash # 1. 安装 MCP 服务器（Python | uv） cd _meta/mcp-server-py uv sync --extra dev uv run pytest -q # 207 个测试（+2 个 ONNX-gated 跳过测试，无需 embeddings 额外功能） # 2. （可选）将 hivemind 指向您自己的 hive — 启动包装器 # 默认情况下 HIVE_PATH 默认为此仓库，它本身就是一个 hive export HIVE_PATH="$HOME/my-hive" # 3. 在 Claude Code 中注册服务器 # .mcp.json 已经在仓库根目录中声明了 `hivemind` 服务器。 # 打开仓库的 Claude Code，23 个工具会自动加载。 ``` **然后在演示语料库上试用**（大约五分钟）：在 Claude Code 中打开仓库并询问检索 — 例如 `hive_retrieve("tool 调用应该如何安全地处理重试")` — 您将获得带有分数的排名笔记和 `retrievalId`。尝试在相同查询上使用 `granularity: "chunk"` 以获取章节锚定命中结果。运行 `/health`，您将看到基于语料库的知识健康状况读数，逃逸速度为真。运行 `/connect` 以查看它在 `30-resources/synthesis/` 中生成跨领域合成笔记 — 该文件夹故意为空。 <img src="docs/assets/demo-health.png" alt="/health 读数超过演示语料库：状态 COMPOUNDING，K=68，sigma 1.0，rho 0.741，delta 0.279 — sigma 乘以 rho 超过 100 的 delta，因此逃逸速度为真" width="100%"> 服务器以**文件系统优先**的方式运行 — 无需外部服务，MemRL 学习环路在纯文件系统模式下保持活跃。要启用与 Obsidian 的实时双向同步，请安装 [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) 插件并设置 `OBSIDIAN_API_KEY`（或将其存储在服务 `hivemind` 的 OS 密钥环中）。要启用语义嵌入后端： ```bash cd _meta/mcp-server-py uv sync --extra embeddings uv run --extra embeddings python scripts/fetch-embedding-model.py export HIVEMIND_EMBEDDINGS_BACKEND=onnx export HIVEMIND_EMBEDDINGS_MODEL_DIR=$PWD/models/all-MiniLM-L6-v2 ``` 启动包装器自动检测 `models/all-MiniLM-L6-v2/` 中获取的权重，因此如果权重位于非默认位置，则只需两个导出语句即可。无需权重，服务器将启动依赖无关的哈希后端 — `hive_status` 始终报告正在使用的后端。 ## 远程运行 在 [Claude Code 网页版](https://claude.ai/code) 中打开此仓库，平台将自动配置 — 无需本地设置。`SessionStart` 钩子（[`.claude/hooks/session-provision.sh`](.claude/hooks/session-provision.sh)）在会话首次启动时运行： 1. **依赖项** — `uv sync` 安装服务器（开发版 + 嵌入式额外功能）。 2. **索引** — hive 清单被构建，以便在第一个提示时可以检索已播种的语料库。 3. **嵌入** — 如果环境网络策略允许，MiniLM ONNX 权重将被获取；否则，服务器将在确定性哈希后端启动。无论哪种方式，`hive_status` 都会报告活动后端 — 备用链本身就是后端可观察性设计的现场演示。 4. **烟雾测试** — 一个真正的 JSON-RPC 会话通过 stdio 驱动（初始化 → 工具/列表 → 状态 → 检索 → 健康），并且结果会出现在会话上下文中。 然后按照上述相同的五分钟路径：请求检索语料库，运行 `/health`，运行 `/connect`。 关于烟雾测试客户端（[`scripts/stdio-smoke.py`](_meta/mcp-server-py/scripts/stdio-smoke.py)）的一个说明：它保持标准输入打开，直到读取完所有预期响应。stdio MCP 服务器在标准输入 EOF 时开始关闭并取消正在进行的工具调用，因此一次性 shell 管道（`printf ... | server`）会静默地丢弃慢调用 — 失败会伪装成损坏的工具。如果您使用服务器编写自己的测试框架，请保持标准输入打开。 --- ## 仓库布局 ```text hivemind/ ├── .claude/ │ ├── skills/ 22 个斜杠命令工作流（+ 评估框架） │ ├── hooks/ 15 个生命周期自动化脚本 │ ├── rules/ 8 个始终开启的行为规则 │ ├── agents/ 3 个子代理定义 │ └── settings.json 将钩子绑定到生命周期事件 ├── _meta/ │ ├── mcp-server-py/ hivemind MCP 服务器（Python / FastMCP，207 个测试） │ └── scripts/ 独立的 hive 实用工具 ├── docs/ 文档网站（定制静态网站 → GitHub Pages） ├── .github/workflows/ CI（ruff + pytest）和 Pages 部署 ├── 00-inbox/ … 50-maps/ PARA 知识 hive（已播种的演示语料库） ├── memory/ 项目内存，词汇表（已播种的演示语料库） ├── .mcp.json MCP 服务器注册 ├── CLAUDE.md 代理操作说明（+ 传奇命名映射） ├── STRUCTURE.md hive 布局 + 自定义层，解释 └── EXAMPLES.md 端到端会话演练 ``` 该仓库是**引擎 + 一个已播种的演示 hive** — PARA 文件夹包含 53 个笔记演示语料库（每个文件标记为 `seed: demo`），因此所有循环都是开箱即用的。要使其成为您自己的：请将 `HIVE_PATH` 指向您自己的 hive，或者直接在此基础上进行修改，并在需要时删除已播种的文件 — 引擎不依赖于它们。 ## 技能评估 技能是根据分级的前后基准进行调整的，而不是凭感觉。[`.claude/skills/execute-workspace/`](.claude/skills/execute-workspace/) 包含一个可运行的测试框架，它在三个场景（模糊范围、过度设计诱饵、安全重构）中评估 `/execute` 技能，在加载和不加载技能的情况下进行评估，因此技能质量的回归是可衡量的。 ## 致谢 hivemind 的知识复合论 — `σ·ρ > δ/100` 逃逸速度模型，σ/ρ/δ 项，MemRL 实用程序循环和 40% 上下文规则 — **改编自 [AgentOps · *The Science*](https://boshu2.github.io/agentops/the-science/)**，作者 [`boshu2`](https://github.com/boshu2/agentops)（Apache-2.0）。hivemind 不包含任何 AgentOps 代码；它是该模型的独立实现。 AgentOps 综合了 hivemind 直接依赖的先前研究： - Ebbinghaus（1885），*Memory: A Contribution to Experimental Psychology* — 遗忘曲线（衰减）。 - Darr、Argote 和 Epple（1995），"The Acquisition, Transfer, and Depreciation of Knowledge in Service Organizations," *Management Science* — 约 17%/周的衰减率（δ）。 - Liu 等人（2023），"Lost in the Middle: How Language Models Use Long Contexts," arXiv:[2307.03172](https://arxiv.org/abs/2307.03172) — 长上下文利用（40% 规则）。 - "MemRL: Self-Evolving Agents via Runtime Reinforcement Learning on Episodic Memory"（2026），arXiv:[2601.03192](https://arxiv.org/abs/2601.03192) — 两阶段检索（语义过滤 → 学习实用程序），hivemind 的融合 → MemRL 重排名镜像。 完整署名和完整参考文献列表：[CREDITS.md](CREDITS.md)。 *Stranger Things* 是 Netflix 的作品；这里的 hive-mind 命名是一种亲切的粉丝致敬，而不是官方关联。 ## 许可证 [PolyForm 非商业 1.0.0](LICENSE) — 源代码可用。您欢迎出于任何非商业目的阅读、运行、研究和适配 hivemind：个人使用、研究、教育和评估。**商业使用需要作者的书面许可。** > 必读声明：版权（c）2026 Alex Iagnocco（https://github.com/alexiagnocco） 2026-07-25 之前的仓库快照使用 MIT 许可证；从此日期起，项目使用 PolyForm Noncommercial 1.0.0 许可证。