HermesClawZero-ConfigSidecar

    # HermesClaw 零配置边车 **基于 PostgreSQL 的长期记忆，适用于 Hermes 和 OpenClaw — 带有实时仪表盘。** --- ## 📋 目录 - [一键安装](#-一键安装) - [仪表盘](#-仪表盘--你的记忆中心) - [记忆星系](#-记忆星系) - [CLI 和 MCP 工具](#-cli--mcp-工具) - [内部](#-内部) - [提供商和配置](#-提供商和配置) - [验证它是否有效](#-验证它是否有效) - [截图](#-截图) - [适用人群](#-适用人群) --- ## 🤖 一键安装 将以下内容粘贴到 **Hermes**、**OpenClaw** 或任何 AI 代理中： ```text 从 GitHub 安装该项目： https://github.com/SunMe1977/HermesClawZero-ConfigSidecar ``` > **⬆️ 代理克隆、配置并启动所有内容。** 无需手动步骤。 > 大约 30 秒后，打开 → [`http://localhost:8010/dashboard`](http://localhost:8010/dashboard) > > 📄 查看 [`install_via_agent.md`](install_via_agent.md) 以获取详细的代理说明。 **手动启动**（如果您没有代理）： ```bash git clone https://github.com/SunMe1977/HermesClawZero-ConfigSidecar.git cd HermesClawZero-ConfigSidecar setup.bat # Windows （或：./setup.sh 在 Linux 上） start.bat # Windows （或：./start.sh 在 Linux 上） ``` --- ## 📊 仪表盘 — 你的记忆中心 **仪表盘** 是您的代理记住的所有内容的 main 入口： | 功能 | 你可以做的 | |---------|----------------| | **记忆时间线** | 按时间顺序浏览所有捕获的记忆 | | **语义搜索** | 按含义查找记忆，而不是关键词 | | **租户隔离** | 每个范围/聊天都有自己的视图 — 无数据泄漏 | | **记忆健康** | 查看过期/低置信度的记忆，运行优化器 | | **记忆星系** | 所有记忆的交互式 3D 星系可视化 | | **导出** | 随时下载记忆快照 |  --- ## 🌌 记忆星系 一个全屏 **基于 Canvas 的星系可视化** ，让你的记忆栩栩如生： | 功能 | 效果 | |---------|--------| | **租户轨道** | 每个范围/用户都有自己的彩色轨道环 | | **发光节点** | 脉动记忆点，带有彗星般的发光轨迹 | | **星云着色器** | 动画气体云（蓝色/紫色/粉色）带有深度 | | **视差深度** | 前景节点比背景星星反应更快 | | **悬停卡片** | 悬停任意节点以查看租户、时间戳和标签 | | **缩放和旋转** | 鼠标滚轮缩放（0.3 倍 – 3 倍），空闲 5 秒后自动旋转 | | **记忆集群** | 附近租户轨道漂移的漫散发光团 | 在仪表盘标题中将其打开 — 无需安装，无需额外设置。 --- ## 🧠 它做什么 | 问题 | 没有边车 | 有边车 | |---------|----------------|--------------| | 会话连续性 | 代理重启时忘记所有内容 | 记住事实、偏好、决定 | | 上下文成本 | 长历史记录会燃烧代币 | 语义搜索找到 *相关* 记忆 | | 设置工作量 | 手动矢量数据库、嵌入、API 密钥 | Docker + Ollama，零配置，零成本 | **工作流：** `用户 ↔ 代理 ↔ 边车 API ↔ PostgreSQL + pgvector` --- ## 🔧 CLI 和 MCP 工具 ### CLI（Python） ```bash python memory.py capture "要记住的事实" # 保存记忆 python memory.py search "查询" 5 # 搜索记忆 python memory.py autosave "文本" "backup.md" # 备份会话 ``` ### MCP 服务器（6 个工具） 适用于 Claude Desktop、Hermes、VS Code 和任何 MCP 客户端： ```bash pip install mcp requests python mcp_server.py ``` | 工具 | 描述 | |------|-------------| | `capture_memory` / `search_memory` | 读取和写入记忆 | | `list_recent` / `memory_stats` | 浏览和分析 | | `delete_memory` / `review_memories` | 管理和合成 | **与 Hermes 注册：** `hermes mcp add hermesclawzero --command "python C:\dev\HermesClawZero-ConfigSidecar\mcp_server.py"` ### 代理技能 两个预建的技能将边车与您的代理集成： - [**Hermes 技能**](hermes-skill/README.md) — 确定性捕获触发器 + 自动加载 Hermes - [**OpenClaw 自动记忆技能**](openclaw-auto-memory-skill/README.md) — 自动捕获事实、偏好和项目上下文 --- ## 📦 内部 | 容器 | 端口 | 角色 | |-----------|------|------| | `hermesclawzero-configsidecar-api-1` | `:8010` | FastAPI + 仪表盘 + 捕获/搜索 | | `gbrain-postgres` | `:5666` | PostgreSQL 16 + pgvector | | `gbrain-ollama` | `:11435` | Ollama（nomic-embed-text） | **健康检查：** `curl http://localhost:8010/healthz` → `{"status":"ok"}` --- ## ⚙️ 提供商和配置 <details> <summary>点击展开</summary> ### 提供商支持 | 模式 | `AI_PROVIDER` | 嵌入 | 密钥必填 | |------|---------------|------------|-------------| | **本地（推荐）** | `ollama` | `nomic-embed-text` | 无 | | OpenAI | `openai` | OpenAI | `OPENAI_API_KEY` | | Gemini | `gemini` | Gemini | `GEMINI_API_KEY` | | Anthropic | `anthropic` | 通过嵌入提供商 | `ANTHROPIC_API_KEY` | | OpenRouter | `openrouter` | OpenRouter | `OPENROUTER_API_KEY` | ### Compose 提供商覆盖 ```bash COMPOSE_AI_PROVIDER=openrouter docker compose up -d --force-recreate api ``` ### 环境变量 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `API_KEY` | — | 所有受保护端点的必填项 | | `DB_PASSWORD` | — | PostgreSQL 密码 | | `AI_PROVIDER` | `ollama` | `ollama` \| `openai` \| `gemini` \| `anthropic` \| `openrouter` | | `MEM_PUBLIC_URL` | `http://localhost:8010` | 客户端脚本的基本 URL | | `OLLAMA_HOST` | `http://host.docker.internal:11434` | Ollama 端点 | | `AUTO_UPDATE_ENABLED` | `false` | 自动从 GitHub 拉取 | | `DASHBOARD_PASSWORD` | `HermesDash!2026` | 仪表盘的基本身份验证 | ### 安全 - 通过 `chat_id` + `scope_id` 实现多租户隔离 - API：`x-api-key` 头或 `?key=` 查询参数 - 仪表盘：基本身份验证 - 速率限制：30 req/min `/capture`，60 req/min `/search` </details> --- ## ✅ 验证它是否有效 ```bash # 1. 健康检查 curl http://localhost:8010/healthz # → {"status":"ok"} # 2. 捕获测试记忆 python memory.py capture "Hello from README" test # 3. 搜索它 python memory.py search "hello" 3 # 4. 打开仪表盘 # → http://localhost:8010/dashboard ``` > 🔍 有问题吗？查看 [OpenClaw 技能中的故障排除部分](openclaw-auto-memory-skill/README.md#troubleshooting)。 --- ## 🖼️ 截图   *在 `docker compose up` 后立即在 [`http://localhost:8010/dashboard`](http://localhost:8010/dashboard) 上可用。* --- ## 🤝 适用人群 AI 开发人员 · Hermes 用户 · OpenClaw 用户 · 自托管者 · MCP 爱好者 --- ## 🏆 与生态系统比较 HermesClawZero 是 **唯一一个** 在单个 Docker 堆栈中结合所有这些功能的内存系统： | 需要 | gBrain | ZeroMem | Hermes 内置 | OpenClaw 内存 | Cognee | **HermesClawZero** | |---|---|---|---|---|---|---| | **知识图谱** | ⚠️ 自我连接 | ❌ | ❌ | ❌ | ✅ | ✅ **实体 + 关系 + 遍历** | | **内存层级** | ❌ | ❌ | ⚠️ 3 层 | ❌ | ❌ | ✅ **热/暖/标准/冷** | | **版本控制** | ❌ | ✅ DAG | ❌ | ❌ | ❌ | ✅ **memory_versions 表** | | **压缩** | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ **智能多行** | | **合并** | ✅ 梦循环 | ❌ | ❌ | ✅ 梦游 | ❌ | ✅ **嵌入聚类** | | **重复数据删除** | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ **矢量距离** | | **编辑器/合并** | ❌ | ✅ DAG | ❌ | ❌ | ❌ | ✅ **内联 + 批量合并** | | **反馈** | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ **投票/反对** | | **时间搜索** | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ **days_back 过滤器** | | **记忆提示** | ❌ | ❌ | ✅ 定期 | ❌ | ❌ | ✅ **/nudge 端点** | | **自动导入** | ❌ | ❌ | n/a | ❌ | ❌ | ✅ **Hermes state.db** | | **自动同步** | ❌ | ❌ | n/a | ❌ | ❌ | ✅ **5 分钟守护进程** | | **仪表盘（UI）** | ❌ | ❌ | ✅ 桌面端 | ❌ | ❌ | ✅ **记忆星系 + 健康** | | **图 UI** | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ **仪表盘中的实体浏览器** | | **MCP 工具** | 30+ | ❌ | 内置 | ❌ | ❌ | **6 个工具** | | **API 密钥** | 需要 OpenAI | ❌ | **无** | ❌ | 需要 LLM 密钥 | **✅ 无（Ollama）** | | **安装** | `npx gbrain` | 复杂 | 内置 | 插件 | `pip install` | **🤖 通过代理一键安装** | ### 为什么切换？ > **您可以在单个 `docker compose up` 中获得所有这些：** > — PostgreSQL + pgvector + HNSW 索引 — 不是 SQLite，不是文件 > — 知识图谱，带有实体提取 + 图遍历 — 不只是矢量搜索 > — 内存层级 + 版本控制 + 压缩 — 没有其他系统具有所有三个 > — 一个完整的动画仪表盘，带有星系视图、健康面板和交互式工具 > — 零 API 密钥，零云，零数据离开您的机器 > — 一键安装：将 GitHub URL 粘贴到任何 Hermes 或 OpenClaw 代理中 --- ## 🙌 欢迎贡献 欢迎各种形式的贡献 — 请随意打开 [PR](https://github.com/SunMe1977/HermesClawZero-ConfigSidecar/pulls) 或 [问题](https://github.com/SunMe1977/HermesClawZero-ConfigSidecar/issues)。 查看 [`CONTRIBUTING.md`](CONTRIBUTING.md) 以获取代码样式、提交约定和 PR 工作流程。 --- 为 AI 代理自主性而构建。 --- <p align="center"> <em> 如果您喜欢这个项目，请考虑分享您的经验 — 一个短视频评论、一条推文或一个 TikTok 帖子有助于他人发现它。 </em> </p> --- <a href="https://github.com/nousresearch/hermes-agent"><img src="https://cdn.jsdelivr.net/gh/selfhst/icons/png/hermes-agent.png" alt="Hermes Agent" width="15%"></a> <a href="https://github.com/openclaw/openclaw"><img src="https://openclaw.ai/logo.png" alt="OpenClaw" width="30%"></a> <a href="https://ollama.com/"><img src="https://ollama.com/public/ollama.png" alt="Ollama" width="15%"></a> - [Hermes Agent GitHub](https://github.com/nousresearch/hermes-agent) - [OpenClaw 网站](https://openclaw.ai) - [Ollama 网站](https://ollama.com)