Server Configuration

Relevant source files

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

• ethos-core/src/config.rs
• ethos-server/src/main.rs
• ethos-server/src/http.rs
• ethos-cli/src/main.rs
• README.md
• migrations/001_initial_schema.sql

Ethos is configured via a centralized configuration system that manages various subsystems including database connectivity, semantic embedding backends, memory consolidation logic, and communication interfaces. The configuration is primarily driven by an ethos.toml file, supplemented by environment variables and CLI arguments for runtime flexibility.

The configuration architecture ensures that the neuromorphic memory engine can operate with specific thresholds for memory decay, importance-based consolidation, and high-performance vector searching.

Sources: README.md:162-184, ethos-core/src/config.rs:4-16

Configuration Loading and Initialization

The server initializes by loading configuration from a TOML file (defaulting to ethos.toml) and optionally loading secrets from a .env file. The EthosConfig struct serves as the primary data container, organized into logical sub-modules for each system component.

Core Subsystem Configurations

The configuration is split into several functional areas, each defined in ethos-core/src/config.rs.

Database and Service Config

The database configuration manages the connection string and pool limits, while the service config defines the Unix domain socket path used for local IPC.

Option	Type	Description
database.url	String	PostgreSQL connection string with pgvector support.
database.max_connections	u32	Maximum size of the SQLx connection pool.
service.socket_path	String	Path to the Unix domain socket (default: /tmp/ethos.sock).
service.log_level	String	Tracing log level (INFO, DEBUG, etc.).

Sources: ethos-core/src/config.rs:24-33, README.md:124-131

Embedding Subsystem

Ethos supports multiple embedding backends, primarily Gemini, to convert memory content into 768-dimensional vectors.

Memory Consolidation and Decay

The Consolidation engine promotes episodic memories to semantic facts based on importance and retrieval frequency. The Decay system implements Ebbinghaus forgetting curves.

Feature	Param	Default	Source
Consolidation	importance_threshold	0.8	ethos-core/src/config.rs:61
	retrieval_threshold	5	ethos-core/src/config.rs:63
	interval_minutes	15	ethos-core/src/config.rs:59
Decay	base_tau_days	7.0	README.md:85
	ltp_multiplier	1.5	README.md:86

Sources: ethos-core/src/config.rs:48-65, ethos-core/src/config.rs:80-87

Communication Interfaces

Ethos exposes two primary interfaces for interaction: a Unix Domain Socket (IPC) and an optional HTTP REST API.

IPC Server (Unix Socket)

Used for high-speed, local communication between OpenClaw hooks and the memory engine. It uses Little-Endian (LE) framed MessagePack payloads.

• Socket Path: Configured via service.socket_path.
• Protocol: 4-byte LE length prefix followed by MessagePack.

Sources: README.md:144-153, ethos-core/src/config.rs:25

HTTP REST API

A secondary interface for remote queries and CLI tool integration (e.g., ethos-cli). It is enabled via the http configuration block.

HTTP Configuration Table

Option	Type	Default	Description
http.enabled	bool	true	Enables the Axum-based REST API.
http.host	String	"127.0.0.1"	Bind address for the HTTP server.
http.port	u16	8766	Listening port for the API.

Sources: ethos-core/src/config.rs:94-103

Runtime Configuration via CLI

The ethos-server and ethos-cli binaries accept arguments that override or supplement file-based configuration.

• ethos-server:
  • --config <PATH>: Specify a custom TOML config file.
  • --health: Performs a database and pgvector connection check then exits.
• ethos-cli:
  • --server <URL>: Set the target HTTP API address (overrides ETHOS_HTTP_URL env).
  • --json: Format search output for QMD wire-protocol compatibility.

Sources: ethos-server/src/main.rs:11-17, ethos-cli/src/main.rs:28-40

Database Schema Constraints

Configuration is intrinsically tied to the PostgreSQL schema, particularly for vector search.

• Vector Dimensions: Fixed at 768 dimensions for Gemini embeddings.
• Search Index: HNSW index using vector_cosine_ops.
• Extensions: Requires vector and pg_trgm.

Sources: migrations/001_initial_schema.sql:15-17, migrations/001_initial_schema.sql:167-171

Ethos provides a robust configuration framework that balances high-level service settings (HTTP/IPC) with granular neuromorphic parameters (decay constants and consolidation thresholds) to manage AI agent memory effectively.