AOE — Agent Ontology Engine

Agent Ontology Engine for software that needs to know, decide, and act.

中文 · Documentation · · Apache-2.0

AOE (Agent Ontology Engine) turns an external domain
model and corpus into a deterministic, versioned, verifiable runtime. An
application or Agent can then discover what exists, ask for a constrained
selection plan, resolve the right projection, and invoke governed actions
through one contract exposed by an embedded SDK, MCP, or HTTP.

The short version: AOE is the engine; a domain's vocabulary and data are
packages around it. There is no production Ticket schema, design ontology, or
fixed list of atom kinds hidden inside Core.

Why this exists

Most Agent knowledge systems start with a document or a skill file. That is a
fine authoring format, but it becomes a poor runtime boundary when a system has
to answer four harder questions:

1. What does this domain mean, exactly? Which types and relations are valid?
2. Which pieces of knowledge are relevant for this request, and why?
3. Can the runtime prove that the loaded snapshot is the one that was built?
4. What may an Agent read, and what may it actually change?

AOE makes those questions explicit without making the core domain-specific.
The model declares the vocabulary. The corpus supplies the units and evidence.
The compiler produces a verified snapshot. Query returns an explainable plan.
Action execution has its own authorization and evidence path.

The boundary

┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│  Model Package   │  │  Corpus Package  │  │ Adapter / Tools  │
│ types, relations │  │ units, sources   │  │ providers, evals │
└────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘
         └─────────────────────┼─────────────────────┘
                               ▼
                    ┌────────────────────┐
                    │       AOE         │
                    │ parse → IR → build │
                    │ verify → snapshot  │
                    └─────────┬──────────┘
                              │
             ┌────────────────┴────────────────┐
             ▼                                 ▼
       Selection Plan                    Governed Action
             │                                 │
             └──────────────┬──────────────────┘
                            ▼
                    SDK · MCP · HTTP

What belongs where

If replacing Ticket with Recipe requires a new branch in the engine, the
boundary is wrong. In a healthy Domain Package, the engine only sees declared
types and contracts.

How the runtime works

1. Model-driven compilation

The compiler reads a Model Package and source units, normalizes them into a
shared IR, emits model-defined projections, and writes a deterministic bundle:

model/ + corpus/sources/
          │
          ├─ parser + structural checks
          ├─ IR normalization
          ├─ projection / relation compilation
          ├─ corpus index + manifest + model lock
          └─ optional signature
                    │
                    ▼
          immutable verified snapshot

_index.xml, projection artifacts, corpus.manifest.json, and model.lock are
generated outputs. They must not be edited by hand. Runtime verifies identity,
paths, signatures (when required), and the canonical content digest before it
serves a snapshot.

2. Explainable query

The query path does not return a mysterious list of strings. It returns a
SelectionPlanIR that records:

• candidate generators and feature contributions;
• visibility and principal filtering before ranking;
• hard constraints and soft preferences;
• relation closure, expansion, exclusion, cycle policy, and load order;
• projection levels and token budget decisions;
• diagnostics when an external generator or relation semantic is unavailable.

The plan is useful to an Agent, but also to a test, an audit log, or a human
debugging why a result was selected.

3. Governed action

Read and write are intentionally different paths. An action must declare its
input/output, side effects, capabilities, preconditions, idempotency, and
approval requirements. The runtime can then perform preflight and dry-run,
authorize a principal, evaluate policy, request human approval, retry within a
bound, and append evidence to an event store. Reading a unit never implies
permission to mutate external state.

Quick start

The repository is a TypeScript workspace and uses Bun for
installation, builds, and tests. Node.js 22+ is useful for consumers of the
HTTP and MCP entry points.

git clone https://github.com/kernary-aoe/aoe-engine.git
cd aoe-engine
bun install --frozen-lockfile

# confidence check
bun run typecheck
bun run test
bun run build

Run the CLI without installing a global binary:

bun packages/cli/src/index.ts --help
bun packages/cli/src/index.ts --version

Build and mount the smallest example

The engine repository carries small example packages so that the full path is
easy to inspect. They are not built-in Core ontology:

bun scripts/build-atom-dirs.ts \
  --src examples/hello-world/primes/sources \
  --out examples/hello-world/primes/compiled \
  --model compat/prime-v1-model \
  --corpus org.example/hello-world \
  --release 2026-08-31

The output is a verified snapshot containing an index, projections, manifest,
and lock. To expose it through the generic MCP transport:

AOE_CORPUS_DIR=examples/hello-world/primes/compiled \
AOE_MODEL_DIR=compat/prime-v1-model \
bun packages/mcp-server-core/src/index.ts

The MCP entry point reads the mounted Corpus and Model paths from its environment
configuration. New integrations should use the aoe CLI and the package
contracts documented below.

Author a domain without changing the engine

A Domain Package normally looks like this:

my-domain/
├── model/
│   ├── model.yaml              # types, relations, projections, actions
│   └── policies.yaml           # declared policy sets
├── corpus/
│   ├── sources/                # source declarations / unit inputs
│   └── corpus.yaml             # identity, provenance, publication policy
├── adapters/                   # optional source/provider integrations
├── tools/                      # optional domain MCP or HTTP handlers
└── README.md

The exact declaration format is intentionally a package contract rather than a
Core constant. Start with:

• Package model
• Define and run a domain
• Connect an Agent
• Actions and policies
• Releases and migrations

The reference Frontend Design Domain Package
is one example of this boundary. Security, backend, mobile, and cooking
corpora in the workspace are additional conformance fixtures, not Core
features.

Package map

The workspace is organized by contract, not by a single framework package:

The workspace packages are implementation modules for AOE. Their names are
listed here so a host can choose the layer it needs; domain users normally
depend on the SDK or a transport rather than importing every module.

Security and reproducibility invariants

AOE is designed to fail closed at the boundaries that matter:

• canonical digests are independent of checkout location and object order;
• manifest and projection tampering fails before content is returned;
• lexical traversal, absolute paths, symlink escapes, FIFOs, and other
  non-regular artifacts are rejected;
• visibility is applied before ranking and relation expansion;
• hard constraints cannot be outweighed by a larger score;
• capability and policy checks happen before effectful execution;
• idempotency is scoped by tenant/workspace and conflicting replays fail;
• unavailable external providers produce diagnostics, not fabricated passes.

Run bun run test to exercise these invariants. The integration workspace runs
the stronger cross-package check with bun run verify.

Project status

The v0.2 engine, SDK, generic query planner, governed action runtime, MCP and
HTTP transports, model/code generation, language-server foundation, and
reference Domain Package are implemented and tested. The hosted Registry,
first-party evaluation service, and production observability deployment are
extension products, not hidden assumptions in Core.

The next work should deepen package distribution and migration tooling rather
than add domain-specific branches to the engine.

Contributing

Engine changes belong here. Domain vocabulary and corpus content belong in a
Domain Package. Before opening a pull request:

bun install --frozen-lockfile
bun run typecheck
bun run test
bun run build

Read CONTRIBUTING, or the
中文贡献指南. For a security issue, use
SECURITY.md.

License

AOE Engine is licensed under Apache-2.0. External Domain and
Corpus Packages carry their own source attribution and licence terms.