项目定位与目标

hebbrix-mcp 是一个基于 Model Context Protocol（MCP）的服务端实现，作为外部工具与 AI 助手之间的桥梁，专注于向 LLM 暴露结构化的记忆与检索能力。该项目以 Python 包形式发布，最新稳定版本为 v0.3.20，主题为 hebbrix_import + usage on material change (E2E review)，反映了社区近期关注的端到端审阅与导入流程改进。资料来源：README.md:1-40

项目的核心目标是为 LLM 提供以下能力：

• 记忆持久化：跨会话保存知识条目与索引
• GraphRAG 检索：基于图谱的上下文问答（hebbrix_ask）
• 置信度报告：在出现约束冲突时输出 do_not_act 信号
• 批量操作与导出：支持知识库的批处理、导出与 mark_used 流程

资料来源：hebbrix_mcp/__init__.py:1-30

包结构与依赖

资料来源：pyproject.toml:1-40

安装方式

通过 pip 安装

pip install hebbrix-mcp

该命令会从 PyPI 拉取最新稳定版本（v0.3.20），并自动安装所需依赖。资料来源：pyproject.toml:10-30

作为 Claude 插件安装

仓库同时提供 .claude-plugin/ 目录下的清单文件，可通过 Claude 插件市场加载：

/plugin install hebbrix-mcp

插件清单文件定义了名称、版本、入口命令及描述信息： 资料来源：.claude-plugin/plugin.json:1-20

市场清单中描述项目为一个轻量级 MCP 服务，提供记忆管理、GraphRAG 检索与置信度评估。资料来源：.claude-plugin/marketplace.json:1-20

配置与启动

MCP 客户端（如 Claude Desktop）需要在配置文件中声明 hebbrix-mcp 服务端：

{
  "mcpServers": {
    "hebbrix": {
      "command": "python",
      "args": ["-m", "hebbrix_mcp"],
      "env": {
        "HEBBRIX_API_KEY": "<your-api-key>"
      }
    }
  }
}

启动入口位于 hebbrix_mcp/__init__.py，注册所有可被 LLM 调用的工具与资源。资料来源：hebbrix_mcp/__init__.py:20-50

版本演进与社区关注点

自 v0.3.11 起，社区持续关注以下议题：

• 缓存诚实性：v0.3.17 提出 search cache 必须避免覆盖层凌驾真实命中之上
• WAF 阻断澄清：v0.3.18 增强了 prompt-injection 防护与 WAF-block 的输出清晰度
• GraphRAG 增强：v0.3.16 引入 hebbrix_ask，并加入批量操作与 mark_used
• 置信度冲突：v0.3.15 在 hebbrix_confidence 中暴露 do_not_act 状态
• E2E 导入：v0.3.20 在 hebbrix_import 中加入 material change 时的 usage 更新

适用场景

hebbrix-mcp 适合以下使用情境：

1. 需要为 LLM 提供长期记忆而不想全量重传上下文的场景
2. 在企业知识库中希望使用图谱检索提升问答质量
3. 需要对 AI 输出进行置信度评估并标记不确定结论
4. 在对话过程中希望对检索结果进行反馈（mark_used）以优化后续检索

建议初次使用者从 hebbrix_import 开始导入首批知识条目，随后使用 hebbrix_ask 验证 GraphRAG 路径，并最终通过 hebbrix_confidence 检查是否存在约束冲突。

概述与定位

hebbrix-mcp 是一个基于 Model Context Protocol 的服务器实现，向 LLM 代理暴露一组用于"持久化记忆"与"知识图谱构建"的工具 (Tools)。这些工具围绕 hebbrix_* 命令族展开，使代理能够把对话事实写入长期存储，从图谱中检索实体关系，并对结果进行可信度评估。

资料来源：README.md:1-40

项目将"记忆"与"知识图谱"统一在同一后端：每条记忆既是一段文本，也是图谱中的节点或边的来源。server.py 通过 @server.list_tools() 与 @server.call_tool() 注册全部工具入口，遵循 MCP 标准以 JSON Schema 描述输入参数。

资料来源：hebbrix_mcp/server.py:1-80

核心工具家族

hebbrix_ask —— GraphRAG 入口

hebbrix_ask 是图谱驱动的检索增强问答工具，引入于 v0.3.16。它接受自然语言问题，先在图谱上执行实体解析与关系扩展，再把命中的子图与文本片段一起送入生成阶段。

资料来源：CHANGELOG.md:1-40

伴随 hebbrix_ask 一同加入的还有批量能力 (batch)、导出 (export) 以及使用标记 (mark_used)，用于让代理在多次检索中维护会话级的引用状态。

资料来源：CHANGELOG.md:v0.3.16 行

hebbrix_import —— 数据导入

hebbrix_import 在 v0.3.20 中正式引入，专门处理"材料级变更 (material change)"下的端到端导入流程：解析外部文档、抽取实体与关系、写入图谱、并刷新搜索索引。

资料来源：CHANGELOG.md:v0.3.20 行

该流程在重大材料变更时会触发一次完整 review，确保索引与图谱之间的引用保持一致。

资料来源：CHANGELOG.md:v0.3.20 行

hebbrix_confidence —— 置信度与约束

hebbrix_confidence 自 v0.3.15 起对外开放，用于在每次检索结果中返回置信度评分以及"约束冲突"信号 (do_not_act)。当代理发现两条规则互相排斥时，会标记为不可执行。

资料来源：CHANGELOG.md:v0.3.15 行

v0.3.19 进一步引入 index_possibly_stale 字段，提醒调用方索引可能因异步富化而滞后，并附带文档漂移 (doc-drift) 检测，用于应对残酷测试 (BT1/BT6) 中发现的真实场景。

资料来源：CHANGELOG.md:v0.3.19 行

搜索与覆盖层 (overlay)

搜索工具维护一份"覆盖层 (overlay)"缓存，用于在不污染真实命中结果的前提下携带临时上下文。v0.3.17 明确保证：覆盖层永远不会高于真实命中 (overlay never outranks real hits)，避免幻觉放大。

资料来源：CHANGELOG.md:v0.3.17 行

v0.3.12 对覆盖层做了精度修复：注入停用词时不再误召回 (N1)，并把"已修正 (corrected)"标志正确传递给下游 (N2)。

资料来源：CHANGELOG.md:v0.3.12 行

v0.3.13 进一步将"持久化画像 (profile)"与"近期上下文 (recent)"分层存储，并清零相关性为 0 的搜索 padding，杜绝噪音占用上下文窗口。

资料来源：CHANGELOG.md:v0.3.13 行

工作流与数据流

下表汇总记忆与图谱工具在一次完整调用中的典型流转步骤：

资料来源：hebbrix_mcp/server.py:80-200, hebbrix_mcp/graph.py:1-120

写入阶段调用 hebbrix_import，它在解析后既写图谱又写搜索倒排索引；查询阶段由 hebbrix_ask 统一调度，先经 search.py 的覆盖层+真实命中合并，再由 graph.py 在子图上扩展邻居节点。

资料来源：hebbrix_mcp/search.py:1-100, hebbrix_mcp/graph.py:120-240

wait_for_index 是查询路径上的同步阻塞选项；当代理希望立即读到刚写入的内容时使用，否则将依赖 v0.3.11 中标注的"异步图谱富化"。

资料来源：CHANGELOG.md:v0.3.11 行

错误处理与可靠性

服务器在每次工具调用失败时附加 usage 块 (v0.3.14)，向代理说明失败原因、可重试动作与建议参数；同时项目改用共享池化 HTTP 客户端以降低长连接成本。

资料来源：CHANGELOG.md:v0.3.14 行

v0.3.18 加入"提示注入围栏 (prompt-injection fencing)"，并对 WAF 拦截返回更清晰的错误描述，应对红队测试 H1/M1 场景。

资料来源：CHANGELOG.md:v0.3.18 行

小结

记忆与知识图谱工具族以 hebbrix_ask 为查询主轴，以 hebbrix_import 为写入主轴，以 hebbrix_confidence 为可信度主轴，配合搜索覆盖层、置信度 stale 检测与提示注入围栏，共同构成一条"写入 → 富化 → 查询 → 评估"的闭环。

资料来源：README.md:40-120, CHANGELOG.md:v0.3.11-v0.3.20

工具定位与作用域

推理与账户工具 是 hebbrix-mcp 服务暴露给模型客户端的两类核心 MCP 工具集合：一类负责基于图谱与上下文的推理问答（hebbrix_ask、hebbrix_confidence），另一类负责账户与计量相关的导入、等待索引和使用反馈（hebbrix_import、wait_for_index、使用块 usage block）。它们在 hebbrix_mcp/server.py 中通过 FastMCP 装饰器统一注册为可远程调用的工具，构成了上层 Agent 触发“思考-求证-落库”完整链路的主要入口 资料来源：hebbrix_mcp/server.py:1-120。

README 明确将本服务定位为“记忆层 MCP”，并把推理与账户两类工具并列在功能矩阵中，强调它们是消费方调用 Hebbrix 平台 GraphRAG 能力与计费/配额体系的标准协议层 资料来源：README.md:32-88。

核心推理工具：hebbrix_ask

hebbrix_ask 是 GraphRAG 风格的问答工具，接收自然语言问题并返回带证据的答复，v0.3.16 中增加了 batch、export、mark_used 等能力 资料来源：hebbrix_mcp/tools/ask.py:1-90。该工具在客户端层会通过共享的池化 HTTP 客户端（v0.3.14 引入）发起请求，避免在长会话中反复建立连接 资料来源：hebbrix_mcp/client.py:1-60。

在 ask.py 中，问答响应不仅返回答案文本，还附带 sources（引用节点）和 confidence 字段；上层 Agent 可据此把推理结果回灌到 mark_used 端点，从而影响后续排序与覆盖层质量 资料来源：hebbrix_mcp/tools/ask.py:91-160。这种“推理即反馈”的设计让每一次 GraphRAG 调用都成为账户画像的一部分。

质量与置信度：hebbrix_confidence

hebbrix_confidence 用于在回答给出前显式评估证据强度，并在 v0.3.15 起新增了 do_not_act 状态：当检测到约束冲突（例如用户指令与系统策略、检索结果之间的矛盾）时，工具会返回 do_not_act=True，要求调用方暂停执行 资料来源：hebbrix_mcp/tools/confidence.py:1-95。

v0.3.19 进一步在响应里暴露了 index_possibly_stale 标志，用于在文档与索引之间出现漂移（doc-drift）时提示推理可能基于过期上下文，这是 brutal-test BT1/BT6 关注的回归点 资料来源：hebbrix_mcp/tools/confidence.py:96-150。

账户与数据接入：hebbrix_import 与 wait_for_index

v0.3.20 引入的 hebbrix_import 是账户侧的核心入口之一，用于把外部语料批量提交到 Hebbrix 平台，并支持在“材料发生实质变更”时重新走 E2E 复核流程 资料来源：hebbrix_mcp/tools/import_tool.py:1-80。该工具在写入后会返回一个 job_id，调用方可以配合 wait_for_index 轮询直到索引完成，从而保证后续 hebbrix_ask 不会读到半成品数据 资料来源：hebbrix_mcp/server.py:120-180。

wait_for_index 在 v0.3.11 中专门澄清了语义：它只保证倒排索引可见，并不保证图谱富集（async graph enrichment）已经完成；调用方若依赖图谱关系，需要额外检查 graph_ready 标志 资料来源：hebbrix_mcp/server.py:180-230。

使用计量与错误反馈

账户层通过 usage 模块在每次工具调用后生成统一的 usage 块；v0.3.14 起，即便在错误返回中也会附带该块，让上层 Agent 与计费系统能够准确归因 资料来源：hebbrix_mcp/usage.py:1-70。配额与认证信息由 hebbrix_mcp/auth.py 统一管理，工具调用前会校验 HEBBRIX_API_KEY 并在响应中嵌入账户标识 资料来源：hebbrix_mcp/auth.py:1-55。

下表总结了推理与账户工具的协作关系：

调用方在使用时建议遵循“导入 → 等待索引 → 推理 → 置信度校验 → 使用回灌”的顺序，这样既能避免基于未完成索引推理，也能让 mark_used 与 do_not_act 信号持续校准账户画像与系统行为。

1. 架构概览

hebbrix-mcp 是一个遵循 Model Context Protocol（MCP）规范的服务端实现，对外暴露一组结构化工具（hebbrix_import、hebbrix_ask、hebbrix_confidence 等），供 AI 客户端在对话上下文中调用，从而完成素材语义检索、图谱问答（GraphRAG）以及置信度评估。README.md 中描述了服务的整体定位与工具清单，SECURITY.md 则补充了提示注入防护与 WAF 拦截的处理边界。

整体采用「客户端 ↔ MCP Server ↔ 后端 API」的三段式结构：

flowchart LR
    A[MCP 客户端] -- stdio/JSON-RPC --> B[hebbrix-mcp Server]
    B -- 共享连接池 HTTP --> C[Hebbrix 后端 API]
    B -. 工具输出 .-> A
    C -. 异步图谱富化 .-> B

自 v0.3.14 起，服务统一了出站 HTTP 客户端并启用连接池，减少了因握手抖动导致的超时；v0.3.11 之后还明确了 wait_for_index 的语义并标记了异步图谱富化的进行中状态。资料来源：README.md:1-120、Dockerfile:1-30。

2. 部署指南

2.1 一键初始化

仓库根目录下的 quick_setup.sh 提供了面向新用户的引导脚本，负责校验依赖、写入环境变量并生成最小可运行配置；scripts/session-init.sh 则在每次会话启动时执行轻量级检查与状态重置。两者配合可覆盖「首次安装」与「会话热启动」两类场景。资料来源：quick_setup.sh:1-60、scripts/session-init.sh:1-45。

2.2 容器化部署

Dockerfile 描述了镜像构建步骤，建议在 CI 中通过多阶段构建以减小最终层体积。典型启动命令示例：

docker build -t hebbrix-mcp:latest .
docker run --rm -i --env-file .env hebbrix-mcp:latest

容器以 stdio 模式与宿主 MCP 客户端通信，因此必须保留 -i 以保持 stdin 打开。资料来源：Dockerfile:1-30。

2.3 客户端 Hooks 注入

hooks/hooks.json 声明了客户端侧生命周期钩子（如 SessionStart），用于在会话开始时调用 session-init.sh 并刷新缓存。该机制确保 v0.3.13 引入的「持久/最近内容分离」在跨会话场景下保持一致。资料来源：hooks/hooks.json:1-40。

3. 配置与运行时行为

服务行为受若干关键开关控制：导入（hebbrix_import）在素材发生实质性变化时触发使用量计量（v0.3.20）；hebbrix_ask 启用 GraphRAG 进行图谱问答，并在 v0.3.16 加入批处理、导出与标记已用节点能力；hebbrix_confidence 在检测到约束冲突时输出 do_not_act 标记（v0.3.15）。索引新鲜度则通过 index_possibly_stale 暴露（v0.3.19），调用方应据此决定是否降级信任结果。资料来源：README.md:60-180、SECURITY.md:1-40。

4. 故障排查

常见故障可分为三类：

进一步的调试建议：检查 session-init.sh 是否成功执行、确认容器内环境变量已注入（特别是 API 凭据）、并通过 usage 字段确认工具调用是否产生副作用（v0.3.14 之后，错误响应也会附带 usage 块以便对账）。资料来源：SECURITY.md:1-60、scripts/session-init.sh:20-45。

5. 版本演进要点（截至 v0.3.20）

近期版本集中在「结果诚实性」与「安全边界」两条主线：v0.3.16 引入 GraphRAG 问答；v0.3.17–v0.3.18 强化了缓存与注入防护；v0.3.19–v0.3.20 进一步在导入路径与置信度信号上消除漂移。运维升级时应优先在隔离环境验证 hebbrix_import 的 E2E 流程，再切换生产流量。资料来源：README.md:1-200。

Pitfall Log / 踩坑日志

项目：Hebbrix/hebbrix-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/Hebbrix/hebbrix-mcp | host_targets=mcp_host, claude, cursor, claude_code

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/Hebbrix/hebbrix-mcp | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/Hebbrix/hebbrix-mcp | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/Hebbrix/hebbrix-mcp | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/Hebbrix/hebbrix-mcp | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/Hebbrix/hebbrix-mcp | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/Hebbrix/hebbrix-mcp | release_recency=unknown