内容
# HiveMind
> 🚧 **正在积极开发中。** API 和配置文件格式可能会在版本之间发生变化。
用于 AI 编程代理的持久内存。HiveMind 运行一个本地 MCP 服务器，为 Claude Code（和其他 AI 代理）提供一个 SQLite 支持的内存存储，以便在会话中保持上下文、偏好和项目知识。
## 工作原理
1. 您只需运行一次 `hivemind up` 即可启动本地服务器。
2. Claude Code 通过 MCP 连接到它。
3. 在每个会话开始时，Claude 自动回忆为您的项目配置的内存。
4. 您要求 Claude 存储任何值得保留的内容。它不会自动存储。
### 会话启动流程详情
当您在具有 `.hivemind.toml` 的项目中打开一个新的 Claude Code 会话：
1. Claude 读取 CLAUDE.md，该文件指示它调用 `hivemind_session_start` 一次。
2. Claude 调用带有当前项目路径的 MCP 工具。
3. HiveMind 读取 `.hivemind.toml`（如果存在，还会读取 `.hivemind.local.toml`），将每个 `recalls` 条目与 SQLite 数据库进行匹配（按确切标题，然后是全文搜索），并以结构化 JSON 返回结果，同时保持在 `max_tokens` 内。
4. Claude 静默地整合返回的内存，并继续处理您的请求。
就是这样。一次工具调用，一次数据库往返，此后每次提示的开销为零。
### 上下文预算
`max_tokens` 限制防止会话启动消耗太多 Claude 的上下文窗口。内存按顺序加载；如果某个条目会超出预算，则跳过该条目（但稍后，较小的条目仍有机会）。`hivemind status` 命令显示将注入的内容的预览，以及每个内容消耗的令牌数。
---
## 在会话期间获取内存
`.hivemind.toml` 中的 `recalls` 列表仅用于**会话开始时的自动注入**。您可以在会话期间随时按需获取任何内存：
- **按标题或 ID**：询问 Claude：*“回忆标题为‘golang preferences’的内存”* → Claude 调用 `memory_recall`
- **按关键词**：询问 Claude：*“在我的内存中搜索 postgres”* → Claude 调用 `memory_search`（全文搜索，返回片段）
- **浏览所有内存**：使用 `/memory-list` 提示
未列入 `recalls` 的内存仍然可用；它们只是不会自动加载。它们存储在数据库中，您可以随时调用它们。
---
## HiveMind 与 Claude Code 内置钩子的区别
Claude Code 在 `.claude/settings.json` 中有自己的钩子系统：
```json
{
"hooks": {
"UserPromptSubmit": [
{ "hooks": [{ "type": "command", "command": "my-memory-tool search" }] }
]
}
}
```
这会运行一个 shell 命令，并将 stdout 注入到对话中。它有效，但权衡不同：
| | Claude Code `UserPromptSubmit` 钩子 | HiveMind `[hooks.on_session_start]` |
|---|---|---|
| **何时运行** | 您发送的**每个消息** | **每个会话一次** |
| **上下文开销** | 每次都添加到每个提示中 | 一次注入；之后无成本 |
| **令牌预算** | 无；无条件转储所有输出 | `max_tokens` 限制，逐项跳过 |
| **数据源** | shell 命令输出的任何内容 | SQLite FTS 存储，可按标题/ID/关键词查询 |
| **选择性** | 命令返回的内容 | 您为每个项目指定要加载的内存 |
| **持久性** | 无状态；每次调用都会重新运行 | 有状态；内存跨机器和重新安装存活 |
| **按需访问** | 仅限钩子返回的内容 | 完整的 MCP 工具（`memory_recall`、`memory_search`等） |
**简而言之：** 钩子方法在每个消息上重新注入上下文，这会按询问频率成比例地消耗令牌。HiveMind 在会话开始时注入一次，然后不再干扰。之后，Claude 使用它加载的内容，如果需要更多，可以调用按需工具。
---
## 安装
```sh
cargo install oxhivemind # 从源代码编译
cargo binstall oxhivemind # 下载预编译二进制文件（更快）
```
### Claude Code
```sh
hivemind mcp install claude
```
这为您运行 `claude mcp add hivemind --transport http http://127.0.0.1:3456/mcp`。
### OpenCode
```sh
hivemind mcp install opencode
```
写入 `~/.config/opencode/opencode.json`（如果可用，使用 `opencode` CLI，否则直接写入配置文件）。手动配置：
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"hivemind": {
"type": "remote",
"url": "http://127.0.0.1:3456/mcp",
"enabled": true
}
}
}
```
文档：[opencode.ai/docs/mcp-servers](https://opencode.ai/docs/mcp-servers/)
### Kimi Code CLI
```sh
hivemind mcp install kimi
```
如果可用，使用 `kimi` CLI，否则直接写入 `~/.kimi/mcp.json`。手动配置：
```json
{
"mcpServers": {
"hivemind": {
"url": "http://127.0.0.1:3456/mcp"
}
}
}
```
文档：[moonshotai.github.io/kimi-cli/en/customization/mcp.html](https://moonshotai.github.io/kimi-cli/en/customization/mcp.html)
### OpenAI Codex CLI
```sh
hivemind mcp install codex
```
追加到 `~/.codex/config.toml`。手动配置：
```toml
[mcp_servers.hivemind]
url = "http://127.0.0.1:3456/mcp"
```
文档：[developers.openai.com/codex/mcp](https://developers.openai.com/codex/mcp)
### Cursor
```sh
hivemind mcp install cursor
```
写入 `~/.cursor/mcp.json`。重启 Cursor 后生效。手动配置：
```json
{
"mcpServers": {
"hivemind": {
"url": "http://127.0.0.1:3456/mcp"
}
}
}
```
文档：[cursor.com/docs/mcp](https://cursor.com/docs/mcp)
### Windsurf
```sh
hivemind mcp install windsurf
```
写入 `~/.codeium/windsurf/mcp_config.json`。重启 Windsurf 后生效。手动配置：
```json
{
"mcpServers": {
"hivemind": {
"serverUrl": "http://127.0.0.1:3456/mcp"
}
}
}
```
注意：Windsurf 使用 `serverUrl`，而其他客户端使用 `url`。
文档：[docs.windsurf.com/windsurf/cascade/mcp](https://docs.windsurf.com/windsurf/cascade/mcp)
### 其他支持 MCP 的客户端
任何支持 MCP 流式 HTTP 传输的客户端都可以连接到：
```
http://127.0.0.1:3456/mcp
```
本地连接不需要身份验证。
---
## 快速入门
```sh
# 1. 启动服务器（保持终端运行）
hivemind up
# 2. 在新终端中，进入项目并初始化
cd ~/projects/myapp
hivemind init
# 3. 打开新的 Claude Code 会话（现在内存钩子已激活）
```
### 作为后台服务运行（推荐）
与其保持终端打开，不如将 HiveMind 安装为用户级服务，以便在登录时自动启动：
```sh
hivemind service install
```
这会写入一个单元文件（Linux）或 launchd plist（macOS），并立即启用它，无需 `sudo`。
| 平台 | 机制 | 单元文件位置 |
|----------|-----------|-------------------|
| Linux | systemd 用户单元 | `~/.config/systemd/user/hivemind.service` |
| macOS | launchd LaunchAgent | `~/Library/LaunchAgents/com.oxhive.hivemind.plist` |
在 macOS 上，日志写入 `~/Library/Logs/hivemind.log`。
```sh
hivemind service status # 检查是否正在运行
hivemind service uninstall # 停止并移除
```
`hivemind init` 创建：
| 文件 | 描述 |
|------|-------------|
| `.hivemind.toml` | 项目配置（提交此文件） |
| `.hivemind.local.toml` | 个人回忆，gitignored |
| `CLAUDE.md` | 指示 Claude 调用 `hivemind_session_start` |
| `.gitignore` | 添加 `.hivemind.local.toml` 条目 |
它还会将 HiveMind 块追加到 `~/.claude/CLAUDE.md`（保留现有内容），以便 Claude 全局了解如何使用 MCP 工具。
> **如果您已经有一个项目 `CLAUDE.md`**，init 不会修改它。请手动添加此行：
> ```
> 在每个会话开始时，如果项目根目录中存在 `.hivemind.toml`，请调用 `hivemind_session_start`。
> ```
`hivemind init` 创建的 `CLAUDE.md` 仅涵盖如何**使用** HiveMind。它告诉 Claude 何时调用 `hivemind_session_start`，而其他内容则不涉及。它不记录您自己的项目代码库架构。如果您希望 Claude Code 了解您的代码库架构，请在 `hivemind init` 后在 Claude Code 中运行 `/init`。`/init` 命令读取您的源代码并生成一个全面的 `CLAUDE.md`，其中包含构建命令、架构概述和关键设计决策。
---
## 命令
```
hivemind up 启动服务器（MCP + REST API + 仪表盘）
hivemind up --headless 启动时不显示仪表盘 UI
hivemind init 为当前项目搭建配置文件
hivemind status 显示配置、内存数量和会话启动预览
hivemind mcp install claude 注册到 Claude Code
hivemind mcp install opencode 注册到 OpenCode
hivemind mcp install kimi 注册到 Kimi Code CLI
hivemind mcp install codex 注册到 OpenAI Codex CLI
hivemind mcp install cursor 注册到 Cursor
hivemind mcp install windsurf 注册到 Windsurf
hivemind service install 安装并启用为后台服务
hivemind service uninstall 停止并移除后台服务
hivemind service status 显示后台服务状态
hivemind dashboard --open 打开仪表盘（需要服务器运行）
```
---
## 配置
### 项目配置：`.hivemind.toml`
提交到仓库。团队间共享。
```toml
[project]
name = "myapp"
layer = "workspace"
description = "项目简要描述"
[hooks.on_session_start]
max_tokens = 2000
recalls = [
"golang preferences",
"project/myapp",
]
```
`recalls` 是在会话开始时自动注入的内存列表。每个条目按确切标题查找，然后回落到全文搜索。组合大小以 `max_tokens` 为上限。
### 个人配置：`.hivemind.local.toml`
gitignored。您在此添加的个人内容。
```toml
[hooks.on_session_start]
recalls = ["my personal style notes"]
max_tokens = 500 # 添加到团队预算
```
### 全局配置：`~/.config/hivemind/config.toml`
由 `hivemind init` 创建。适用于所有项目。
```toml
[defaults]
max_inject_tokens = 2000 # 项目未设置时的默认令牌预算
[server]
host = "127.0.0.1"
port = 3456
[dashboard]
port = 3457
[sync]
enabled = false
remote_url = "" # sqld 服务器 URL 或 Oxhive 主持的端点
api_key = "" # sqld 身份验证令牌，或 Oxhive 账户密钥
interval_seconds = 300
sync_on_store = true
sync_on_startup = true
```
如果设置了 `XDG_CONFIG_HOME`，则使用 `$XDG_CONFIG_HOME/hivemind/config.toml` 代替。
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `HIVEMIND_DB_PATH` | `~/.hivemind/memories.db` | SQLite 数据库路径 |
---
## 同步（可选）
HiveMind 可以将内存复制到远程服务器，这对于跨机器共享或保持远程备份很有用。同步使用 [libsql](https://github.com/tursodatabase/libsql/tree/main/libsql-server) 嵌入式复制：本地数据库保持完全功能性离线，`hivemind up` 会定期将写入复制到远程主服务器。
```toml
[sync]
enabled = true
remote_url = "http://pi.local:8080" # 参见下面的选项
api_key = "your-auth-token" # 参见下面的选项
interval_seconds = 300 # 每 5 分钟后台同步
sync_on_store = true # 还会在每个内存存储后立即同步
sync_on_startup = true # 服务器启动时同步一次
```
支持两种 `remote_url` 目标：
| 设置 | `remote_url` 指向 | `api_key` |
|-------|------------------------|-----------|
| **自托管** | 您自己的 [sqld](https://github.com/tursodatabase/libsql/tree/main/libsql-server) 服务器 | sqld 身份验证令牌；如果 sqld 未配置身份验证，请留空 |
| **Oxhive 主持** *(即将推出)* | `https://sync.oxhive.dev` | 您的 Oxhive 账户密钥 |
`api_key` 从未发送到 Claude 或仪表盘。它仅在复制期间使用。
---
## 检查您的设置
```sh
hivemind status
```
显示活动配置、内存数量、数据库路径，以及下一次会话启动时将注入的内容预览，包括令牌使用情况与预算。
---
## 故障排除
### "提示：看起来您尚未运行 `hivemind init`"
您在初始化之前运行了 `hivemind up` 或 `hivemind status`。在项目目录中运行 `hivemind init`：
```sh
cd ~/projects/myapp
hivemind init
```
这会创建 `.hivemind.toml`，搭建 CLAUDE.md，并写入全局配置文件，使提示消失。
### "提示：尚未注册任何 AI 客户端与 HiveMind"
您运行了 `hivemind init` 但尚未告知您的 AI 客户端有关 MCP 服务器。服务器将启动，但您的 AI 客户端不会连接到它。在客户端运行一次安装命令：
```sh
hivemind mcp install claude # Claude Code
hivemind mcp install cursor # Cursor
hivemind mcp install windsurf # Windsurf
hivemind mcp install opencode # OpenCode
hivemind mcp install kimi # Kimi Code CLI
hivemind mcp install codex # OpenAI Codex CLI
```
这只需在每台机器上执行一次，不需要每个项目。
**HiveMind 如何检测客户端是否已注册：
| 客户端 | 检测方法 |
|--------|-----------------|
| Claude Code | 运行 `claude mcp list` 并检查 "hivemind" |
| Cursor | 读取 `~/.cursor/mcp.json`，检查 "hivemind" |
| Windsurf | 读取 `~/.codeium/windsurf/mcp_config.json`，检查 "hivemind" |
| Kimi | 读取 `~/.kimi/mcp.json`，检查 "hivemind" |
| OpenCode | 读取 `~/.config/opencode/opencode.json`（或 `$XDG_CONFIG_HOME`），检查 "hivemind" |
| Codex CLI | 读取 `~/.codex/config.toml`，检查 `[mcp_servers.hivemind"`
检测失败是沉默的：缺少配置文件或不可用的 CLI 只是意味着“未注册”。如果您已手动注册客户端，请验证“hivemind”是否出现在上述路径的配置文件中。
### Claude 连接但会话启动失败
如果 `hivemind_session_start` 在会话期间出错，最可能的原因是服务器未运行。检查：
```sh
hivemind service status # 如果已作为服务安装
# 或
hivemind up # 手动启动
```
### 会话启动成功但未注入任何内存
`hivemind_session_start` 仅加载 `.hivemind.toml` 中 `[hooks.on_session_start].recalls` 列出的条目。如果该列表为空或没有条目与数据库中的标题匹配，则不会注入任何内容。检查：
```sh
hivemind status # 预览将注入的内容
```
---
## 常见问题
**HiveMind 是否会将内存注入我发送的每个提示中？**
不。内存仅在 Claude 调用 `hivemind_session_start` 时注入到会话开始时。之后，加载的内存是对话上下文的一部分，但每次提示都会额外添加内容；像 `.claude/settings.json` 中的 `UserPromptSubmit` 钩子这样的工具会在每个消息上运行；HiveMind 不会。
**HiveMind 会话启动与 Claude Code 的 `UserPromptSubmit` 钩子有什么区别？**
`UserPromptSubmit` 钩子运行 shell 命令，并将输出附加到您发送的每个消息上，无条件、无令牌预算限制。HiveMind 只运行一次会话启动，尊重 `max_tokens` 限制，并让您控制每个项目加载哪些内存。参见 [比较表](#how-hivemind-differs-from-claude-codes-built-in-hooks) 以获取完整分析。
**我可以获取 `recalls` 中未列出的内存吗？**
是的。`recalls` 仅是会话启动时的自动注入列表。数据库中的每个内存都可在任何时候按需访问。询问 Claude 通过标题或 ID 回忆它 (`memory_recall`)，或通过关键词搜索 (`memory_search`)。没有任何内容被隐藏或无法访问。
**Claude 会自动存储内存吗？**
不。HiveMind 永远不会自动存储。Claude 仅在您明确要求它时才会写入内存，例如 *"记住这个"* 或 *"存储此偏好"*。这使存储库保持有意图且无噪音。
**如果内存不适合 `max_tokens`，会发生什么？**
它将被跳过。HiveMind 按顺序加载回忆；如果某个条目会超出预算，则跳过该条目，继续下一个条目；稍后较小的条目仍可能合适。跳过的条目将在结果中报告。使用 `hivemind status` 预览将加载的内容以及每个内容消耗的令牌数，然后再打开会话。
**我可以为不同的项目设置不同的回忆吗？**
是的。每个项目都有自己的 `.hivemind.toml`，具有自己的 `recalls` 列表和 `max_tokens`。您的个人添加内容位于 `.hivemind.local.toml`（gitignored）中，与项目配置叠加。
**我的队友能看到我的个人记忆吗？**
不。标记为“personal”的记忆随您而去，不随仓库。仅标记为“workspace”的记忆是项目范围的。`.hivemind.local.toml` 文件被 gitignored，您个人的层级仅在您自己的机器上本地，除非您配置同步。
**MCP 连接是否经过身份验证？**
MCP 端点 (`/mcp`) 和 REST API (`/api/v1/*`) 默认绑定到 `127.0.0.1`，因此仅限本地进程访问。无需身份验证。
**如果服务器未运行，会发生什么？**
如果在 Claude 调用 `hivemind_session_start` 时 `hivemind up` 未运行，MCP 调用将失败。Claude 通常会注意到这一点，并继续在没有内存上下文的情况下进行会话。您的工作不会受到阻碍，但您不会获得该会话的注入内存。
**我可以使用 HiveMind 来支持 Claude Code 以外的代理吗？**
是的，只要该代理支持 HTTP 上的 MCP（流式 HTTP 传输）。REST API 也完全可访问，用于自定义集成。
**数据库存储在哪里？**
默认为 `~/.hivemind/memories.db`。可通过 `HIVEMIND_DB_PATH` 环境变量覆盖。它是一个纯 SQLite 文件；您可以备份、复制或直接检查它。
---
## 与 HiveMind 集成
有关将您的应用、脚本或 AI 代理连接到 HiveMind 的 MCP 工具和 REST API 的详细文档：[docs/INTEGRATING.md](docs/INTEGRATING.md)
---
## 许可证
AGPL-3.0-only
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器