Skip to main content
Glama
Sign In
deenesjakoruzh
decision-graph

decision-graph

by vietqtran
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

decision-graph

英文 · Tiếng Việt

CI License: MIT Python 3.10+

为 AI 代理所处理的代码库提供决策记忆。

代码图告诉你代码做了什么。decision-graph 告诉你为什么是这样——业务规则何时出现、谁决定的、哪些备选方案被拒绝，以及该决策是否仍然有效。

git blame 给你一条提交信息。它不会告诉你客户的 CTO 在会议上要求增加第二级审批、一个单独的模块曾被考虑但因无法合并而被拒绝，或者六个月后有人降低了阈值。

与语言和框架无关。适用于任何仓库。

为什么

当一个基础产品按客户扩展时，痛点最为尖锐——但任何业务逻辑积累的地方都会出现：

  • 代理“改进”了一条为某个租户特意编写的规则。

  • 没人记得一个看起来奇怪的代码分支是 bug 还是需求。

  • 同一个被拒绝的方案每隔几个月就被重新提出。

  • 决策存在于 Slack 线程、工单评论和人们的头脑中。

AI 代理使情况更糟，因为它们对过去六个月的会议没有隐式记忆——但如果存在书面记录，它们会遵循。

Related MCP server: arcane

设计原则

  • Markdown 是事实来源。 每个决策一个 .md 文件，放在 git 中，可在 PR 中审查。

  • SQLite 只是索引。 删除 decisions/_index/ 可随时重建。

  • 代理不得虚构 decided_by。 代理只能创建 draft；将其提升为 active 需要人工。

  • 记录是编码的副作用，而不是需要记住的杂务——钩子在正确时机提示。

  • 检测读取 git，而非工具事件。 使用 sed、heredoc、git apply 或普通编辑器进行的编辑，与 Edit/Write 工具调用一样会被捕获。

安装

尚未发布到 PyPI——直接从 GitHub 安装：

uv tool install "decision-graph[mcp] @ git+https://github.com/vietqtran/decision-graph"
# pipx
pipx install "decision-graph[mcp] @ git+https://github.com/vietqtran/decision-graph"

# one-off, no install
uvx --from "git+https://github.com/vietqtran/decision-graph" decision-graph --help

# local development
git clone https://github.com/vietqtran/decision-graph && cd decision-graph
uv venv && uv pip install -e ".[mcp]"

需要 Python 3.10+ 和带 FTS5 的 SQLite 构建（macOS、Debian/Ubuntu 和官方 Python 镜像均标配）。

快速开始

cd /path/to/your/repo
decision-graph init

decision-graph add --scope acme --module deals/approval \
  --title "Second approval tier for deals over 500M" \
  --file src/approval.py --tag override-base --stdin < body.md

# a human confirms who decided — the agent cannot do this step
decision-graph confirm acme-2026-08-26-second-approval-tier --by "Jane Doe (CTO, Acme)"

decision-graph search "two-tier approval" --scope acme
decision-graph history src/approval.py   # every decision that touched this file
decision-graph overlay acme              # how acme differs from base, and why

核心概念：scope

scope 是区分上下文的轴——客户、产品线、团队，或适用于所有决策的 _base。

按 scope 过滤发生在全文排名之前，这能阻止一个租户的规则渗入关于另一个租户的答案。在服务多个客户的仓库中，这是最重要的字段。

布局

decisions/
  _template.md
  _base/                          # applies to every scope
  acme/2026-08-26-approval.md
  viettel/2026-05-20-inventory.md
  _index/decisions.db             # generated — gitignored
.decision-graph.yml               # per-repo watch/ignore patterns

记录的前置元数据：

id: acme-2026-08-26-second-approval-tier
scope: acme
module: deals/approval
title: "Second approval tier for deals over 500M"
status: active                 # draft | active | superseded | deprecated
lifecycle_stage: maintenance   # design | dev | uat | golive | maintenance
supersedes: acme-2026-03-12-single-tier
decided_by: "Jane Doe (CTO, Acme)"
requested_by: "John Smith (PM)"
decided_at: 2026-08-26
linked_files: [src/approval.py]
linked_commit: 8f3a2c1
session_id: abc-123            # agent session that produced the change
ticket: JIRA-482
tags: [approval, override-base]

正文遵循 decisions/_template.md：背景 / 考虑的备选方案 / 决策 / 影响 / 开放风险。

考虑的备选方案对代理比对人类更重要——它能阻止代理重新提出已被拒绝的方案。

supersedes 将记录链接成链而不是删除，因此审计轨迹得以保留。

搜索

先进行元数据过滤（scope、module、status、lifecycle_stage、file、tag），然后进行 SQLite FTS5 排名。变音符号会被折叠，因此 duyet don hang 能匹配 Duyệt đơn hàng。

decision-graph search "approval"                    # active decisions only, by default
decision-graph search --scope acme --status any
decision-graph search --file src/approval.py
decision-graph search "pricing" --tag override-base --json

代理集成

选择哪个触发器

情况

触发器

Claude Code 在同一台机器上运行，与仓库同机

Claude Code 钩子——可阻止，最强

Claude Code 在其他位置运行（SSH / VM / 远程）

Git 钩子——提醒，不能阻止

人类在没有代理的情况下提交

Git 钩子 + CI 中的 check

同时安装两者也没问题；一旦决策被记录，每个都会安静下来。

Claude Code 钩子

decision-graph hooks install --target /path/to/repo

  • PostToolUse(Edit|Write|MultiEdit) 记录会话接触了哪些文件。

  • Stop 检查 git 和该记录。如果业务相关文件被更改且未写入决策，则返回 decision: "block" 并附上说明——代理必须采取行动而不是结束。

代理恰好有两条出路：

decision-graph skip --session <id> --reason "renamed variables only"
decision-graph add ... --session <id>   # then ask the human, then confirm

stop_hook_active 会被尊重，因此这永远不会循环。

在 Claude Code 实际运行的地方安装钩子，而不是代码所在的地方。如果你在 VM 上运行 Claude Code，并且只将 shell 命令代理到持有仓库的机器，那么该机器的 .claude/settings.json 永远不会被读取——请改用 git 钩子。

Git 钩子

decision-graph hooks install --git --target /path/to/repo

安装 .git/hooks/post-commit 调用 decision-graph remind。它从不阻止提交。由于代理通过其 shell 运行 git 并读取 stdout，提醒无论如何都会进入代理的上下文。

一旦有决策链接到该提交，它就会保持沉默。

MCP 服务器

一个条目，在用户级别声明一次——服务器跟随会话打开的任意仓库，因此无需同步路径：

{
  "mcpServers": {
    "decision-graph": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/vietqtran/decision-graph",
               "decision-graph-mcp"]
    }
  }
}

它询问客户端会话正在哪个目录工作（MCP roots），回退到工作目录。没有 decisions/ 目录的仓库会被跳过，而不是猜测。仅当需要将服务器固定到一个仓库时，才添加 --path /path/to/repo。

工具：search_decisions、get_decision、get_decision_history、get_decision_chain、get_overlay_map、list_scopes、add_decision。

参见 docs/MCP.md。

过滤噪音

并非每次提交都是业务决策。拼写错误和纯重构不应生成记录。

默认忽略测试、锁文件、node_modules、构建输出、覆盖率报告、资产和 i18n 文件。可按仓库进一步缩小范围：

# .decision-graph.yml
watch:
  - "src/domain/**"
  - "app/services/**"

空的 watch 意味着所有不在 ignore 中的内容都算数。

CI

decision-graph check --git

输出 {"needs_decision": bool, "watched_files": [...], ...}——将其接入 PR 警告。

文档

开发

uv venv && uv pip install -e ".[mcp]"
.venv/bin/python -m unittest discover -s tests

除 PyYAML 外无运行时依赖；mcp 是可选附加项。

先例

decision-graph 是 ADR 的变体。ADR 为人类记录架构决策；本工具按租户记录业务决策，以代理可查询的形式——并带有自动捕获和人工确认门。

许可证

MIT

This server cannot be deployed

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Memory Server

    beach55607-max
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides long-term memory for AI coding agents, enabling them to remember, search, and organize information across sessions and platforms like Claude Code, ChatGPT, and Cursor.
    20 npm
    8
    MIT

  • arcane

    Edition-X
    A
    license
    Not graded
    quality
    A
    maintenance
    Provides persistent, searchable memory and knowledge capture for AI-assisted development, enabling agents to retain decisions, bugs, and patterns across sessions and projects.
    MIT

  • robrain

    adelinamart
    A
    license
    A
    quality
    A
    maintenance
    Self-hosted decision memory for AI coding agents. Captures decisions with the alternatives you rejected, and warns before an agent re-proposes a rejected approach.
    4
    89
    Apache 2.0

  • mcp-vector-memory

    BBerthod
    A
    license
    Not graded
    quality
    C
    maintenance
    Gives multiple AI coding agents a shared, persistent memory by indexing your code and documentation into a vector database with AST-aware chunking and hybrid semantic/keyword search. Agents can search across projects and store, update, or forget decisions, conventions and lessons learned, all self-hosted with local embeddings.
    MIT