Agent Ontology Engine
Domain knowledge, made executable.
AOE compiles your domain model and knowledge into a versioned runtime. Agents and applications query it, get a plan they can inspect, and change state only through declared actions.
What AOE is
For domains that are more than a pile of documents.
AOE is useful once your domain has named things, relationships between them, retrieval you can predict, and operations that need to stay safe. You declare that domain in a package you own: the types and relations, the material released against them, and the actions an agent may request.
The engine compiles those declarations into an immutable snapshot and serves it. It fixes the declaration schema and the runtime contracts, and nothing else. There is no built-in list of business types to reuse, so a support model, a recipe model, and a compliance model all compile through the same path.
Read how selection works →{
"corpus": "com.example/support",
"query": "open incidents affecting the checkout service",
"topK": 8,
"projection": "core"
}A Selection Plan, which your application can log, diff, and test.
selected units- what matched, in load order
score contributions- why each unit ranked where it did
constraint decisions- which limits applied, and to what
relation expansion- which links were followed or excluded
projection loads- summary, core, or full, per unit
budget use- tokens spent against the request budget
snapshot identity- the exact release and digest that answered
The packages you own
A package tells AOE what your domain is.
Keep all four in one repository while you prototype, then publish them separately when different teams own the model, the data, or the providers.
What can exist, and what can be done
Types and fields, relation direction and cardinality, the projections returned at each detail level, retrieval profiles, and the actions an agent may request. The declarations are data, validated against the engine meta-schema.
typesrelationsprojectionsretrievalactionspolicies Which material is released against it
Source units and assets, corpus identity and the compatible model range, provenance and licence, visibility, evaluation fixtures, and the signed release. A build turns your sources into an immutable snapshot.
unitssourceslicencereleasesdigests Where the outside world connects
A source catalogue, search provider, validator, evaluation provider, or action provider. An adapter can add an integration, and it cannot quietly add a type or relation to your model, which keeps providers replaceable.
importersproviderspermissions The thing an agent installs
Model, corpus, adapters, optional tools, and an optional Skill composed into one deployable product. The Skill teaches an agent how to ask well; it grants no capability and cannot bypass action policy.
modelcorpusadapterstoolsskills How a request travels
From a declaration to a reliable action.
Scroll through the four boundaries a domain crosses inside the runtime.
-
You write the vocabulary.
The Model Package defines what a valid object and relationship look like. The Corpus Package supplies the objects and their sources. The engine reads both as data and holds no domain of its own.
- Input
- types · relations · units
- Owner
- your team
- Output
- declarations
-
Declarations become a reproducible build.
The compiler joins the model with each source unit and emits projections, an index, a manifest, and a model lock that pins the exact schema digest. The same input produces the same bytes.
- Checks
- schema · relation · licence
- Output
- unit artifacts + index
- Guarantee
- deterministic
-
The runtime only loads complete snapshots.
Snapshot identity binds model, corpus, release, and digest. The runtime recomputes identity and content before it serves anything, so a host can answer whether the release is the one its corpus expects and whether it arrived untampered.
- Identity
- tenant · corpus · release
- Proof
- manifest + content digest
- State
- immutable
-
Reading and writing are separate contracts.
A query returns a Selection Plan with its constraints and evidence. An action starts from a model declaration, passes principal, capability, precondition, idempotency, and policy checks, and runs only after any required approval. Evidence appends to the event store.
- Read
- SDK · MCP · HTTP
- Plan
- explainable + budgeted
- Write
- policy-gated
Choose your boundary
Put the runtime where your work already is.
The same model and corpus run in-process, mount into an agent through MCP, or sit behind an HTTP service. The query, plan, and action contracts stay the same.
Read the integration guide →import { AoeClient } from '@aoe/sdk';
const aoe = new AoeClient({
snapshot: './dist/snapshot',
model: './model',
});
const plan = await aoe.query({
corpus: 'com.example/support',
query: 'open incidents affecting checkout',
topK: 8,
});
// plan.selected, plan.constraints, plan.snapshotAOE_CORPUS_DIR=./dist/snapshot \
AOE_MODEL_DIR=./model \
bun packages/mcp-server-core/src/index.ts
# tools the Model Package exposes to the agent
aoe_query({ query: "open incidents affecting checkout" })
aoe_plan({ query: "...", budget: { tokens: 4000 } })
aoe_act({ action: "resolve", target: "INC-2041" })curl -X POST https://runtime.example/v1/query \
-H 'Authorization: Bearer $AOE_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"corpus": "com.example/support",
"query": "open incidents affecting checkout",
"projection": "core"
}'
# → SelectionPlan + snapshot identity + digestWhat people build with it
Anywhere an agent needs to know your objects by name.
Each of these needs the same three things: a vocabulary the application shares with the agent, material with traceable sources, and writes that stay under policy.
- 01
Support assistant
Incidents, services, teams, and releases with the relations between them, so an assistant can follow impact instead of guessing from ticket text.
A question it answers Which open incidents affect checkout, and who owns them?
- 02
Compliance review
Controls, evidence, and exceptions under a versioned release, so a review can cite the exact snapshot it read.
A question it answers Which controls lack evidence for this quarter?
- 03
Operations knowledge base
Runbooks and procedures as typed units with preconditions, where the risky steps are declared actions rather than prose an agent improvises.
A question it answers What is the rollback procedure, and may I run it?
- 04
Data catalogue
Datasets, owners, lineage, and access rules, retrieved through a profile you configure instead of a similarity score you cannot inspect.
A question it answers Which datasets carry customer data, and who approves access?
- 05
Design system guidance
The reference Frontend Design package: 797 units of patterns, anti-patterns, and rules an agent consults while writing interface code.
A question it answers What breaks keyboard access in this component?
The five-minute path
Three commands to a verified runtime.
The engine repository ships a small example so you can watch the whole path before you create a domain of your own.
- 01
Install the engine
Clone the repository and install with a frozen lockfile.
git clone https://github.com/kernary-aoe/aoe-engine.git cd aoe-engine bun install --frozen-lockfile - 02
Build an example
The model path is explicit, because the example vocabulary belongs to the example package and not to AOE Core.
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 - 03
Connect a client
Mount the same snapshot and model you built. The SDK and HTTP transports expose the same contracts.
AOE_CORPUS_DIR=examples/hello-world/primes/compiled \ AOE_MODEL_DIR=compat/prime-v1-model \ bun packages/mcp-server-core/src/index.ts
Questions
Frequently asked.
01 How is this different from putting documents in a prompt or a vector store?
A prompt or a vector index stores text and returns passages ranked by similarity. AOE stores a compiled domain: typed units, directional relations, model-defined projections, and declared actions, all under a versioned snapshot. A query returns a Selection Plan that records what matched and which constraints applied, so you can log it, diff it between releases, and write tests against it.
02 Does AOE ship an ontology I have to adopt?
No. The engine fixes the declaration meta-schema and the stable IR. Types, fields, relations, retrieval profiles, and actions come from external Model Packages. Frontend Design, Security, Backend, and the mobile corpora in the registry are reference packages you can read, replace, or ignore.
03 What does a verified snapshot actually guarantee?
Every release carries a manifest and a content digest bound to a model lock. Before serving, the runtime recomputes identity and content, so a host can check that the snapshot is the release its corpus expects and that it is complete. A changed file fails the release instead of being served quietly.
04 Can an agent change state, or only read?
Both, through separate contracts. Queries and plans are read-only. An action validates inputs, principal, capability, preconditions, provider binding, side-effect class, idempotency, and policy, then returns an effect plan before running anything. Execution waits for any required approval, and the run and its evidence append to the event store. Deny is the default.
05 Which clients can connect today?
Any MCP-capable agent can mount a package directly. Applications can embed the SDK in-process or call the HTTP transport from another service. All three share the same query, plan, and action contracts, so the choice is about deployment rather than semantics.
06 What does it cost to keep a package current?
Editing sources and rebuilding. Generated files such as the index, manifest, and model lock are never hand-edited; a build regenerates them atomically so the digest and provenance stay trustworthy. Model and corpus releases carry their own versions, and a corpus declares the model range it was built for.
07 Is AOE ready for production?
AOE is 0.2 and Apache-2.0 licensed. The package, snapshot, query, and action contracts described in these docs are current, and the registry here is a static discovery site rather than a hosted registry service. Read the release notes before you depend on a contract.
Start with your domain
Give your agent a domain it can name.
Start with a small model and a handful of units. In a few minutes you have a runtime you can query, inspect, and govern.