内容
# Hebbrix MCP 服务器
<!-- mcp-name: io.github.Hebbrix/hebbrix-mcp -->
[](https://pypi.org/project/hebbrix-mcp/)
[](https://github.com/Hebbrix/hebbrix-mcp/actions/workflows/ci.yml)
[](https://pypi.org/project/hebbrix-mcp/)
[](LICENSE)
一款为任意AI代理提供长期记忆和时间知识图谱的模型上下文协议（MCP）服务器，由 [Hebbrix](https://www.hebbrix.com) 支持。
您的代理在会话结束时忘记所有内容。这解决了这个问题，并超越了简单的记忆存储：
- **记忆** — 存储、搜索、纠正和版本化记忆，跨越会话
- **知识图谱** — 实体、关系、时间线和“在时间X时什么为真”
- **推理** — 询问代理在行动前应该有多自信，并记录结果以便改进
与Claude Desktop、Claude Code、Cursor、Cline、Continue等任何其他MCP客户端兼容。
## 快速开始（无需账号）
在MCP客户端配置文件中添加以下内容。首次运行无API密钥时，服务器会自动创建一个**免费代理账号**（无需电子邮件，无仪表盘，约1秒），并将其保存到 `~/.hebbrix/config.json`。
```json
{
"mcpServers": {
"hebbrix": { "command": "uvx", "args": ["hebbrix-mcp"] }
}
}
```
> [!NOTE]
> `uvx` ([来自uv](https://docs.astral.sh/uv/)) 在无需安装步骤的情况下运行服务器。如果您更喜欢，可以使用 `pip install hebbrix-mcp` 并使用 `"command": "hebbrix-mcp"` 代替。
重启客户端。完成 — 您的代理现在具有持久记忆。
免费代理账号包括 **300次学习事件** 和 **2,000次检索**，如果未认领，则在最后一次使用后14天后过期。每个工具结果都带有 `hebbrix_usage` 块，以便代理始终了解其状态，并在需要认领时通知您。
**永久保留**（相同密钥，所有记忆均转移，解锁免费月度套餐）：
```bash
uvx hebbrix-mcp claim --email you@example.com
```
## Claude Code 插件（推荐）
作为Claude Code **插件** 安装，Claude启动每个会话时已经了解您 — `SessionStart` 钩子自动加载您编译的Hebbrix配置文件到上下文中，并且一步完成记忆工具的连接：
```bash
/plugin marketplace add Hebbrix/hebbrix-mcp
/plugin install hebbrix@hebbrix
```
就是这样。不需要账户（代理模式会在第一次运行创建账户）；在插件配置中设置您的 `api_key` 以使用您自己的账户。钩子会平稳降级 — 全新配置文件只显示 `(none yet)`，直到您保存了一些事实，并且它永远不会阻止会话。
## 配置
在 [hebbrix.com/dashboard/api-keys](https://www.hebbrix.com/dashboard/api-keys) 获取API密钥，以使用您自己的账户代替代理模式。
<details>
<summary><b>Claude Desktop</b> — <code>~/Library/Application Support/Claude/claude_desktop_config.json</code></summary>
```json
{
"mcpServers": {
"hebbrix": {
"command": "uvx",
"args": ["hebbrix-mcp"],
"env": {
"HEBBRIX_API_KEY": "mem_sk_...",
"HEBBRIX_COLLECTION_ID": "your-default-collection-uuid"
}
}
}
}
```
</details>
<details>
<summary><b>Claude Code</b></summary>
```bash
claude mcp add hebbrix -- uvx hebbrix-mcp
```
</details>
<details>
<summary><b>Cursor</b> — <code>~/.cursor/mcp.json</code></summary>
```json
{
"mcpServers": {
"hebbrix": { "command": "uvx", "args": ["hebbrix-mcp"] }
}
}
```
</details>
<details>
<summary><b>Cline / Continue / other</b></summary>
将您的MCP服务器配置指向 `uvx hebbrix-mcp` 命令（stdio）。形状与上述相同。在 `env` 中设置 `HEBBRIX_API_KEY` 以跳过代理模式。
</details>
环境变量始终优先于保存的代理模式凭证。
### 环境变量
所有变量均为可选。未设置任何变量时，服务器以代理模式启动。
| 变量 | 默认值 | 用途 |
|---|---|---|
| `HEBBRIX_API_KEY` | *(代理模式创建)* | 您的Hebbrix bearer令牌 |
| `HEBBRIX_COLLECTION_ID` | *(代理模式设置)* | 默认写入/读取集合 |
| `HEBBRIX_API_BASE` | `https://api.hebbrix.com/v1` | API端点覆盖 |
| `HEBBRIX_CONFIG` | `~/.hebbrix/config.json` | 代理模式凭证保存位置 |
| `HEBBRIX_MCP_HOST` | `127.0.0.1` | 绑定主机（HTTP传输） |
| `HEBBRIX_MCP_PORT` | `8080` | 绑定端口（HTTP传输） |
| `HEBBRIX_MCP_MULTI_TENANT` | 关闭 | 主机模式：每个请求的`Authorization`头部认证 |
## 可用工具
服务器级指令块教导模型何时调用每个工具，因此行为良好的代理在回答前会搜索并记住重要的内容。
**记忆**
- `hebbrix_remember` - 存储事实、决定或偏好。
- `content` （字符串，必填）：记忆文本
- `tags` （列表，可选），`collection_id` （字符串，可选）
- `extract` （布尔，默认为假）：假则精确存储文本（一个记忆）；真则运行事实提取，可能创建多个原子记忆
- `wait_for_index` （布尔，默认为真）：调用返回时可搜索
- `hebbrix_search` - 语义搜索（混合向量 + BM25 + 图谱检索）。
- `query` （字符串，必填），`limit` （整数，可选），`collection_id` （字符串，可选）
- `hebbrix_get` - 按ID获取一个记忆，附带元数据。
- `hebbrix_update` - **原位**纠正一个记忆（保留旧版本）。
- `hebbrix_forget` - 按ID删除一个记忆。
- `hebbrix_list` - 列出最近的记忆。
- `hebbrix_history` - 查看记忆随时间的变化。
**知识图谱** — Hebbrix自动从您编写的记忆中提取实体和关系，**所有层级，包括代理模式**，因此所有图谱 *读取* 操作（实体、时间线、遍历、矛盾）都在代理模式下工作。只有显式图谱 *写入* /推理操作需要付费套餐。
- `hebbrix_search_entities` - 列出已知实体（人、组织、工具、地点）。
- `hebbrix_entity_timeline` - 一个实体在何时处于什么状态。
- `hebbrix_graph_query` - 从命名实体遍历关系；传递 `timestamp` 获取某一时刻的真实情况。（自由文本问题：使用 `hebbrix_search`。）
- `hebbrix_contradictions` - 找出相互冲突的事实。
**推理和账户**
- `hebbrix_confidence` - 代理在行动前应该有多自信？基于记忆 + 过去结果。
- `hebbrix_log_decision` - 记录一个决定及其结果；为未来的自信度提供数据。 `hebbrix_confidence` 检查后，可以只记录 `outcome` — 描述会自动填充您的问题。
- `hebbrix_list_collections` - 列出密钥可以使用的记忆空间。
- `hebbrix_account_status` - 套餐、用量、限制和到期日。
服务器还公开了一个 `hebbrix://profile` 资源和一个 `context` 提示，注入用户的编译配置文件。
## 使Hebbrix成为代理的记忆
服务器自带一个指令块，告诉模型使用Hebbrix作为其“记住”的单一真实来源。但一些主机（尤其是Claude Code）有自己的基于文件的记忆，其指令位于系统提示级别，可以优先于MCP服务器的指令 — 因此代理可能会悄悄地将笔记写入本地文件而不是Hebbrix。
可靠的解决方法是在您的项目的 `CLAUDE.md` （或助手的系统提示/规则文件）中添加一行：
```markdown
## 记忆
使用Hebbrix MCP服务器作为长期记忆的单一真实来源。
当您需要记住、记录或保存任何持久的信息时，请调用 `hebbrix_remember`
（和 `hebbrix_search` 来回忆）。不要将记忆写入本地文件或主机内置记忆。
```
Cursor用户：在 `.cursorrules` 中添加相同的内容。这将优先级放在主机尊重的级别上，因此Hebbrix始终一致。
## 运行模式
**本地（默认）— stdio.** 快速启动执行的操作：每个客户端一个进程。
**自托管HTTP — 一个实例，您的机器：**
```bash
HEBBRIX_API_KEY=mem_sk_... uvx hebbrix-mcp --transport streamable-http
# 服务于 http://127.0.0.1:8080/mcp
```
**托管 — 无需运行。** 任意支持HTTP的MCP客户端都可以访问官方托管端点，并使用您自己的密钥（在 [hebbrix.com/dashboard/api-keys](https://www.hebbrix.com/dashboard/api-keys) 获取）进行身份验证：
```json
{ "mcpServers": { "hebbrix": {
"url": "https://mcp.hebbrix.com/mcp",
"headers": { "Authorization": "Bearer mem_sk_..." }
}}}
```
**自托管多租户 — 一个实例，多用户。** 形状与您自己的基础设施相同。服务器不持有密钥；每个请求都使用自己的 `Authorization` 头部进行身份验证：
```bash
HEBBRIX_MCP_MULTI_TENANT=1 HEBBRIX_MCP_HOST=0.0.0.0 uvx hebbrix-mcp --transport streamable-http
```
或运行容器（默认多租户，`GET /healthz` 用于负载均衡器探测）：
```bash
docker build -t hebbrix-mcp . && docker run -p 8080:8080 hebbrix-mcp
```
在多租户模式下，没有默认集合 — 在工具调用时传递 `collection_id`。
## 工作原理
```
┌──────────────────┐ MCP（stdio或HTTP） ┌─────────────┐ HTTPS ┌──────────┐
│ Claude / Cursor / │ ───────────────────────→│ hebbrix-mcp │─────────────→│ Hebbrix │
│ Cline / 任意代理 │ 工具调用 │ （此） │ REST API │ 云端 │
└──────────────────┘ └─────────────┘ └──────────┘
```
此软件包**不拥有任何状态**。工具调用变为针对您的Hebbrix账户的REST调用；记忆、嵌入、知识图谱和检索都存储在Hebbrix后端。删除此软件包后，您的记忆仍然存在。
代理模式账户在任务中途不会中断：当达到限制时，您会收到一个结构化错误，带有 `resolve` 字段，而不是失败。写入在读取之前停止；读取继续工作；账户在过期前变为只读。
## 调试
使用 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 检查服务器：
```bash
npx @modelcontextprotocol/inspector uvx hebbrix-mcp
```
常见问题：
- **每次调用都返回 `HTTP 401`** — 密钥错误或已撤销。取消设置 `HEBBRIX_API_KEY`，删除 `~/.hebbrix/config.json`，然后重启以重新配置，或粘贴来自仪表盘的新密钥。
- **代理模式无法启动（`auto-signup unavailable`）** — 注册可能达到每日容量或您的网络阻止API。请设置 `HEBBRIX_API_KEY` 代替。
- **`claim` 显示 `EMAIL_IN_USE`** — 认领需要一个没有现有Hebbrix账户的电子邮件。使用一个新鲜的地址（`you+agent@gmail.com` 别名有效）。
- **一个记忆不能立即搜索** — 索引是异步的；典型的收敛时间小于30秒。
## 开发
```bash
git clone https://github.com/Hebbrix/hebbrix-mcp
cd hebbrix-mcp
./quick_setup.sh # venv + 可编辑安装
source venv/bin/activate
pytest tests/ -q # 55个离线测试，无需网络
hebbrix-mcp # 在stdio上启动代理模式
```
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [CHANGELOG.md](CHANGELOG.md)。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
## 链接
- [Hebbrix 文档](https://www.hebbrix.com/docs)
- [MCP 集成指南](https://www.hebbrix.com/integrations/mcp)
- [模型上下文协议](https://modelcontextprotocol.io)
