The keystone of the Airymax runtime: every higher layer ultimately depends on the atomic services provided here. Leaf repository under the agentrt management repo.
Language: English | 简体中文
- Repository:
git@atomgit.com:openairymax/atoms.git - Branch:
feature/official-hubs-01 - Version: 0.1.1 (Airymax foundational release)
atoms is the core system layer of the Airymax agent runtime. It sits at the very bottom of the Airymax cyclic layered architecture, directly above the operating system, and follows a strict microkernel design philosophy: minimize what lives in the core, maximize what can be composed on top. It wraps raw OS resources (CPU, memory, storage, network) into a unified set of agent-runtime primitives — inter-process communication, memory management, task scheduling, time services, system calls, task orchestration, the core runtime loop, and framework integration bridges.
Every module is implemented in C11 and exported through a stable C ABI so the same primitives can be consumed by upper-layer daemons, SDKs, applications, and foreign-language bindings (FFI) with no impedance mismatch. The top-level CMakeLists.txt aggregates every sub-module and exports an INTERFACE target airy_atoms that propagates include paths and compile definitions to consumers.
atoms is the keystone of the entire runtime — every higher layer (cupolas, heapstore, protocols, gateway, daemons) ultimately depends on the atomic services it provides. Within the Airymax 0.1.1 release, the workspace is partitioned into 38 repositories (1 umbrella + 5 management + 29 leaf + 3 top-level); atoms is one of the 7 leaf repositories aggregated by the agentrt management repo, and is itself composed of 7 sub-modules (corekern, coreloopthree, syscall, taskflow, frameworks, memory, memoryrovol).
Class A — Foundational / Atomic.
atoms is the lowest-level leaf repository in agentrt. It is depended upon by every other leaf repo (cupolas, heapstore, protocols, gateway, daemons) and never depends on them in return. Its only intra-agentrt upstream dependency is commons (the shared foundation library). As a Class-A module, atoms guarantees ABI stability within a major version and is the canonical substrate on which the SDK layer ultimately binds back (closing the Airymax cyclic architecture).
atoms/
├── CMakeLists.txt # Top-level build config (INTERFACE lib + subdir aggregation)
├── README.md # This file (English)
├── README_zh.md # Chinese version
├── corekern/ # Microkernel — IPC/Binder, memory, scheduling, time
│ ├── include/ # Public headers (agentrt.h unified entry, ipc.h, mem.h, task.h, are_ipc.h, arena.h, mempool.h, slab.h, tcache.h, oom_handler.h, observability.h, airy_time.h, error.h, refcount.h, platform_core.h, export.h)
│ ├── src/ # Kernel impl (ipc/, mem/, task/, time/, observability/)
│ ├── tests/ # Unit tests
│ └── CMakeLists.txt
├── coreloopthree/ # Core runtime — Cognition / Execution / Memory tri-loop engine
│ ├── include/ # loop.h, cognition.h, execution.h, memory.h, orchestrator.h, multi_agent_collaboration.h, cognitive_evolution.h, compensation.h, hook_*.h, checkpoint_adapter.h, *_adapter.h, *_ops.h
│ ├── src/ # Runtime implementation
│ │ ├── cognition/ # Cognition engine (intent, planning, cooperation, scheduling, evolution)
│ │ ├── execution/ # Execution engine (units, compensating transactions, tracing)
│ │ ├── memory/ # Memory engine (memory service, engine core)
│ │ └── utils/ # Helpers (ID generation, error handling)
│ ├── tests/ # Unit tests
│ └── CMakeLists.txt
├── memory/ # Built-in memory subsystem — pluggable L1+L2 architecture
│ ├── src/memory_provider.h # Provider interface (function-pointer table + capability flags)
│ ├── src/builtin_provider.c # Built-in free provider implementation
│ ├── src/builtin_storage.c # L1 raw storage (filesystem + SQLite)
│ ├── src/builtin_index.c # L2 feature index (FAISS vector search)
│ ├── src/builtin_retrieval.c # Retrieval strategy implementation
│ └── CMakeLists.txt
├── memoryrovol/ # Commercial memory bridge — L1-L4 PRO (independent repo)
│ ├── src/airy_mr_force_includes.h
│ └── CMakeLists.txt
├── syscall/ # Syscall layer — 5 categories + 4 protection rings
│ ├── include/ # syscalls.h, airy_sandbox.h public interface
│ ├── src/ # Syscall impl (sandbox_permission.h, sandbox_utils.h, sandbox_quota.h, sandbox_internal.h, circuit breaker, rate limiter)
│ ├── tests/ # Unit tests
│ └── CMakeLists.txt
├── taskflow/ # Task-flow engine — Pregel superstep DAG orchestration
│ ├── include/ # taskflow.h, taskflow_types.h, taskflow_advanced.h, taskflow_integration.h, workflow_patterns.h, pregel_engine.h, graph_engine.h
│ ├── src/ # Engine impl (core, graph, Pregel, workflow patterns)
│ ├── tests/ # Unit tests
│ └── CMakeLists.txt
└── frameworks/ # External AI framework adapter bridge — industry base driver
├── include/ # airy_frameworks.h adapter interface + registry API
├── src/ # Thread-safe registry + instance lifecycle management
└── CMakeLists.txt
| Component | Path | Core Capability | Language |
|---|---|---|---|
| CoreKern | corekern/ |
Microkernel: IPC/Binder, memory management (arena/mempool/slab/tcache), task scheduling, time service, OOM handling, observability | C11 |
| CoreLoopThree | coreloopthree/ |
Cognition loop, execution loop, memory loop; compensating transactions; cognitive evolution; multi-agent collaboration; hooks; checkpointing; orchestrator | C11 |
| Memory | memory/ |
L1 raw storage (filesystem + SQLite) + L2 keyword/vector index (FAISS); pluggable-provider architecture (free built-in provider) | C11 |
| MemoryRovol | memoryrovol/ |
L1-L4 full commercial memory; bridges built-in Memory via weak-symbol bridge (opt-in via AIRY_WITH_MEMORYROVOL=ON) |
C11 |
| Syscall | syscall/ |
5 syscall categories (task/memory/session/telemetry/agent) + Skill management; 4 protection rings; sandbox + circuit breaker + rate limiter | C11 |
| TaskFlow | taskflow/ |
Pregel superstep model, DAG orchestration, workflow patterns, graph engine, checkpoint fault tolerance | C11 |
| Frameworks | frameworks/ |
External AI framework adapter bridge; thread-safe registry; drives LangChain/AutoGen/CrewAI/Semantic Kernel/LlamaIndex | C11 |
┌──────────────────────────────────────────────┐
│ Applications (OpenLab) │
├──────────────────────────────────────────────┤
│ Ecosystem (Toolkit / SDK) │
├──────────────────────────────────────────────┤
│ Daemon Services │
├──────────────────────────────────────────────┤
│ ★ atoms (Core System Layer) ★ │
├──────────────────────────────────────────────┤
│ Operating System / Hardware │
└──────────────────────────────────────────────┘
┌─────────────┐
│ CoreKern │
│ (microkernel)│
└──────┬──────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────────┐
│ Syscall │ │ TaskFlow │ │ CoreLoopThree │
│ │◄──┤ │◄──┤ (tri-loop) │
└───────────┘ └───────────┘ └───────┬───────┘
┌───────────┐ │
│ Memory │◄──────────────────┘
│ (builtin) │
└─────┬─────┘
│ (weak-symbol bridge)
┌───────────┐
│ Memory │
│ Rovol │ (commercial, opt-in)
└───────────┘
┌──────────────────────────────────────┐
│ Frameworks │
│ External AI framework adapter bridge │
└──────────────────────────────────────┘
Design principles: microkernel (only 4 atomic capabilities — IPC, memory, scheduling, time), determinism (priority inheritance + resource reservation), composability (C ABI + FFI), lock-free hot paths, zero-copy IPC, async-first I/O, hardened release builds (stack protection, _FORTIFY_SOURCE, PIE, RELRO).
commonsis the foundation for all agentrt modules. atoms is no exception: every sub-module consumescommonsutilities.
| Dependency | Role |
|---|---|
| commons | Foundational shared utilities consumed by every atoms sub-module: logging, sync, platform, error, types, config_unified, observability, ipc, io, cache, cost, memory, string, token, network, security, resource, uuid |
| OS / hardware | POSIX / Windows kernel primitives (threads, shared memory, timers, file system) |
| External (optional) | cJSON (JSON), SQLite (L1 storage), FAISS (L2 vector index) — auto-detected by the umbrella CMake |
| MemoryRovol (optional) | Commercial L1-L4 memory provider; bridged via weak symbols when AIRY_WITH_MEMORYROVOL=ON |
| Consumer | What they use |
|---|---|
| cupolas | CoreKern IPC + Syscall sandbox as the substrate for the 4-layer safety dome |
| heapstore | CoreKern memory primitives (arena/mempool/slab) + TaskFlow for heap persistence |
| protocols | CoreKern IPC buffer / message primitives (are_ipc.h) to carry the AgentsIPC L2 wire format |
| gateway | CoreKern scheduler + Syscall entry as the runtime substrate for the gateway daemon |
| daemons | All 12 runtime daemons are built on CoreLoopThree + Syscall + TaskFlow + Memory |
| External frameworks | Frameworks adapter lets LangChain / AutoGen / CrewAI / Semantic Kernel / LlamaIndex plug into the Airymax kernel |
atoms is built with CMake. The top-level CMakeLists.txt aggregates every sub-module and exports an INTERFACE target airy_atoms that propagates include paths and compile definitions to consumers.
# Standard release build (out-of-source, enforced by BAN-33)
cmake -S . -B /tmp/atoms-build -DCMAKE_BUILD_TYPE=Release
cmake --build /tmp/atoms-build --parallel $(nproc)
# Enable the commercial MemoryRovol bridge
cmake -S . -B /tmp/atoms-build -DAIRY_WITH_MEMORYROVOL=ON
cmake --build /tmp/atoms-build
# Enable unit tests
cmake -S . -B /tmp/atoms-build -DBUILD_TESTS=ON
ctest --test-dir /tmp/atoms-build --output-on-failure
# Install
cmake --install /tmp/atoms-build --prefix /opt/airymaxBuild artifacts:
airy_core— static library for CoreKernairy_coreloopthree,airy_syscall,airy_taskflow,airy_frameworks,airy_memory— per-module static librariesairy_atoms— INTERFACE target that propagates include paths and links the umbrellaairy_compile_defsdefinitions to consumers
Headers are installed under include/agentrt/{corekern,coreloopthree,syscall,frameworks}, CMake package config files under lib/cmake/AgentRT.
All modules follow semantic versioning (MAJOR.MINOR.PATCH) and guarantee ABI compatibility within the same MAJOR version. Module API versions are defined in their respective public headers:
- CoreKern:
AIRY_CORE_API_VERSION(1.0.0) — entry headercorekern/include/agentrt.h - CoreLoopThree:
LOOP_API_VERSION(1.0.0) — entry headercoreloopthree/include/loop.h - Syscall:
SYSCALL_API_VERSION(1.0.0) — entry headersyscall/include/syscalls.h - TaskFlow: entry header
taskflow/include/taskflow.h - Frameworks: entry header
frameworks/include/airy_frameworks.h - Memory: provider interface header
memory/src/memory_provider.h
Key public surfaces: agentrt.h (unified entry), ipc.h / are_ipc.h (IPC), mem.h / arena.h / mempool.h / slab.h / tcache.h (memory), task.h (scheduling), airy_time.h (time), cognition.h / execution.h / memory.h (tri-loop), syscalls.h / airy_sandbox.h (syscall + sandbox), taskflow.h / pregel_engine.h / graph_engine.h (task-flow), airy_frameworks.h (adapters).
Copyright (c) 2025-2026 SPHARX Ltd. All Rights Reserved.
This module is dual-licensed under the terms of either:
- GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later), or
- Apache License, Version 2.0 (Apache-2.0)
SPDX-License-Identifier: AGPL-3.0-or-later OR Apache-2.0
You may select either license to comply with. The AGPL-3.0-or-later terms apply by default; the Apache-2.0 alternative is provided for downstream integration scenarios (e.g., closed-source or proprietary distribution) that the AGPL does not accommodate.