Deployment Guide

Relevant source files

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

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

Ethos is a neuromorphic memory engine designed as a standalone service to provide long-term memory for AI agents. This guide details the architectural requirements, environment setup, database configuration, and service orchestration necessary to deploy Ethos in a production or development environment.

The deployment focuses on three primary components: the PostgreSQL database with vector support, the ethos-server (Rust) which handles IPC and HTTP traffic, and the ethos-cli for administrative and tool-based interaction.

System Requirements

Ethos requires a modern Linux environment (Ubuntu 25.10+ recommended) or macOS for proper operation of its dependencies.

Requirement	Version	Notes
Rust + Cargo	1.75+	Required for building from source
PostgreSQL	16+	17 recommended for native performance
pgvector	0.8.0+	Supports HNSW indexing for 768-dim embeddings
Node.js	18+	Required for TypeScript ingest hooks
Gemini API Key	—	Required for asynchronous embedding pipeline

Sources: README.md:108-116, migrations/README.md:5-15

Database Deployment

Ethos utilizes PostgreSQL with the pgvector and pg_trgm extensions. The database stores episodic traces, semantic facts, and high-dimensional vectors.

1. Installation and Extension Setup

The vector extension must be created by a superuser. Trigram support is required for fast text searching on content columns.

# Ubuntu 25.10 setup
sudo apt install postgresql-17 postgresql-17-pgvector
sudo -u postgres psql -d ethos -c "CREATE EXTENSION IF NOT EXISTS vector;"

Sources: migrations/README.md:7-15, migrations/001_initial_schema.sql:15-16

2. User and Schema Provisioning

A dedicated ethos user should be created with restricted privileges.

sudo -u postgres createuser --no-superuser --no-createdb --no-createrole ethos
sudo -u postgres psql -c "ALTER USER ethos WITH PASSWORD 'your_password';"
sudo -u postgres createdb --owner=ethos ethos

Sources: migrations/README.md:21-30

3. Schema Migrations

Migrations define the core memory tables, including the memory_vectors table which utilizes an HNSW index for cosine similarity search.

Service Configuration

The Ethos server is configured via a TOML file (ethos.toml) and environment variables for sensitive secrets like the Google Gemini API key.

Configuration Structure

The EthosConfig struct defines the operational parameters for various subsystems including decay, consolidation, and retrieval.

Section	Key	Type	Description
service	socket_path	String	Path to the Unix domain socket (default: /tmp/ethos.sock)
database	url	String	PostgreSQL connection string
embedding	gemini_model	String	Model used for 768-dim embeddings
http	port	u16	Port for the REST API (default: 8766)
decay	base_tau_days	f64	Base half-life for Ebbinghaus decay

Sources: ethos-core/src/config.rs:5-95, README.md:144-151

Environment Variables

Secrets should be stored in a .env file or exported to the environment:

• GOOGLE_API_KEY: Required for Gemini embeddings.
• ETHOS_HTTP_URL: Used by ethos-cli to locate the server.

Sources: README.md:140-142, ethos-cli/src/main.rs:25

Service Execution and Orchestration

systemd Integration

For production environments, Ethos should run as a background service. A user-level systemd unit is the recommended deployment method.

[Service]
Type=simple
WorkingDirectory=/path/to/ethos
ExecStart=/path/to/ethos/target/release/ethos-server
EnvironmentFile=/path/to/ethos/.env
Restart=on-failure

Sources: README.md:175-191

Server Subsystems

When the binary starts, it initializes several concurrent background tasks:

Verification and Health Checks

Post-deployment verification can be performed using the built-in health flags or the ethos-cli.

1. Binary Health Check

The server provides a --health flag to verify database connectivity and pgvector extension availability.

./ethos-server --health
# ✅ PostgreSQL connected: PostgreSQL 17.x
# ✅ pgvector version: 0.8.0

Sources: ethos-server/src/main.rs:53-73, README.md:166-170

2. API Health Check

The HTTP server exposes a /health endpoint (default port 8766) which returns JSON status.

curl http://127.0.0.1:8766/health

Sources: ethos-server/src/http.rs:98-124

3. CLI Status

The ethos-cli can be used to check server status from the command line.

ethos-cli status

Sources: ethos-cli/src/main.rs:172-198

Conclusion

Deploying Ethos involves setting up a specialized PostgreSQL environment with vector support and configuring a Rust-based server that manages multiple background subsystems for memory consolidation and decay. Once deployed, the system exposes both a high-performance Unix socket for local ingest and a REST API for remote semantic search and administration.