Graqle

---

GraQle 的功能

1. 记忆。 将代码、文档、政策和决策转化为一个相互关联的知识图谱，让记忆超越单次聊天会话。
2. 检查。 Agent 采取行动前，决策保障门会检查该行动，并给出 EXECUTE、REPLAN、HOLD、REJECT 或 ESCALATE 的答复——附带原因和签名记录。
3. 共享。 一个图谱供整个 Agent 团队使用——Claude Code、Cursor、Codex、Copilot——每个 Agent 都拥有各自的权限和文件。

支持任何模型：Anthropic、OpenAI、AWS Bedrock、Ollama、Gemini 等，也支持完全离线运行。

---

快速入门

pip install graqle

graq scan docs ./policies          # documents, policies, ADRs -> graph
graq scan repo .                   # code -> the same graph
graq learn knowledge "vendor DPA must be signed before any data access"
graq run "what approval is needed for a large refund?"
# -> answer + confidence + the exact sources it used

将它连接到 AI 工具（Claude Code、Cursor、Windsurf、VS Code）：

graq init        # detects your IDE and wires GraQle in

PDF、DOCX、PPTX 和 XLSX：pip install "graqle[docs]"。

---

检查每个决策

大多数 AI 工具只给出一个置信度数值。GraQle 会在 Agent 采取行动前分别提出问题——对一个问题的良好回答，绝不会掩盖另一个问题未通过检查：

• 是否允许？ 策略有效、执行者已获授权、证据为最新、参数与已批准的参数完全一致。任何一项回答“否”都会阻止该行动。
• 是否一致？ 图谱会跟踪相互矛盾的事实；一项变更会更新所有依赖它的决策。
• 是否足够确定？ 按维度衡量置信度，而不是将其混合成一个分数。
• 是否按计划进行？ 不可靠的步骤序列会在重试预算范围内退回重新规划。
• 由谁批准？ 根据行动的影响级别检查审批权限。

答复	含义
EXECUTE	所有检查均已通过。任何检查失败或出错后，都不可能返回此结果。
REPLAN	制定更好的计划并重试。
HOLD	缺少重要信息；等待补齐。
REJECT	不允许，或与证据矛盾。
ESCALATE	由人工决定。

from graqle.assurance.gate import DecisionAssuranceGate

verdict = gate.evaluate(candidate, ctx)
verdict.outcome         # EXECUTE | REPLAN | HOLD | REJECT | ESCALATE
verdict.decisive_rule   # which rule decided
verdict.reason_codes    # why

每个决策都会留下封存记录：带签名且经过哈希链保护的溯源事件，可导出为 W3C PROV-O 格式并使用 SHACL 检查，审计人员可以用标准工具验证。该门默认关闭：安装或升级 GraQle 不会带来任何变化，除非你主动启用它。

按项目启用：

1. 在 GraQle 运行的环境中（或 .env 中）设置 GRAQLE_DAG_ENABLED=true。
2. 提供必需的设置。GraQle 不附带任何阈值、盐值或密钥：由你自行选择。参考 .env.example 中的 GRAQLE_DAG_* 部分，并填写所有占位项（盐值、阈值、签名密钥 ID 和版本、校准器版本，以及其中列出的其他项）。将值设为环境变量，或放入 GRAQLE_DAG_SECRETS_PATH 指定的私有文件中（默认为 .graqle/graqle_secrets.yaml）；环境变量优先。
3. 按照通常方式启动。如果缺少必需值，GraQle 会在首次加载门设置时抛出配置错误，并指出缺少的值。不会静默回退。

检查方式：运行 python -c "from graqle.assurance.settings import is_dag_enabled; print(is_dag_enabled())"，应输出 True。

如需再次关闭，请取消设置该标志或将其设为 false。详情：操作决策保障门。

---

一个供团队 Agent 共用的记忆

多个 Agent 使用同一代码库，通常意味着内存中会有多个相同图谱副本。GraQle 可以只保存一份：

# where the graph lives
graq mcp serve --transport http --port 8765 --config graqle.yaml --allowed-roots /path/to/projects

# in each agent session (.mcp.json)
{ "mcpServers": { "graqle": { "command": "graq", "args": ["mcp", "relay", "--url", "http://127.0.0.1:8765"] } } }

• 占用更少内存。 每个会话运行的是小型中继，而不是完整副本（在 20,000 节点图谱上测得：3 个独立服务占用 687 MB，共享服务 + 3 个中继占用 493 MB）。
• 所有会话即时共享学习成果。
• 每个会话保留自己的门控和文件——文件操作在每位用户自己的机器上进行。
• 团队成员可通过 SSH 隧道或带令牌的 HTTPS 连接。
• 在一台服务器上运行多个项目，各自使用独立图谱（Team 和 Enterprise）。

启用决策门控（可选择加入，基线层级）

除非设置了 GRAQLE_DAG_ENABLED，否则决策门控默认关闭；关闭时不会有任何变化。启用方法：

1. 创建一个 ed25519 签名密钥（PEM，模式为 0600）和一个列出其公钥的密钥清单 （graqle.assurance.key_manifest_store.save_manifest），以及一个覆盖范围策略文件。
2. 设置 GRAQLE_DAG_ENABLED=1 和必需的 GRAQLE_DAG_* 配置项：SIGNING_KEY_ID、 SIGNING_KEY_VERSION、SIGNING_KEY_PATH、COVERAGE_POLICY_PATH、CONFIG_SALT、CAP_VALUE、 HG05_POISONING_THRESHOLD、HG07_MATERIALITY_THRESHOLD、CALIBRATOR_VERSION、 TRAJECTORY_ESTIMATOR、MAX_RETRY_BUDGET、CIRCUIT_BREAKER_WINDOW、SCOPE_KEY_FIELDS_REF、 MERGE_PRIORITY_REF。这些配置项没有内置默认值，需要由你自行选择。
3. 注册可执行 MEDIUM 风险调用的参与者（例如 GRAQLE_RBAC_ACTORS_JSON）。未注册角色的参与者会被硬性门控 HG-06 拒绝。
4. 启动进程。打包的默认运行时提供程序会在启动时注册。如果无法构建该提供程序，进程会在启动时失败，并显示提及 register_runtime 的错误；如有需要，可使用 graqle.assurance.adapter.register_runtime(provider) 提供自己的程序。

基线层级的决策受规则 DAG-RT-BASELINE-ADMIT 管控。此类决策不会计算或记录投影分数、可靠性或残余风险。只有风险为 LOW、影响为零且所有硬性门控均通过时才会 EXECUTE；其他情况将为 HOLD（DAG-RT-NO-EVIDENCE），若硬性门控失败则为 REJECT。MEDIUM 及以上级别的路由需要显式配置。每项决策都会记录为经过签名、采用哈希链的来源事件；如果无法写入，则不会执行调用。

这是证据层级为 BASELINE、受策略范围约束的授权。它不基于图谱，也不构成安全验证。基于证据的评分将在 0.88 版本中推出（CR-DAG-088-1）。 python scripts/dag_wheel_e2e.py 会在干净的虚拟环境中，使用构建好的 wheel 执行这些步骤。

---

信任

• 本地优先，不进行遥测。 图谱是由你掌控的文件；不会向外发送数据。
• 默认安全。 除非你明确启用本地开发模式，否则服务需要身份验证；图谱上传绝不会在无提示的情况下相互覆盖。
• 经过签名的发行版本。 使用 Sigstore 签名的 wheel、CycloneDX SBOM、可复现构建。
• 受监管的工作。 为你自己的 EU AI Act 文件提供审计记录和证据导出——GraQle 提供证据，但不会声称能让你合规。详情

请将漏洞报告发送至 [email protected] · SECURITY.md

---

版本

	提供内容
Free	知识图谱、所有核心工具、治理门控、Decision Assurance Gate、单个项目的共享服务
Pro — $19/mo	云同步、优先模型、托管的透明日志中继
Team — $29/dev/mo	跨项目共享图谱（多项目服务）、团队经验、审计日志保留
Enterprise	本地部署、自定义后端、支持 SLA——联系我们

---

最新版本

• v0.87.0 — 决策保障门：五项回答决策、矛盾追踪、各维度置信度、重新规划、签名溯源记录。
• v0.86.0 — 为一组 Agent 提供统一记忆：共享服务、轻量中继、按会话设置门控、在每位用户的机器上处理文件；服务默认安全。

完整更新日志

---

专利与许可证

核心方法正在申请专利：EP26167849.4、EP26162901.8 和 EP26166054.2。源代码完全可审计，遵循 GraQle License，详见 LICENSE。