Skip to main content
Glama
deenesjakoruzh
vietqtran

decision-graph

by vietqtran
OverviewSchemaRelated ServersScoreDiscussions
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: MCP Memory Server

设计原则

  • 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 installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Doclea MCP by docleaai

    Doclea MCPofficial

    docleaai
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides persistent memory for AI coding assistants, storing and retrieving architectural decisions, patterns, and solutions across sessions using semantic search, while also offering git integration for commit messages and code expertise mapping.
    MIT

  • 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.
    18
    9
    MIT

  • Context Graph MCP Server

    ingpoc
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables storing, querying, and managing decision traces with semantic search using Voyage AI embeddings and ChromaDB. Supports outcome tracking and category filtering for software development decisions.

  • arcane

    Edition-X
    A
    license
    Not graded
    quality
    B
    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

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/vietqtran/decision-graph'

If you have feedback or need assistance with the MCP directory API, please join our Discord server