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):

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)

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

License

MIT (modify as needed)