ServiceGraph

Local-first cross-repository change intelligence for AI agents

中文 · Web Workbench · Development plan · Impact analysis plan · Integrations

ServiceGraph is building a local-first, cross-repository change intelligence engine for AI agents. It connects frontend code, gateways, backend services, contracts, configuration, registries, databases, and eventually runtime traces so a requirement or code change can become an evidence-backed impact, development, integration, and verification plan.

ServiceGraph is in early development. The CLI, versioned SQLite graph, Codebase Memory Route/HTTP import, bounded cross-repository traversal, and MCP/CLI/Web Mermaid sequence output work today. Broader framework coverage, impact propagation, boundary view, and Change Lens remain in development.

Why ServiceGraph?

A repository code graph knows what the source says can happen. A service registry knows which service instances currently exist. A runtime trace knows what happened for one sampled request. Cross-service development needs all three views, tied to stable service, endpoint, revision, and source identities.

ServiceGraph aims to answer questions such as:

• How does a click in mall-web reach the inventory database?

• Which repository and handler implement POST /orders in the test environment?

• If this DTO, route, or service name changes, which repositories and tests are affected?

• Is this edge inferred from source, declared in a contract, or observed at runtime?

• Which services are the minimum set needed to develop this flow locally?

Related MCP server: agentmako

Architecture

flowchart LR
    CLI["CLI"] --> D["servicegraphd"]
    MCP["MCP server"] --> D
    WEB["Sequence Workbench<br/>(MVP available)"] --> D
    CBM["Codebase Memory"] --> D
    CG["CodeGraph<br/>(optional enrichment)"] --> D
    NACOS["Nacos<br/>(planned)"] --> D
    OTEL["OpenTelemetry<br/>(planned)"] --> D
    D --> GRAPH["Federated evidence graph"]
    GRAPH --> SEQ["Sequence query engine"]
    SEQ --> WEB
    GRAPH --> IMPACT["Impact engine<br/>(planned)"]
    IMPACT --> REPORT["Change, integration,<br/>and verification plan"]

ServiceGraph integrates with Codebase Memory as its planned default repository indexer and CodeGraph as optional in-repository enrichment. Both are independent projects and are detected as external tools; ServiceGraph does not install, bundle, or modify them.

Project status

Try the foundation

Requirements: Node.js 22+ and pnpm 11.

git clone https://github.com/LM20230311/servicegraph.git
cd servicegraph
corepack enable
pnpm install --frozen-lockfile
pnpm build

pnpm servicegraph doctor
pnpm servicegraph init /path/to/a/multi-repository-workspace
pnpm servicegraph sync /path/to/a/multi-repository-workspace
pnpm servicegraph status /path/to/a/multi-repository-workspace
pnpm servicegraph sequence /path/to/a/multi-repository-workspace \
  --entrypoint submitOrder --target "POST /orders"
pnpm servicegraph serve /path/to/a/multi-repository-workspace

sync always records a versioned workspace snapshot and Repository nodes in .servicegraph/graph.db. When Codebase Memory is installed and every configured repository already has an index, it also imports Route, HTTP_CALLS, CROSS_HTTP_CALLS, and HANDLES facts through the public CLI and advances the graph to federated. It never invokes index_repository automatically. Missing indexes and incomplete/truncated upstream results keep the graph at repository_inventory and are reported as diagnostics.

Try the reproducible five-repository fixture:

node fixtures/mall-workspace/materialize.mjs /tmp/servicegraph-mall
node fixtures/mall-workspace/seed-recorded-graph.mjs /tmp/servicegraph-mall
pnpm servicegraph serve /tmp/servicegraph-mall

Open http://127.0.0.1:7464. The seed command imports a deterministic recorded graph contract for demonstration and tests; it does not claim to analyze the fixture source or replace a real Codebase Memory sync. The Web UI defaults to Simplified Chinese, supports English from the header switcher, and remembers the selection in the current browser.

Run the stdio MCP server:

pnpm mcp

The server registers servicegraph_explore, servicegraph_sequence, and servicegraph_impact. When a complete federation snapshot exists, servicegraph_sequence and the servicegraph sequence CLI perform a bounded local SQLite traversal, collapse repository-internal steps, and return a normalized SequenceModel and/or deterministic Mermaid. Query/entrypoint/target lookup is available now; persisted chain IDs, declared-only filtering, boundary view, and Change Lens are not. Explore and impact propagation still return CAPABILITY_NOT_IMPLEMENTED. Every unavailable or unreachable operation returns a structured error instead of inventing a flow.

Broader target output example

The current renderer can produce the evidence-backed HTTP portion of this flow. The database call, return messages, and actor event below remain an illustrative target until their corresponding graph facts are imported:

sequenceDiagram
    actor User
    participant Web as mall-web
    participant Gateway as api-gateway
    participant Order as order-service
    participant Inventory as inventory-service
    participant DB as inventory-db

    User->>Web: Submit order
    Web->>Gateway: POST /api/orders
    Gateway->>Order: POST /orders
    Order->>Inventory: POST /reservations
    Inventory->>DB: INSERT reservation
    DB-->>Inventory: reservationId
    Inventory-->>Order: reserved
    Order-->>Web: orderId

Every future arrow must carry provenance, confidence, environment, revision, and a source anchor. Static possibilities and runtime observations will never be presented as the same kind of fact.

Roadmap

1. Complete the evidence-backed static vertical slice for Vue/React, Spring Cloud Gateway, controllers, OpenFeign, and JPA/MyBatis.

2. Extend the local Sequence Workbench MVP with boundary grouping, persisted sequences, source navigation, and export.

3. Add Git diff impact overlays across repositories, APIs, contracts, data, and tests.

4. Add two-stage requirement anchoring, Nacos/Kubernetes identity, and OpenTelemetry possible/observed comparison.

5. Generate development slices and later add permission-aware team workflows.

See the development plan for the overall roadmap and the impact analysis plan for the public model, interfaces, propagation rules, milestones, and acceptance criteria.

Contributing and security

Read CONTRIBUTING.md before proposing large API changes. Report vulnerabilities according to SECURITY.md, not in a public issue.

Independence and license

ServiceGraph is not an official extension of Codebase Memory or CodeGraph, and neither upstream project endorses or is responsible for it. See Integrations and NOTICE.

ServiceGraph is licensed under Apache-2.0.