Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
Ethos is a neuromorphic memory engine designed to provide AI agents with long-term persistent memory. The installation process involves setting up a PostgreSQL database with vector support, configuring the Rust-based server, and integrating with external tools like OpenClaw via Unix sockets or HTTP.
Sources: README.md:3-12
System Prerequisites
Before installing Ethos, ensure the following software requirements are met:
| Requirement | Version | Notes |
|---|---|---|
| Rust + Cargo | 1.75+ | Required for building the server and CLI |
| PostgreSQL | 16+ | Version 17 is recommended |
| pgvector | 0.8.0+ | Required for HNSW index and vector search |
| Node.js | 18+ | Required for TypeScript ingest hooks |
| Google AI Studio API Key | - | Required for Gemini semantic embeddings |
Sources: README.md:143-151, migrations/README.md:5-10
Database Setup
Ethos relies on PostgreSQL with the pgvector and pg_trgm extensions for storing and searching semantic memories.
1. Extension Installation
On Ubuntu, the extensions can be installed via the package manager. pgvector must be created by a superuser.
sudo apt install postgresql-17 postgresql-17-pgvector
sudo -u postgres psql -d ethos -c "CREATE EXTENSION IF NOT EXISTS vector;"
Sources: README.md:155-159, migrations/README.md:11-15
2. User and Database Creation
The following SQL commands establish the ethos user and database with necessary permissions.
CREATE USER ethos WITH PASSWORD 'your_password_here';
CREATE DATABASE ethos OWNER ethos;
\c ethos
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
GRANT ALL PRIVILEGES ON DATABASE ethos TO ethos;
Sources: README.md:168-176, migrations/README.md:20-27
3. Schema Migrations
The database schema is initialized by running the provided SQL migration files. The primary schema includes tables for episodic_traces, semantic_facts, and memory_vectors.
psql -U ethos -d ethos -h localhost -f migrations/001_initial_schema.sql
Sources: README.md:191-193, migrations/README.md:32-34
The following diagram illustrates the initial database entity relationships:
The schema establishes a hierarchy from raw sessions to episodic traces, which are then consolidated into semantic facts. Sources: migrations/001_initial_schema.sql:24-170
Server Configuration
Ethos uses a TOML configuration file (ethos.toml) and an environment file (.env) for secrets.
Configuration Parameters
The configuration is structured into several sections including database, service, and consolidation settings.
| Section | Parameter | Type | Description |
|---|---|---|---|
service | socket_path | String | Path to the Unix domain socket |
database | url | String | PostgreSQL connection string |
embedding | gemini_model | String | Model used for embeddings (e.g., gemini-embedding-001) |
http | port | u16 | Port for the REST API (default 8766) |
Sources: ethos-core/src/config.rs:5-80, migrations/README.md:59-65
Secrets Management
An .env file must be created in the project root to store the Google AI API key:
GOOGLE_API_KEY=your_gemini_api_key_here
Sources: README.md:183-187, ethos-server/src/main.rs:26-28
Building and Running
Compilation
Build the release binaries using Cargo. This produces the ethos-server and ethos-cli.
cargo build --release
Sources: README.md:178-181
Execution and Health Check
The server can be verified using a health check flag before regular operation.
# Verify connection to DB and pgvector
cargo run --release --bin ethos-server -- --health
# Run the server
cargo run --release --bin ethos-server
Sources: README.md:199-203, ethos-server/src/main.rs:44-61
Systemd Integration
For production environments, Ethos should be run as a background service.
The server manages multiple background loops for ingestion, embedding, and memory consolidation. Sources: README.md:209-228, ethos-server/src/main.rs:81-110
Integration and CLI
Command Line Interface
The ethos-cli acts as a QMD-compatible frontend for searching memory.
| Command | Argument | Description |
|---|---|---|
search | <query> | Semantic search against the memory engine |
status | - | Displays server health and version info |
query | <query> | Alias for search |
Sources: ethos-cli/src/main.rs:17-64
Hook Setup
Integration with OpenClaw is achieved via TypeScript hooks that communicate over the Unix socket defined in the configuration. The client handles automatic reconnection and MessagePack framing.
Sources: README.md:241-248, ethos-ingest-ts/src/client.ts:74-106
Summary
Setting up Ethos requires a PostgreSQL 17 environment with pgvector to support 768-dimensional Gemini embeddings. After configuring the database and ethos.toml, the Rust server handles background consolidation and decay tasks while exposing IPC and HTTP interfaces for AI agent interaction.