AIMON Core

AIMON is a ReAct (Reasoning and Acting) agent framework for Java, designed for building autonomous LLM-powered agents. While it ships with operations-focused defaults (alert triage, root cause analysis, runbook execution), the core framework is general-purpose and can be embedded in any Java application.

Project status: 0.2.x — public API may change between minor versions until 1.0. See CHANGELOG.md for release notes, docs/project/api-stability.md for what 0.x does and does not promise, and docs/project/roadmap.md for what 1.0 is waiting on.

• ReAct loop — iterative reason → act → observe cycle with 13 pluggable hook points
• Multi-agent orchestration — delegate to sub-agents, or script deterministic multi-agent workflows
• Pluggable LLM providers — OpenAI and Anthropic out of the box; add your own via LlmClient
• Skill system — reusable Markdown-based knowledge packages teach agents domain tasks
• Tool ecosystem — Read/Write/Edit/Grep, Bash, WebSearch/WebFetch, Task, Todo, Browser (Playwright), Sandbox (Docker/Kubernetes), and custom tools
• Persistent sessions — pluggable session storage (Redis, PostgreSQL, MongoDB, or in-memory) with multi-node routing
• Long-term memory — observations accrue into derived representations across sessions
• Knowledge & RAG — keyword store built in, OpenSearch backend optional, plus an LLM wiki
• Distributed scheduling — Quartz-based scheduler for clustered cron tasks
• Virtual filesystem — abstract VFS with local, GridFS, and S3 backends
• Sandboxed execution — run untrusted shell commands in Docker or Kubernetes pods
• Observability — execution tracing with redaction, LLM usage/cost metering, streamed execution events

This is a multi-module Gradle project. The framework core is in aimon-core; everything else is opt-in.

Agent memory itself is in aimon-core: the PeerMemory SPI, the store-backed default backend, and its node-local stores (in-memory and file-backed JSONL, at.aimon.core.memory.file). A distributed memory backend is a separate service consumed through PeerMemory — see aimon-memory, whose aimon-memory-client implements that SPI over HTTP.

Two families of agent tool are built and released separately. Both were part of this repository through 0.2.4 under at.aimon.core:*; those artifacts remain on Maven Central and keep working.

The SPIs those backends implement (SessionRecordStore, SessionLeaseStore, SessionInbox, SessionSignalBus, IdempotencyStore) live in aimon-core under at.aimon.core.agent.session.*, so a distributed backend needs aimon-core alone — not aimon-session-routing.

• Java 17 or higher
• An LLM API key — OPENAI_KEY or ANTHROPIC_KEY

Add aimon-core and at least one LLM provider:

// build.gradle.kts
dependencies {
    implementation("at.aimon.core:aimon-core:0.2.0")
    implementation("at.aimon.core:aimon-llm-openai:0.2.0")
}

<!-- pom.xml -->
<dependency>
    <groupId>at.aimon.core</groupId>
    <artifactId>aimon-core</artifactId>
    <version>0.2.0</version>
</dependency>
<dependency>
    <groupId>at.aimon.core</groupId>
    <artifactId>aimon-llm-openai</artifactId>
    <version>0.2.0</version>
</dependency>

git clone https://github.com/kangwoo/aimon-core.git
cd aimon-core
OPENAI_KEY=sk-... ./gradlew :aimon-cli:run

The key goes on the command rather than being exported, on purpose: while a provider key is exported, ./gradlew test and checkAll in that shell can run the live-API tests too, and those calls bill — see Live-API tests.

Or build a fat JAR:

./gradlew :aimon-cli:shadowJar
java -jar modules/aimon-cli/build/libs/aimon-cli-*.jar

The supported path is aimon-spring-boot-starter: three properties (aimon.workspace.root, aimon.llm.api-key, aimon.agent-defaults.default-agent), one injected bean (AimonSessions), and a turn runs. Hosts that are not Spring Boot assemble the same stack from aimon-bootstrap.

See docs/getting-started/embedding-agent-in-application.md — the starter path, the property tree, the four scopes, multi-instance deployment, and an appendix for wiring OrcaAgentExecutor by hand. A working application lives in samples/aimon-sample-app.

The CLI reads YAML configuration. Default location: modules/aimon-cli/src/main/resources/default-config.yaml.

llm:
  provider: "openai"          # "anthropic" also changes baseUrl and agent.name (CLI guide, docs/getting-started)
  baseUrl: "https://api.openai.com/v1"
  apiKey: "${OPENAI_KEY}"     # ${ENV} interpolation supported
  model: "gpt-5.1"
  timeout: 60

agent:
  name: "default"

cli:
  colorOutput: true
  showIterations: true
  showToolCalls: true
  streaming: true

Run with a custom config:

./gradlew :aimon-cli:run --args="-c /path/to/config.yaml"

• Type a request and press Enter
• End a line with \ for multi-line input
• /quit or /exit — exit the REPL
• /help, /commands — list available commands
• /clear — clear the conversation history
• /compact — compact the conversation to reclaim context
• /status, /agents, /skills — inspect the running system
• /pending, /approve, /deny, /revoke — skill approval flow
• Ctrl+C — interrupt the current operation
• Ctrl+D — exit

Agents are defined as Markdown files with YAML frontmatter:

---
name: my-agent
maxIterations: 10
model:
  name: gpt-4o-mini
  temperature: 0.5
  maxTokens: 40000
variables:
  language: Java
  tools: ["Read", "Write", "Bash", "Grep"]
---

# System Prompt
You are a helpful assistant specialized in ...

Place definitions under modules/aimon-cli/src/main/resources/agents/ (or your own resource path when embedding).

Skills package reusable knowledge as Markdown + supporting files:

skill-name/
├── SKILL.md        # Frontmatter (name, description, allowed-tools) + system prompt
├── root-files/     # Files materialized into the agent's working directory
├── scripts/        # Executable scripts
├── references/     # Documentation
└── assets/         # Templates and static resources

Example SKILL.md:

---
name: alert-triage
description: Analyze and triage operational alerts
version: 1.0.0
allowed-tools:
  - Read
  - Grep
  - Bash
---

# Alert Triage Process
1. Assess severity and impact
2. Gather relevant context
3. Identify potential root causes

Skills live under <workspace>/skills/. The bundled ops-agent workspace is at modules/aimon-cli/src/main/resources/workspaces/ops-agent/.

public class GreetTool extends AbstractTool {

    public GreetTool() {
        super("Greet",
              "Greets the given name.",
              Map.of(
                  "type", "object",
                  "properties", Map.of(
                      "name", Map.of("type", "string", "description", "Name to greet")
                  ),
                  "required", List.of("name")
              ));
    }

    @Override
    public ToolResult execute(ToolInput input, ToolContext context) {
        try {
            String name = input.getRequiredString("name");
            return ToolResult.success("Hello, " + name + "!");
        } catch (Exception e) {
            return ToolResult.error(e.getMessage());
        }
    }
}

See docs/features/tool/tool-development-guide.md for the full pattern (error handling, schema, permission system).

./gradlew build                    # Build everything
./gradlew test                     # Run all tests
./gradlew :aimon-core:test         # Tests for a single module
./gradlew format                   # Apply Spotless (Eclipse formatter)
./gradlew checkAll                 # format check + Checkstyle + unit tests (pre-commit verification)

Quality tooling:

• Spotless with Eclipse formatter (config/eclipse/eclipse-formatter.xml)
• Checkstyle on main sources (config/checkstyle/checkstyle.xml)
• JaCoCo code coverage
• JUnit 5 + AssertJ + Mockito + Testcontainers for tests

┌─────────────────────────────────────────────────────────────────┐
│                    User / Application                            │
└───────────────────────────┬──────────────────────────────────────┘
                            │
                            ▼
                ┌────────────────────────┐
                │  LiveSession (REPL     │
                │  or programmatic API)  │
                └───────────┬────────────┘
                            │
                            ▼
        ┌────────────────────────────────────────┐
        │  OrcaAgentExecutor (ReAct loop)        │
        │   build prompt → call LLM → run tools  │
        │   → loop until done                    │
        └──────┬──────────────────────────┬──────┘
               │                          │
               ▼                          ▼
        ┌─────────────┐          ┌─────────────────────┐
        │  LlmClient  │          │ ToolExecutionMgr    │
        │  (OpenAI /  │          │  (Read, Write, Bash,│
        │  Anthropic) │          │   Browser, custom…) │
        └─────────────┘          └─────────────────────┘

The documentation site is at https://kangwoo.github.io/aimon-core/. Start at docs/README.md — what AIMON is, how to run it, how a turn loops, and where to go next. Docs are organized by feature, not by reader role.

• docs/overview/features.md — feature catalog: what aimon-core can do, where each entry point lives, and whether it is built in or a separate module
• docs/overview/ — architecture reference, glossary, scope/lifetime model
• docs/getting-started/ — embedding AIMON, annotated integration reference
• docs/features/ — per-feature guides (tools, skills, hooks, sessions, workflows, memory, …)
• docs/references/ — Hooks specification, AgentSkills specification
• docs/design/ — design documents and rationale
• docs/migration/ — version migration guides
• docs/project/ — roadmap, API stability, SOLID principles, documentation rules, publishing

Note: under docs/ Korean is canonical and English translations are *.en.md, served under /en/ on the site. A page without a translation yet falls back to the Korean original rather than 404ing, so the site is always whole.

This is an early-stage project under active development. The public API may change between 0.x minor versions; we follow Semantic Versioning starting at 1.0.

See CHANGELOG.md for release notes.

Contributions are welcome — please read CONTRIBUTING.md before opening a pull request, and note our Code of Conduct. MAINTAINERS.md says who reviews, how long that usually takes, and how to become a maintainer.

To report a security vulnerability, see SECURITY.md.

Licensed under the Apache License 2.0.