ArchGraph

An architecture-graph driven framework for Agentic Engineering.

What is this?

ArchGraph builds a unified language that puts harness design and target product design into one model — so you get a single view to work and observe, and real control over your agents.

It doubles as a long-term memory for coding agents: an ArchiMate 3.2 intent graph exposed through a single read/write MCP interface. Memory is tiered — a compact working memory restored at session start, a long-term memory recalled on demand — and writes are deduplicated, so the graph stays clean and semantic recall stays precise. Reusable subgraphs can also be shared across projects through a federated registry, and any read tool can take an optional projectId to query another project's graph through the federation center — authorized, read-only, and by reference (denied by default). See the home page for the full capability set.

Architecture

The global architecture (Layered Viewpoint) shows how the human, the coding agent, ARGO MCP, the intent architecture graph, ArchiMate 3.2, and Enterprise Architect relate in graph-driven agentic engineering:

Editable source: scripts/gen-diagrams.js

Supported Harnesses

ArchGraph deploys the ARGO toolchain to all major coding-agent environments:

| Harness | MCP Server | Skills | Rules / Instructions | Agents | Wakeup Gate | |--------------------|:----------:|:------:|:--------------------:|:------:|:-----------:| | GitHub Copilot | ✓ | ✓ | ✓ | ✓ | — | | Cursor | ✓ | ✓ | ✓ | ✓ | — | | OpenCode | ✓ | ✓ | ✓ | ✓ | ✓ | | DeepSeek Harness | ✓ | ✓ | ✓ | ✓ | ✓ | | OpenClaw | ✓ | ✓ | ✓ | — | ✓ | | Codex | ✓ | ✓ | ✓ | — | ✓ |

A single argo-deploy registers the argo MCP server and installs all artifacts into each harness automatically.

For Codex (OpenAI Codex CLI / desktop), argo-deploy places the artifacts where Codex looks: the rules go to ~/.codex/AGENTS.md (Codex injects the global AGENTS.md into every session, so the wakeup gate is always active), the argo-init and ea-human-reconcile skills go to ~/.codex/skills/, and the argo and graph-mcp MCP servers are registered in ~/.codex/config.toml ([mcp_servers.*]) — the argo server follows the workspace you open in Codex.

Install

npm install -g archgraph-argo
argo-deploy

Done — the ARGO toolchain, skills, and rules are deployed, and the argo MCP server is registered automatically in GitHub Copilot, Cursor, OpenCode, DeepSeek Harness (dsh), OpenClaw, and Codex.

Prerequisites and configuration

Everything works out of the box except semantic (Graph RAG) queries, which need:

• Neo4j graph database — stores the structural projection of your architecture graph. During argo-deploy you configure ARGO_NEO4J_DATABASE_URL, ARGO_NEO4J_DATABASE_USERNAME, and ARGO_NEO4J_DATABASE_PASSWORD in ~/.argo/.env.
• Embedding / vector engine — powers semantic Graph RAG retrieval. Configure ARGO_EMBEDDING_BASE_URL, ARGO_EMBEDDING_MODEL, ARGO_EMBEDDING_PROVIDER, ARGO_EMBEDDING_MODEL_VERSION, ARGO_EMBEDDING_DIMENSIONS, plus the API key QWEN_KEY. It points at any OpenAI-compatible embedding endpoint — a cloud provider, or a self-hosted server for offline / intranet / private deployments via ARGO_EMBEDDING_PROFILE=openai-compatible (see the self-hosted embedding guide).

Where do the values come from? The Neo4j credentials come from the Neo4j instance you own or provision (URI, username, password). The embedding configuration and QWEN_KEY come from your embedding provider's dashboard — for example Alibaba DashScope — or from a self-hosted OpenAI-compatible server. argo-deploy walks you through the prompt (existing non-empty values in ~/.argo/.env are kept); you can also edit the file afterwards and re-run.

How to use

Step 0 — initialize the workspace. In a fresh project, ask your coding agent to run argo init (the initializeWorkspace MCP call). It creates a starter design/KG/SystemArchitecture.json when missing, performs the first JSON → Neo4j sync, initializes the semantic (Graph RAG) lifecycle, and verifies the architecture. From then on, the intent graph is the source of truth for the project.

After installing, open your project and start a coding agent. It will:

1. locate the architecture element behind the task before changing anything,
2. arm itself with that element's Skills and Rules,
3. work test-first (GIVEN-WHEN-THEN), and trace every commit back to the graph,
4. reuse an existing element, relationship, or view instead of creating a duplicate — the write path deduplicates by identity and flags a semantically near element of the same type.

The intent architecture graph — modelled in ArchiMate 3.2 — is the single source of truth.

The federation model

ArchGraph is a federated intent graph, not one big distributed graph. Every project owns a complete, sovereign canonical graph (design/KG/SystemArchitecture.json) and stays the single source of truth for its own model — nothing is split, sharded, or merged into a central super-graph.

Projects co-build by federation: a member self-registers with the federation center, others discover it, reads are explicitly authorized and denied by default, and a cross-project read returns a reference, not a copy. The center holds only federation metadata — membership, capabilities, interfaces, grants — plus a read-only mirror: it is a registry + broker, never the content.

The pattern is Registry–Broker Federation over sovereign knowledge graphs: self-registration + discovery + capability-based authorization + reference-not-copy, mediated by a broker. It is federated, not "distributed" — a distributed model would mean one logical graph partitioned across nodes, which is exactly what this design avoids.

Community

ArchGraph runs on open co-building. Join the community hub to share, browse and reuse architecture subgraphs across projects, and follow the governance & contribution guides:

• Community site — https://argo.derekworkspacev5.com/archgraph/ (subgraph library, docs, blog)
• graph-wiki repository — https://github.com/derekhu0002/graph-wiki (graph-asset home: contribute a subgraph from your project, or pull one back to reuse)

Sharing is federated: each project keeps its own graph sovereign and publishes subgraphs to a registry, where other members register, discover, and read opened content by reference — register, discover, authorize, read. Access is denied by default, and nothing is copied or merged. Browse the federation members.

License

Apache License 2.0