Async Task Management

Relevant source files

The following files were used as context for generating this wiki page:

• ethos-server/src/main.rs
• ethos-server/src/subsystems/consolidate.rs
• ethos-server/src/subsystems/decay.rs
• ethos-server/src/http.rs
• ethos-core/src/config.rs
• README.md

Ethos utilizes an asynchronous task management system built on the Tokio runtime to handle long-running memory maintenance operations without blocking primary conversation ingestion or retrieval. The architecture relies on non-blocking background loops and fire-and-forget IPC hooks to ensure high availability and low latency for AI agent interactions.

Key background tasks include the Consolidation Engine, which promotes episodic memories to semantic facts, and the Decay Engine, which handles the natural fading of unimportant information via Ebbinghaus decay. These tasks are decoupled from the synchronous request-response flow of the Unix socket and HTTP servers, allowing the system to maintain "neuromorphic" memory properties—such as Long-Term Potentiation (LTP)—independently of immediate user requests.

Sources: README.md:46-52, ethos-server/src/main.rs:75-103

Background Maintenance Loops

The core of Ethos's background management is the consolidation loop, which is spawned during server startup. This loop manages the transition of short-term episodic traces into long-term structured knowledge.

Consolidation and Decay Loop

The consolidation loop runs on a configurable interval (defaulting to 15 minutes). It is governed by a tokio::time::interval ticker and listens for a broadcast shutdown signal to ensure graceful termination. To minimize performance impact, the loop incorporates an "idle check" mechanism that prevents heavy maintenance during active conversation periods.

The diagram above illustrates the sequential execution of maintenance tasks triggered by a periodic timer, subject to system resource availability.

Sources: ethos-server/src/subsystems/consolidate.rs:77-111, ethos-server/src/main.rs:81-94

System Idle Detection

The system is considered idle based on two primary metrics:

1. Database Activity: No session_events have been created within a specific idle_threshold_seconds (defined in ConsolidationConfig).
2. CPU Load: The 1-minute load average (retrieved from /proc/loadavg on Linux systems) must be below a cpu_threshold_percent.

Sources: ethos-server/src/subsystems/consolidate.rs:118-154, ethos-core/src/config.rs:43-52

Component Architecture

The task management system is distributed across several subsystems that interact with the PostgreSQL database.

Component	Responsibility	Relevant Files
Consolidation Subsystem	Scans unconsolidated episodes and extracts structured facts using regex-based pattern matching.	consolidate.rs
Decay Subsystem	Recalculates salience scores for all memory types and marks items below the prune_threshold as pruned.	decay.rs
HTTP Server	Provides an Axum-based REST API for manual task triggering (e.g., /consolidate).	http.rs
IPC Server	Handles asynchronous ingestion where Gemini API calls for embeddings occur in background tasks.	README.md, main.rs

Sources: ethos-server/src/subsystems/consolidate.rs:17-30, ethos-server/src/subsystems/decay.rs:41-75, ethos-server/src/http.rs:11-20

Manual Task Orchestration

While most tasks are automated, the system provides mechanisms for manual orchestration via the HTTP and IPC interfaces. The trigger_consolidation function allows a consolidation cycle to run immediately, bypassing the idle check.

The sequence diagram shows the flow of a manually triggered consolidation request through the HTTP API.

Sources: ethos-server/src/http.rs:188-208, ethos-server/src/subsystems/consolidate.rs:65-75

Task Configuration

Maintenance tasks are configured through the ethos.toml file, which maps to the EthosConfig structure.

Parameter	Type	Default	Description
interval_minutes	u64	15	Time between consolidation/decay attempts.
idle_threshold_seconds	u64	60	Required period of inactivity before maintenance begins.
cpu_threshold_percent	u8	80	Maximum CPU load allowed for maintenance tasks.
importance_threshold	f32	0.8	Minimum importance required for an episode to be promoted.
base_tau_days	f64	7.0	Base time constant for Ebbinghaus decay.
prune_threshold	f64	0.05	Salience/Confidence level below which a memory is "forgotten."

Sources: ethos-core/src/config.rs:43-52, ethos-core/src/config.rs:80-86

Error Handling and Graceful Degradation

The async task system is designed for "graceful degradation." As noted in the project documentation, background tasks like the Gemini embedding pipeline or maintenance loops are designed to be "fire-and-forget." If the Ethos server is down or a background task fails, the main AI conversation delivery remains unblocked, often falling back to empty context files.

Internally, the run_consolidation_loop uses tracing to log errors at the ERROR or WARN level without crashing the main server thread. For example, if a decay sweep fails during a consolidation cycle, it is treated as a "non-fatal" error.

Sources: README.md:54, ethos-server/src/subsystems/consolidate.rs:96-102