内容
# Hexus
[](https://github.com/codenamekt/hexus/actions/workflows/ci.yml) [](https://badge.fury.io/py/hexus)
### 基于 Postgres 的矢量内存，适用于智能代理时代
**Postgres + hexus 内存基质，适用于 [hermes-agent](https://github.com/NousResearch/hermes-agent) 和独立的模型上下文协议（MCP）服务器，适用于任何客户端（Claude Desktop、Cursor、fleet 代理等）。**
```mermaid
graph TD
classDef default fill:#1f2937,stroke:#374151,stroke-width:1px,color:#f3f4f6;
classDef highlight fill:#3b82f6,stroke:#1d4ed8,stroke-width:2px,color:#ffffff;
classDef db fill:#059669,stroke:#047857,stroke-width:2px,color:#ffffff;
subgraph 客户端 ["集成客户端"]
Minions["Hermes 代理小兵<br/>(Header: X-Hermes-Session-Key)"]
Claude["Claude Desktop<br/>(stdio MCP)"]
Cursor["Cursor 编辑器<br/>(stdio MCP)"]
Custom["自定义代理<br/>(HTTP MCP)"]
end
subgraph Hexus ["Hexus（单进程，共享嵌入）"]
Plugin["Hermes 插件<br/>(hexus/__init__.py)"]
Server["MCP 服务器<br/>(mcp_server)"]
Embedder["本地 BertEmbedder<br/>(MiniLM-L6-v2)"]:::highlight
Store["内存存储<br/>(psycopg 池)"]
end
DB[("PostgreSQL 16 + pgvector<br/>(memory_entries & conversations)")]:::db
%% 连接
Minions -->|X-Hermes-Session-Key| Plugin
Claude -->|stdio| Server
Cursor -->|stdio| Server
Custom -->|HTTP| Server
Plugin --> Embedder
Server --> Embedder
Plugin --> Store
Server --> Store
Store --> DB
```
---
## 🚨 “内存危机”（以及 Hexus 为何出色 🎸）
如果你曾经尝试过运行一组协作代理，你可能会遇到以下障碍。Hexus 就是为了解决这些问题而存在的，它可以改变游戏规则：
* **不再受限于本地标记文件 🐘**：告别多个代理运行时会被覆盖的本地标记文件。Hexus 为每个小兵提供了一个干净、独立的内存空间（“主题”）。您的营销代理的笔记不会污染您的交易代理的数据！
* **纯矢量速度（热点路径中无 LLM！） ⚡**：嵌入式搜索应该纯粹是矢量数学！我们使用纯粹的本地 BERT 模型。零云调用，热点路径中零 LLM，绝对隐私，*以及* 更快的性能。
* **抛弃云巨头 ☁️**：其他内存提供商需要付费云服务，并通过 LLM 路由每个读/写操作。而我们不是。Hexus 使用您现有的 Postgres + `pgvector`。保持简单，保持快速！
* **存储层和内存模型 📦**：Hexus 既是坚实的存储基础，又是智能内存模型，适用于一组协作代理，保持所有内容集中、可搜索和干净。
* **独立插件能力 🧩**：为什么要独立插件？这样您就可以直接安装并运行！无需等待主存储库中的上游 PR。
## 🌪️ 入门指南（安装非常简单！）
准备好试用了吗？您可以立即开始。
### 选项 1：Hermes 插件（通过 pip）
如果您直接集成到 Hermes 代理中，可以从 pip 获取：
```bash
pip install hexus
```
*注意：安装完成后，只需将 Hermes 指向它！您也可以直接将 `hexus` 模块文件放入 `~/.hermes/plugins/hexus/` 目录中。Hermes 的发现系统将自动检测并在启动时初始化它！*
### 选项 2：Docker 和 MCP 服务器（Claude、Cursor 等）
运行独立 MCP 服务器的最简单方法是使用 Docker（GHCR）。
> **注意：** Docker MCP 服务器需要一个运行中的 PostgreSQL 数据库，并启用 `pgvector`。您可以参考或使用我们提供的 `docker/compose.yml` 文件作为快速示例来启动！
```bash
# 在端口 8000 上通过 HTTP 流传输运行 MCP 服务器
docker run -d --name hexus -p 8000:8000 ghcr.io/codenamekt/hexus:latest
```
**与 Claude Code / Claude Desktop 一起使用：**
如果您想通过标准 `stdio` 将 Hexus 直接插入到您的 Claude `claude_desktop_config.json` 中，您可以添加此块以无缝运行后台 Docker 镜像：
```jsonc
{
"mcpServers": {
"hexus": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"HEXUS_DSN=dbname=hermes_memory user=postgres host=host.docker.internal",
"ghcr.io/codenamekt/hexus:latest",
"hexus-mcp",
"serve",
"--transport",
"stdio"
]
}
}
}
```
## 🏎️ 看看！令人印象深刻的基准测试
我们相信速度。查看这些在基本 CPU 上运行的实际基准测试（无需 GPU！）：
* **单次嵌入延迟**：`7.4 ms`
* **批量嵌入吞吐量**：`1,486 items/sec` （批量大小 32）
* **召回延迟（前 5 名）**：`2.0 ms`
想自己运行这些测试吗？查看完整的 [BENCHMARK.md](docs/BENCHMARK.md) 了解如何操作！
## ✨ 等一下，还有更多！（功能）
* **两条集成路径，一个共享存储**：将其用作 Hermes 插件，或作为 Claude Desktop、Cursor 和自定义代理的独立模型上下文协议（MCP）服务器。
* **内置增强功能**：混合搜索（BM25 + 矢量），时间衰减，TTL/内存遗忘，实体标记和对话摘要。
* **适合任何设备**：完全在 CPU 上本地运行（例如旧的 Intel NUC 或迷你 PC）。
## 🕳️ 深入了解
想了解更多详细信息吗？我们将技术细节转移到它们自己的文档中，以便您直接进入代码：
* 📖 [技术细节和配置](docs/TECHNICAL_DETAILS.md) - 管理员 DB 命令，模式，钩子和 MCP 配置。
* 🗺️ [路线图](docs/ROADMAP.md) - 查看我们已经完成的内容和即将推出的功能。
* 🔙 [回滚指南](docs/ROLLBACK.md) - 以防您改变主意（但您不会！）。
---
*License: [BSD 3-Clause](LICENSE)*
