GRAFOMEM CGR Capture

grafomem-cgr

一个 MCP 服务，让编码 Agent 能够记录自己的判断及判断结果， 并将记录发送到你的 GRAFOMEM Cloud 租户。

模型是现在记录，稍后评分。每当 Agent 做出可能出错的判断——“这次部署是安全的”“这次扫描没有问题”“这条审查发现确实存在”—— 它就会记录该判断。之后，事实明朗时，它会记录结果。两者通过你选择的 work_item_id 关联起来。最终积累的是一份仅追加、可追溯的判断及其结果记录。

此软件包仅负责记录。它会向你的租户写入数据；不会计算、提供或显示分数。

cgr.cosign.v1 验证器（可选附加组件）

除了记录客户端，此软件包还提供 cgr.cosign.v1 双方联合签名信封的参考验证器——grafomem_cgr.cosign_verify.verify(record, registry, ledger, trusted_issuers)，实现 docs/cgr/cgr-cosign-v1-spec.md §8（经决策 0010 和 0011 修订）。trusted_issuers 是必填项（§8.2a 发行者固定）：一个发行者密钥 ID 集合，没有默认值，也不存在信任所有发行者的路径——省略该参数或传入空集合都会拒绝记录，而不会信任记录自行声明的发行者。它是第二个独立的参考实现（第一个是 JS 版 @gns-foundation/cgr-verify）；两个实现都通过了 conformance/cgr-cosign-v1/ 中相同的 28 个向量一致性测试，判定结果完全一致。使用附加组件安装其依赖：

pip install grafomem-cgr[verify]      # rfc8785 + cryptography

记录功能不依赖它；该附加组件仅用于验证。

它不是什么

• 它不会在记录时评分，也不会将分数读回你的会话。
• 它不会让你的 Agent 更安全，也不会对任何操作进行把关。不会阻止、批准或禁止任何操作。
• 它不是合规、审计或安全产品。
• GRAFOMEM Cloud 目前的评分是单维度的：无论 domain 是什么，所有判断／认证决策都在同一个维度下评分。你传入的 domain 会按每项决策持久保存（见下文），以便之后追溯归属——但目前不会单独评分。

要求

需要有 GRAFOMEM Cloud 账户。免费套餐足够使用——预计每天只需提交少量决策。请注意，受治理的决策会计入套餐的实际用量；服务启动时会显示当前用量，因此不会让你感到意外。

安装与配置

只需一条命令和环境变量——无需检出代码仓库，也无需启动脚本。

Claude Code：

claude mcp add grafomem-cgr --scope user \
  --env GRAFOMEM_CGR_TENANT_KEY=sk_your_api_key \
  --env GRAFOMEM_CGR_TENANT=your_tenant_id \
  --env GRAFOMEM_CGR_ROLE_KEYS_JSON='{"cc-builder@acme":"<64-hex public key>"}' \
  -- uvx grafomem-cgr

或者使用任何读取 JSON 配置的 MCP 客户端：

{
  "mcpServers": {
    "grafomem-cgr": {
      "command": "uvx",
      "args": ["grafomem-cgr"],
      "env": {
        "GRAFOMEM_CGR_TENANT_KEY": "sk_your_api_key",
        "GRAFOMEM_CGR_TENANT": "your_tenant_id",
        "GRAFOMEM_CGR_ROLE_KEYS_JSON": "{\"cc-builder@acme\":\"<64-hex public key>\"}"
      }
    }
  }
}

环境变量

变量	必填	含义
GRAFOMEM_CGR_TENANT_KEY	是	租户的 X-API-Key。耐久性检查需要 decisions:read 权限。
GRAFOMEM_CGR_TENANT	是	你预期该密钥解析到的租户 ID。如果密钥解析到其他位置，则会拒绝所有写入。
GRAFOMEM_CGR_ROLE_KEYS_JSON	二选一	角色句柄 → 公共 agent_key 的映射，以 JSON 格式内联提供。
GRAFOMEM_CGR_ROLE_KEYS	二选一	同一映射，以 JSON 文件路径形式提供。
GRAFOMEM_CGR_FORBIDDEN_TENANTS	否	以逗号分隔的租户 ID；即使误设为固定租户，也会始终拒绝。请将生产租户放在这里。
GRAFOMEM_API	否	基础 URL。默认为 https://api.grafomem.com。

角色密钥

角色句柄（cc-builder@acme）是判断归属的身份标识。其 agent_key 是稳定的 Ed25519 公钥，共 64 个十六进制字符——记录绑定的主体。请为每个角色生成一个：

openssl genpkey -algorithm Ed25519 -out cc-builder.pem
openssl pkey -in cc-builder.pem -pubout -outform DER | tail -c 32 | xxd -p -c 64

请妥善保管私钥部分。此版本不会使用它——只绑定公钥——但未来计划加强每项决策的持有证明，而持有私钥才能证明该身份属于你。

工具

cgr_record_decision — 记录判断。

arg
work_item_id	由你选择的稳定关联键（PR 编号、任务 ID、运行 ID）
agent_handle	你配置的角色句柄之一
domain	deploy-verification | security-scan | adversarial-review
decision	certify | reject
verifiability_tag	judgment（默认）| rule
reason_code、reason_text	可选
agent_confidence	可选，接受但尚未持久化——见下文

出于向前兼容的考虑，工具架构接受 agent_confidence，但目前不会将其写入决策记录。请勿依赖它被存储。

只有 judgment + certify 才会改变评分。rule 决策是确定性的，不带任何声誉权重——请如实标记。

cgr_record_outcome — 记录结果。

arg
work_item_id	决策时使用的同一个关联键
result	结果标签，例如 deploy_succeeded、ci_failed、vuln_found、review_confirmed
source	可选的来源说明字符串

无法识别的 result 会被有意忽略，不执行任何操作。 决策会保持待处理状态，而不会凭猜测解决——错误解决决策会永久破坏记录。映射的标签包括：deploy_succeeded、deploy_healthy、ci_passed、migration_applied、merge_landed、pr_merged、scan_clean、no_vuln_confirmed、review_confirmed、finding_correct、bug_confirmed（成功）；deploy_failed、deploy_rolled_back、migration_failed、ci_failed、merge_reverted、vuln_found、secret_found、review_refuted、finding_wrong、bug_not_real（失败）。

安全属性

• 租户固定。 你需要预先声明租户。启动时会强制执行固定设置，且每次决策响应都会再次核对 API 实际解析到的租户，因此密钥轮换或错误密钥不会悄然写入其他位置。
• 拒绝名单。 GRAFOMEM_CGR_FORBIDDEN_TENANTS 会直接拒绝指定的租户。
• 密钥保管。 调用方选择角色句柄；服务端会注入该角色的密钥。工具调用绝不能提供任意密钥或指定其他租户。
• 故障开放。 如果服务配置错误，它会以非零状态退出，且不会加载。你的会话将继续运行，不受阻碍，也不会注册任何工具。被拒绝的工具调用会像正常工具输出一样返回错误，而不会导致 MCP 服务崩溃。
• 领域持久性。 domain 会作为专用字段发送，并针对每个决策存储在服务端的、CGR 可读取且从不加密的决策 parameters 中，键名为 cgr_domain——它存储在签名决策记录中，而非客户端日志中。selftest 包含一个持久性校验：重新读取刚写入的决策，并在 cgr_domain 未能往返时明确中止，而不会悄然记录缺少领域信息的决策。

CLI

grafomem-cgr                 # run the stdio MCP server (the default)
grafomem-cgr setup           # register your role identities on the tenant (idempotent)
grafomem-cgr selftest --handle cc-builder@acme --domain deploy-verification

selftest 会完整执行一次流程——决策 → 持久性校验 → 结果 → 评分读取——并打印变动情况和指标。在将服务接入会话前运行它。

链接

• grafomem.com · docs.grafomem.com
• 源代码 · 问题反馈

采用 MIT 许可证。