Skip to main content

Source tree

This page is a guided map of the AION Agents repository: which folder holds what, and why the code is split that way. It is meant for developers who need to find where a feature lives before changing it, and for IT staff who want to know which folders are configuration and which are code. For the runtime flow (what happens when a message arrives) start from the architectural overview.

Separation principles​

This section explains why the code is organized into these folders, describing the key principles of modularity and separation of concerns of the system.

Standard vs Local Structure (_std sync)​

To ensure maximum configuration flexibility and process isolation without polluting the Git repository, AION Agents uses a pattern of splitting sensitive folders for local environment and runtime:

  • config_std/ and mcp_servers_std/: They are the official reference folders, tracked by Git. They contain default templates for configurations, agent profiles, skills, and built-in MCP servers.
  • config/ and mcp_servers/: They are the active directories at runtime, completely ignored by Git (.gitignore). They are synchronized starting from their respective standard templates using the scripts:
    • sync_config.py: Populates config/ keeping local overrides intact (e.g., mcp_registry.local.yaml).
    • sync_mcp_servers.py: Synchronizes MCP server source files locally.
    • Automatic synchronization occurs at startup in production (if AION_SYNC_ON_BOOT=1 in containers) or via setup and upgrade scripts (setup-aion-env.sh, upgrade-aion.sh).

Complete directory layout​

src/ — Core Python Runtime​

The directory src/ houses the agent's Python runtime, divided into well-defined areas of responsibility:

src/api/ — HTTP Boundary (FastAPI)​

The APIs represent the "boundary" that separates the agent's business logic from external clients. For this reason, routes must not contain complex logic, but delegate to runtime modules.

PathRoleRationale
main.pyHTTP entrypoint and initializationConfigures the lifespan of the FastAPI server, starts the unified databases, and defines basic public endpoints (/health, /profiles).
chat_ui.pySSE endpoint for Chat ClientManages Server-Sent Events (SSE) connections and the reception of asynchronous/streaming messages from the chat.
orchestration.pyInternal orchestration APIsManages approval, rejection, and modification of execution plans for tasks.
plan_execution.pyTask and execution statusMonitoring the status of current executions for active plans.
cron_admin.py & cron_user.pyCron Job scheduling APIsEndpoints to create, monitor, and delete periodic/scheduled tasks of the agent.
research.pyDeep Research APIsSupport for external queries for running deep research cycles.
history.pySTM & FTS data layerProvides services to retrieve chat history and full-text searches on old messages.
session_uploads.pyFile upload managementUpload attachments to uploads/; triggers PDF auto-ingest and legacy .doc → .docx conversion on the API host.
admin.pyAdministrative CRUD dashboardEndpoints for centralized management of profiles, users, sessions, and installed skills.
admin_profile_memory.pySOUL/MEMORY/USER CRUDManagement of persistent profile files for agents (legacy endpoints).
admin_query_memory.py & ltm_admin.pyLong-term memory search and debugAllows administrators to inspect information extracted in LTM and semantic metadata.
src/api/v1/REST v1 routers and controllersCollection of endpoints for version 1 of the APIs, including: chat.py (streaming), conversations.py (sessions), files.py (file management), mcp_integrations.py (credentials and per-user integrations), navigation_memory.py, query_memory.py and steps.py (intermediate steps of tools).

src/runtime/ — The agent engine​

The package src/runtime/ contains the internal logic of the agent's execution cycle. It resolves alignment with language models, coordinates execution plans, and implements background daemons.

src/memory/ — Data Persistence Patterns​

The memory runtime coordinates data persistence, both long-term memory (LTM, facts kept across conversations) and short-term memory (STM, the recent turns of the current conversation).

FilePatternDescription
ltm_orchestrator.pyLong-term memory orchestratorPost-turn extraction into Mnemos notes; bridges wake/recall.
stm_consolidator.pyShort-term memory consolidationCleans up and compacts recent conversation turns.
context_compressor.pyContext compressionManages the compression of overall tokens to be sent to the LLM.
llm_extract.pyEntity structuring via LLMPerforms targeted HTTP calls to the LLM to extract semantic keys in JSON format.
project_memory_service.pyProject-scoped Mnemos CRUDREST-backed project notes with membership checks.
user_memory_service.pyUser-scoped Mnemos CRUDREST-backed personal notes of the calling user.
src/memory/sql_query_memory/SQL QueryMemoryCache of validated SQL queries reused across sessions.
src/memory/mnemos/Native LTM backendStore, FTS, hybrid recall (RRF), compress/digest, dream cycle, entity index (optional). See Mnemos docs.
note

MemPalace, the external MCP server previously used for long-term memory and ERP navigation (mempalace_manager.py, navigation_memory_service.py, project_memory_scope.py, db_navigation_mempalace_hooks.py), has been removed and replaced by Mnemos. Legacy .env keys are migrated by scripts/migration/migrate_mempalace_to_mnemos_env.py.

src/learning/ — Evolutionary Features (Experimental)​

This module collects the agent's learning capabilities starting from previous usage sessions.

  • skill_distiller.py: Dynamically generates reusable skill packages when observing chains of actions that successfully complete a task.
  • skill_view_metrics.py: Computes efficacy and usage frequency metrics to evaluate whether a skill is useful or redundant.
  • nudge.py: Intervenes in the chat UI by suggesting the user try tools or skills in certain situations.
  • skill_patcher.py: Updates or corrects saved skills following environmental changes.
  • dedup.py: Deletes duplicate skills by calculating the semantic similarity of embeddings.

src/security/ — Security and Control-Plane​

Ensures access control and system integrity during tool calls.

src/tools/ — Integrated Native Wrappers​

Contains the Python wrappers of the tools exposed to the agent.

src/a2a/ and src/plan_execution/ — Inter-agent protocol and Execution​

  • src/a2a/: Implements the communication and delegation protocol between agents.
    • protocol.py: Defines standard data models for interaction (ExecutionPlan, ExecutionTask, TaskStatus).
    • plan_markdown.py: Manages the translation of plans into readable Markdown tables.
  • src/plan_execution/:
    • handler.py: Coordinates the orchestration of tasks and intermediate progress.

mcp_servers/ — MCP Process Pool​

MCP (Model Context Protocol) servers are executed as stdio processes external to the main Python runtime for security, modularity, and language independence reasons.

Synchronization and startup​

The AION runtime does not start the servers directly from mcp_servers_std/ but executes the binaries and scripts inside the local mcp_servers/ folder (populated via sync_mcp_servers.py).

Standard MCP servers (mcp_servers_std/)​

Below is the list of standard submodules ready for use:

  1. aion_subagents/: Performs spawning and communication with per-session hierarchical sub-agents.
  2. charts/: Calculates and returns structured data formats to display area, line, or bar charts in the chat UI.
  3. code_executor/: Provides an isolated sandbox for script execution.
  4. geocoding/: Forward geocoding via OpenStreetMap Nominatim.
  5. grafana/: Allows querying Grafana monitoring dashboards.
  6. legacy_rag/: Bridge for backward compatibility with RAG components from previous versions.
  7. mcp_toolbox_for_databases/: Git submodule with Google's MCP Toolbox for Databases (googleapis/genai-toolbox).
  8. ocr_mcp/: Processes PDF files or images, extracting structured text blocks (GPU/CPU heavy).
  9. odoo_mcp_server/: Connector to the Odoo ERP.
  10. orchestration/: Allows third-party agents or sub-agents to interface with the task scheduler.
  11. prometheus/: Query interface for system monitoring metrics.
  12. promo_render/: Generates graphic previews in PNG format starting from HTML or React templates (dashboards and promos).
  13. query_memory/: Maintains the semantic index of successful queries and enables their inter-session retrieval.
  14. session_sandbox/: Controls secure access and filesystem isolation for each chat.
  15. skills_hub/: Manages the alignment of loaded skills in the agent's active profile.
  16. smb_files/: Reads and writes files on company Windows shares with the user's own credentials (see SMB files).
  17. stt_mcp/: Transcribes session audio files (speech-to-text) via a remote OpenAI-compatible Whisper service or local faster-whisper; logic in src/tools/audio_transcribe.py.
note

The former agent_db/ (per-user SQLite databases) and memory/ (mem0_server.py) servers have been removed from mcp_servers_std/.


config/ — Declarative Configuration​

The two configuration levels (config_std/ and config/)​

  • config_std/: Contains the default declarative configuration distributed with the code.
  • config/: Created at runtime (gitignored). Houses active settings modified locally.

Main files in config_std/​

  • fs_policy.example.yaml and fs_policy.dev.yaml: Define the domains and commands executable by the agent within the workspace. Synchronized in config/fs_policy.yaml.
  • mcp_registry.yaml: Declaration of startup parameters (path, environment variables, flags) of all MCP servers. It can be extended by an uncommitted config/mcp_registry.local.yaml file to add local definitions.
  • native_tool_registry.yaml: Configuration listing the native Python tools that can be enabled.
  • profiles/: YAML files containing the system prompt instructions, enabled skills, and tool groups for specific profiles (e.g., data_agent.yaml, infra_sre.yaml, orchestrator.yaml).
  • skills/: Markdown files with YAML frontmatter (e.g., core_protocol.md, db_navigation_map.md) detailing specific procedures read at runtime by skill_registry.py.
note

The config/default.yaml file mentioned in various log and configuration files is not committed to git. Runtime configuration loaders (config.py and llm_router.py) read it only if present, otherwise they fail silently inheriting defaults from code or environment variables.


Deployment and Environment​

Environment variables and .env.example​

All system environment variables are centralized in a single template file .env.example. Unlike other architectures, there is no separate .env.docker.example file: configurations for containers (such as DOMAIN, AION_SYNC_ON_BOOT, ports exposed by Caddy, etc.) are appended directly inside .env.example.

When starting in Docker mode, the installation script copies .env.example directly to local .env before starting docker compose.

docker/ structure​

The directory docker/ collects deployment assets:

  • Dockerfile.backend: Builds the Python 3.13 image with pre-installed system tools like Tesseract (OCR) and Poppler, plus the faster-whisper speech-to-text model downloaded at build time (ARG STT_LOCAL_MODEL).
  • Dockerfile.chat-ui and Dockerfile.admin-ui: Generate the standalone Next.js images.
  • Dockerfile.website: Generates the static Nginx image to serve Docusaurus.
  • Caddyfile: Reverse proxy with path-based balancing (/admin, /api) and automatic SSL certificate generation.
  • nginx-website.conf: File caching configuration for the docs portal.

Frontend Applications and Documentation​

chat-ui/ — Primary Chat Client​

Next.js 16 (React 19) application that manages the main conversation UI with the agent. Uses pnpm for package management.

  • app/: Application routing (App Router).
  • components/: Contains the React conversation components (messages, tool accordions, sidebar for execution plans).
  • lib/: API services to call FastAPI.
  • styles/: Vanilla CSS style sheets for rendering and responsiveness.

admin-ui/ — Administrative Dashboard​

Next.js 16 dashboard for maintenance. Provides the graphical interface to inspect user sessions, configure profiles, and inspect security audit logs.

  • Note: To start it in local development it requires the webpack flag: next dev --webpack -p 3870.

website/ — Documentation Portal​

Docusaurus site hosted in the directory website/. Loads and statically renders the Markdown documentation present in the docs/ directory of the repository.