🌌 OntoAgent

The All-Knowing Code Brain & Architecture Contract Guard for AI Coding Agents

A repository-wide cognitive knowledge graph and architecture governance engine for AI coding agents.

📖 Why OntoAgent?

Modern coding agents face three structural problems when working with large codebases:

1. Blind men and the elephant: They only see the current file, not cross-module callers, API contracts, and test dependencies.

2. Long-context hallucination: "Brute-forcing" the entire repository into the Prompt costs a lot of tokens, has a low signal-to-noise ratio, and the model tends to ignore critical constraints.

3. Destructive changes are hard to trace: Changing one core class makes it hard to quickly know which upstream modules, tests, and interfaces will break together.

Traditional approaches:

• Naive Raw Text: Stuff everything into the context — huge token usage and no structured targeting.

• Vector-Chunk RAG: Chunks by text similarity, compresses tokens, but loses AST-level dependencies, inheritance relationships, and contract semantics.

OntoAgent's choice:

Use AST static parsing + embedded graph database to build a repository-wide cognitive graph, so AI agents see the call network, contracts, tests, and blast radius before modifying code.

Related MCP server: code-intel

🏛️ Architecture Flow

graph TD
    subgraph Base["底座层"]
        Kuzu["Kùzu Embedded Graph DB"]
        AST["AST Parsers: Python / TypeScript / Markdown / JSON"]
    end

    subgraph Core["核心引擎"]
        Blast["Blast Radius Analyzer"]
        Context["Smart Context Extractor"]
        Compliance["Architecture Compliance Guard"]
        Scanner["Codebase Scanner & Entity Ingestion"]
    end

    subgraph Ecosystem["交互生态"]
        MCP["MCP Server"]
        DSH["DSH / Cordis Plugin"]
        CLI["onto-agent CLI"]
        Dashboard["React 2D Canvas + Dagre Dashboard"]
    end

    AST --> Scanner
    Scanner --> Kuzu
    Kuzu --> Blast
    Kuzu --> Context
    Kuzu --> Compliance
    Blast --> MCP
    Context --> DSH
    Compliance --> CLI
    Scanner --> Dashboard

📊 Benchmark

Reproduce with one command:

python benchmark/run_benchmark.py

Based on deterministic code fixtures, comparing three context construction strategies:

Conclusions:

• OntoAgent reduces token consumption by about 89.7% compared to Naive Raw Text.

• OntoAgent leads Vector-Chunk RAG across the board in critical dependency recall, test/contract recall, and blast radius targeting.

• Full report: benchmark/reports/benchmark_report.md.

🚀 Quickstart

1. Install

pip install -e .[test]

2. Scan the entire repository

onto-agent scan --path .

3. Launch the visualization workbench

python dashboard/api_server.py
# 打开 http://127.0.0.1:8000

4. Configure MCP

Copy integrations/cursor_mcp.json to .cursor/mcp.json, or merge it in Claude Desktop:

{
  "mcpServers": {
    "onto-agent": {
      "command": "python",
      "args": ["-m", "onto_agent.mcp"]
    }
  }
}

5. Install the DSH native plugin

dsh plugin --profile web add ./integrations/dsh/onto-agent-plugin

🧠 Agent Abilities

get_blast_radius(file_path)

Before modifying any file/symbol, returns:

• Direct callers

• Indirectly affected modules

• Downstream dependencies

• Associated API contracts

• Tests that must be run

check_architecture_compliance(strict=True)

Checks:

• Circular imports

• Cross-layer violation calls

• Core classes not covered by tests

get_smart_context(query_or_symbol)

Generates high signal-to-noise context before refactoring/generation:

• Definition, line numbers, Docstring

• Class/function list

• imports / callers

• API contracts, related tests, related documentation

🔌 Ecosystem

🗂️ Project Layout

src/onto_agent/
├── engine/          # Scanner, ArchitectureGuard, Context, Steering, Reflection
├── storage/         # Kùzu graph storage adapter
├── mcp/             # MCP Server
├── client/          # Python SDK
└── cli.py           # Unified CLI

dashboard/           # FastAPI + React workbench
benchmark/           # Reproducible Codex-for-Open benchmark
integrations/        # Cursor / Claude / Windsurf / DSH
docs/                # Design docs & tickets
tests/               # 48+ unit / integration tests

📚 Documentation

• MCP & SDK API

• System Architecture

• Ontology Schema

• Agent Behavior Protocol

• Dashboard Spec

• Contributing Guide

📄 License

This project is open-sourced under Apache-2.0.