Skip to main content
Glama

graph-arch

Graph database-driven code architecture management system — use Neo4j to maintain a three-layer dependency graph of "requirements / code modules / data", with Agent development auto-fill, one-click change impact queries, and Hook reactive linkage for multi-Agent collaboration.

One-sentence configuration instruction for AI: "Read this README and complete the installation and configuration of this project according to the 'Quick Start' section."


What this project is

Existing tools cannot answer "if I change a data structure, what are all the places that need updating" — IDEs only recognize code imports, build systems only recognize compile dependencies, and data lineage only recognizes data pipelines. This project puts code, data, tools, and requirements into the same graph:

AI 运行 A ─PRODUCES→ 数据集 B ─→ 工具 C ─→ Excel D ─┐
                       └──→ 工具 E ─→ Excel F ─┴→ 工具 G ─→ Excel H ─→ 客户端/服务端
  • Impact analysis: for any node change, one Cypher query finds all downstream nodes

  • Strong gating: Agent declares graph changes (intent request) → git commit triggers review verification → only writes to graph after passing; failures can't even get a commit in

  • Reactive Hook: graph changes are distributed to relevant Agents according to subscriptions; propagation naturally converges when there are no changes

  • Desktop client: visualize graph data + view in-progress tasks

Design details: docs/design-v1.1.md, program structure: docs/architecture.md.


Related MCP server: codemap

Quick Start

Prerequisites

  • Windows 10/11 (Git Bash available)

  • Python ≥ 3.11 (verify with python --version)

  • Optional: OpenAI-compatible LLM API (for review / nightly maintenance agent, defaults to http://localhost:8642/v1, configurable or skippable)

One-command configuration (hand off to AI)

Say to any AI assistant after cloning this project:

"Read README.md, execute the quick start installation process, and complete this project's configuration."

The only core command the AI should execute:

python setup/setup.py

This script fully automatically completes the following steps (each step provides clear manual takeover instructions on failure):

Step

Action

Artifact

1

Check Python version

Exit with prompt if version mismatch

2

Download and extract JDK 21 (Temurin, multi-mirror)

runtime/jdk-21/ (skipped if system Java exists)

3

Download and extract Neo4j Community 5.x (multi-mirror)

runtime/neo4j/ (on download failure, prompts to manually place zip in runtime/ and rerun)

4

Start Neo4j service and initialize password

Password defaults to graph123, written to config/settings.yaml

5

Create .venv and install all Python dependencies

.venv/

6

Apply graph schema (constraints + indexes + sample pipeline seed data)

Three-layer graph in Neo4j

7

Register MCP server to ~/.workbuddy/mcp.json (auto-backup original file)

WorkBuddy can directly call 6 tools

8

Smoke test: run impact query once

Should return 8 downstream nodes

9

Output next-step instructions

Desktop client startup / git hooks / exe packaging

Estimated time: 5–15 minutes on first run (depends on download speed of JDK + Neo4j, ~380MB total). Resumable: the script is idempotent at each step; fix the issue and rerun, completed steps are automatically skipped.

Manual step-by-step (if you don't want the one-command script)

# 1. 依赖
python -m venv .venv && .venv/Scripts/pip install -e .

# 2. Neo4j(手动下载 zip 解压到 runtime/neo4j/,需要 JDK 21)
runtime/neo4j/bin/neo4j.bat install-service
runtime/neo4j/bin/neo4j.bat start

# 3. 初始化密码(首次默认 neo4j/neo4j,登录后强制改)
runtime/neo4j/bin/cypher-shell.bat -u neo4j -p neo4j \
  "ALTER CURRENT USER SET PASSWORD FROM 'neo4j' TO 'graph123';"

# 4. 应用 schema 与种子数据
.venv/Scripts/python -m graph_arch.setup_db

# 5. 注册 MCP(见下方「接入 Agent Harness」)

# 6. 验证
.venv/Scripts/python -c "from graph_arch.graph.queries import impact; \
  print(len(impact('data:dataset_b')), '个下游节点')   # 应输出 8"

Desktop client (visualization + activity monitoring)

# 开发运行
.venv/Scripts/python desktop/main.py

# 打包为独立 exe(产物在 desktop/dist/)
.venv/Scripts/python desktop/build_exe.py

Features:

  • Graph visualization: color-coded by layer (requirements/modules/data), click a node for details (summary, pointers, status, neighborhood)

  • Activity panel: pending intent requests, task queue, recent changelog stream, stale node list

  • Auto-refresh every 5 seconds


Integrating with Agent Harness

WorkBuddy

setup.py automatically writes to ~/.workbuddy/mcp.json. After restarting WorkBuddy, the following appear in the tools directory:

submit_graph_intent / query_impact / query_context / claim_task / get_pending_intents / get_pending_tasks

Hermes

If Hermes supports MCP: register this server the same way (python -m graph_arch.mcp_server, working directory is the repository root). If it only supports OpenAI function calling: tool definitions are in the docstring of src/graph_arch/mcp_server.py and can be directly converted to OpenAI tools format.

Agent workflow instructions (paste into system prompt or make into a skill)

开发工作流(必须遵守):
1. 接到任何修改类任务,先调 query_context 加载目标节点邻域(摘要+指针+状态)
2. 若涉及已有数据结构/模块,必须调 query_impact 确认影响范围
3. 按指针从源头(git/文档/schema)加载细节后开工
4. 完成后必须 submit_graph_intent 声明图变更,再创建 git 提交
5. review 失败则按返回原因修正,重新提交

Directory structure

graph-arch/
├── README.md                  # 本文件
├── pyproject.toml             # 包定义与依赖
├── docs/                      # 设计文档(v1.1)+ 结构文档
├── setup/setup.py             # 一键安装脚本
├── config/
│   ├── settings.yaml          # Neo4j/LLM/路径/超时(setup 自动生成)
│   ├── hooks.yaml             # Hook 规则注册
│   └── skill_routes.yaml      # skill 路由表(harness 层)
├── schema/                    # Cypher:约束 + 种子数据
├── src/graph_arch/
│   ├── graph/                 # client / writer / queries / merger
│   ├── hooks/                 # engine / cycle_guard / actions
│   ├── review/                # 核验协议 + LLM 调用
│   ├── tasks/                 # 任务队列 + 死信队列
│   ├── mcp_server.py          # 入口 1: MCP server(常驻)
│   ├── git_hook.py            # 入口 2: git hooks(pre-receive/post-merge)
│   ├── nightly.py             # 入口 3: 夜间维护(定时)
│   └── setup_db.py            # schema 初始化
├── desktop/                   # 桌面端(PySide6 + vis-network)
├── git-hooks/                 # 仓库钩子 + 安装脚本
├── changelog/                 # append-only 变更日志(JSONL)
├── runtime/                   # JDK / Neo4j(setup 下载,不入 git)
└── tests/

Configuration (config/settings.yaml)

Key

Default

Description

neo4j.uri

bolt://localhost:7687

Neo4j connection

neo4j.password

graph123

Written after setup initialization

llm.base_url

http://localhost:8642/v1

OpenAI-compatible endpoint (for review/maintenance, can be left empty to skip)

llm.model

default

Model name

hook.max_chain_hits

2

Max trigger count for the same node in the same Hook chain (loop prevention)

task.claim_timeout_sec

3600

Task claim timeout (reassign/dead-letter on timeout)

changelog.dir

changelog/

Changelog directory

Installing git hooks (target code repository)

bash git-hooks/install.sh /path/to/your/code-repo

After that, push/merge on that repository will trigger review verification and graph merging.

Troubleshooting

Symptom

Resolution

Neo4j download failed (403/timeout)

Manually download neo4j-community-5.26.0-windows.zip from neo4j.com, place in runtime/, rerun setup.py

neo4j start reports JAVA_HOME

Confirm runtime/jdk-21/ exists; or install system JDK 21

bolt connection refused

Check service status with runtime/neo4j/bin/neo4j.bat status; allow port 7687 through firewall

LLM connection failure during review step

LLM can be left empty: set llm.base_url to empty in settings.yaml, review degrades to "structural validation + manual confirmation" mode

MCP tools not appearing

Restart harness; confirm graph-arch entry exists in ~/.workbuddy/mcp.json and the path is correct

License

MIT (modify as needed)

Available Tools

7 tools
claim_taskClaim TaskA

认领一个 Hook 分发的任务(多 Agent 防撞车的排他锁定)。

何时必须调用:

  • 收到任务通知、评估后确认需要响应时,开发之前先认领

  • 认领成功才开工;返回 rejected 说明他人已认领,直接放弃

何时不需要:

  • 评估后确认无需变更时(不认领,让任务自然超时或被他人处理)

参数:

  • task_id: 任务 id(来自 get_pending_tasks)

  • agent_id: 你的 Agent 角色 id(稳定命名,与订阅关系关联)

返回: {status: claimed|rejected, task_id, ...}

Inputs: task_id (required), agent_id (required). Returns: object

get_pending_intentsGet Pending IntentsA

查看待核验的意图请求(review agent 专用)。

何时调用:

  • 你是 Review Agent,git hook 触发你执行核验时

  • 排查「为什么图没更新」时检查是否有滞留的 pending

何时不需要:

  • 普通开发任务(你不应该消费别人的意图请求)

返回: 意图请求列表(完整 JSON)

Inputs: no named parameters. Returns: result

get_pending_tasksGet Pending TasksA

拉取任务队列(被动触达的 pull 端)。harness 执行循环中每轮调用。

何时必须调用:

  • Agent 执行循环的每轮迭代开始时(检查是否有 Hook 分发给你的任务)

何时不需要:

  • 正在处理一个任务的中间(先完成当前任务)

参数:

  • status: pending(待认领)/ claimed(已认领)/ completed

返回: 任务列表 [{task_id, source_node, message, subscribers, status, ...}] 对订阅了你的任务: 先 query_impact 评估 → 需响应则 claim_task 后开工

Inputs: status. Returns: result

graph_revisionGraph RevisionA

查询当前图版本号(写意图请求时填入 base_revision,用于过期检测)。

Inputs: no named parameters. Returns: object

query_contextQuery ContextA

图导航:查询节点的邻域导航信息,用于 Agent 诞生后构建工作上下文。

何时必须调用:

  • 接到任何涉及已有节点(数据结构/模块/需求)的任务时,第一步调用

  • 收到 Hook 任务通知、需要了解变更节点的宏观环境时

何时不需要:

  • 已经持有该节点邻域信息的连续会话中(避免重复调用)

参数:

  • node_id: 图节点 id

返回: {id, type, layer, name, summary, path, status, skill_hint, neighborhood} 返回的是导航信息而非内容本身——按 path 指针从源头(git/文档/schema)加载细节。 skill_hint 是处理建议,实际路由由 harness 的 skill_routes.yaml 决定。

Inputs: node_id (required). Returns: object

query_impactQuery ImpactA

查询一个图节点的变更影响范围(谁会被这个节点的变更波及)。

何时必须调用:

  • 修改任何已有数据结构、模块或需求之前

  • 收到图变更通知、评估自己负责区域是否需要更新时

  • 规划跨模块任务、需要完整依赖上下文时

何时不需要:

  • 纯新增且明确无下游依赖的独立模块

参数:

  • node_id: 图节点 id(命名规范: data:user_table / module:auth_svc / req:login)

  • direction: "downstream"=谁被我影响 / "upstream"=我依赖谁

返回: [{id, layer, type, status, summary, path, hops}] 按传播距离排序。 返回的 path 是指针——细节由 skill 按指针从源头加载,不要向本工具索要内容全文。

Inputs: node_id (required), direction. Returns: result

submit_graph_intentSubmit Graph IntentA

提交图变更意图请求(开发完成后的必经步骤)。缓存为 pending,git 提交后由 review 核验。

何时必须调用:

  • 完成任何涉及图变更的开发任务后、创建 git commit 之前

  • 变更包括: 新增/修改节点(模块/数据结构/需求)、新增/删除依赖边

何时不需要:

  • 未产生任何结构变更的纯阅读/查询任务

参数:

  • intent_json: JSON 字符串,结构: {task_id, base_revision, nodes_to_create:[{id,label,props}], nodes_to_update:[{id,props}], edges_to_create:[{from,type,to,props}], edges_to_remove:[{from,type,to}], work_notes, summary, actor} work_notes 必填工作过程状态: 为什么这么改、考虑过什么备选(下一个实例靠它重建场景)

返回: {status: "pending", task_id, path} 注意: 本工具只缓存不写入——review 失败(git 提交被拒)时 pending 不会进图。

Inputs: intent_json (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 7 tools

    Disambiguation4/5

    query_impact and query_context are clearly differentiated by their focus (propagation vs. navigation), and the core command/voting tools are distinct. However, get_pending_intents and get_pending_tasks share a similar prefix and both return lists, so an agent could initially confuse them; descriptions mitigate but do not fully eliminate this.

    Naming Consistency4/5

    Most tools follow a snake_case verb_noun pattern (query_impact, submit_graph_intent, claim_task, get_pending_tasks, get_pending_intents). graph_revision deviates as a noun-only identifier, and there is minor verb variance (query vs. get vs. submit), but the overall pattern is readable and predictable.

    Tool Count5/5

    Seven tools is well within the ideal range for a specialized graph/context server. Each tool serves a distinct part of the investigate-assess-claim-submit-review workflow with no obvious redundancy or bloat.

    Completeness4/5

    The tool surface covers the core lifecycle: context discovery, impact analysis, task retrieval/claiming, intent submission, pending-intent review, and revision tracking. Minor gaps exist—such as no explicit intent-cancellation or node-detail tool—but query_context and query_impact fill most needs and the workflow appears functional.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      AI-native code intelligence graph that builds a persistent knowledge graph of your codebase in Neo4j and exposes it to AI assistants via MCP, enabling contextual code analysis, impact analysis, and dependency tracking.
      23
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for local-first code intelligence, providing structural code graph, semantic search, and impact analysis to AI agents.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Local-first code intelligence and safety layer for AI coding agents. MCP server exposes dependency graph, impact analysis, and AST-compressed repo context, backed by typed local memory, patch-scope safety gates, and git-independent transaction rollback.
      1
      MIT