Introduction to Ethos
Relevant source files
The following files were used as context for generating this wiki page:
Ethos is a standalone neuromorphic memory engine designed to provide AI agents with persistent, long-term memory capabilities. It mimics biological memory processes by passively recording interactions, consolidating episodic turns into semantic facts, and managing memory retention through Ebbinghaus decay and Long-Term Potentiation (LTP). Built with Rust and backed by PostgreSQL with the pgvector extension, Ethos serves as a "Hippocampus" for AI frameworks like OpenClaw.
The system operates as a memory service that integrates into agent workflows via Unix domain sockets (IPC) or a REST API. It handles high-dimensional vector embeddings—specifically 768-dimensional Gemini embeddings—to perform semantic similarity searches, allowing agents to retrieve relevant context based on conceptual relationships rather than simple keyword matching.
Sources: README.md:1-25, ethos-server/src/main.rs:1-15
System Architecture
The Ethos architecture consists of a central Rust-based server (ethos-server) that orchestrates several specialized subsystems. It interacts with a PostgreSQL database and exposes interfaces for external agents and tools.
Core Components
- Ingest Subsystem: Captures raw conversation turns (episodic traces) and stores them in the database.
- Embedder Subsystem: An asynchronous pipeline that generates vector embeddings for new memories using the Gemini API.
- Retrieve Subsystem: Performs semantic searches using cosine similarity and spreading activation across a memory graph.
- Consolidation Engine: Periodically distills short-term episodic memories into structured, durable semantic facts.
- Decay Engine: Implements the Ebbinghaus decay algorithm to prune low-salience memories while reinforcing frequently accessed ones.
Sources: README.md:105-135, ethos-server/src/main.rs:77-110
System Data Flow
The following diagram illustrates how a conversation turn moves through the Ethos engine from ingestion to long-term storage and retrieval.
The diagram shows the lifecycle of a memory from initial ingestion through embedding and consolidation, ending in retrieval or decay.
Sources: README.md:57-75, ethos-server/src/http.rs:136-155
Communication Interfaces
Ethos provides multiple ways for clients to interact with the memory engine, primarily through a performance-oriented IPC protocol and a developer-friendly REST API.
IPC Protocol (Unix Domain Socket)
The primary integration point for performance-critical hooks is a Unix domain socket located at /tmp/ethos.sock. It uses a custom framing protocol consisting of a 4-byte Little-Endian (LE) unsigned 32-bit integer representing the payload length, followed by a MessagePack-encoded payload.
Sources: README.md:139-150, ethos-ingest-ts/src/client.ts:133-145
HTTP REST API
A companion HTTP server (default port 8766) provides RESTful endpoints for tools like ethos-cli.
| Endpoint | Method | Description |
|---|---|---|
/health | GET | Returns system health, DB status, and component versions. |
/search | POST | Performs semantic memory search using vector similarity. |
/ingest | POST | Submits content to be recorded into memory. |
/consolidate | POST | Manually triggers the episodic-to-semantic consolidation cycle. |
Sources: ethos-server/src/http.rs:32-41, ethos-cli/src/main.rs:141-155
Data Models and Schema
Ethos utilizes a relational schema optimized for vector search and graph-based relationships. The core of the memory storage resides in six primary tables.
Database Tables
| Table | Purpose | Key Fields |
|---|---|---|
sessions | Tracks active agent sessions. | session_key, agent_id |
episodic_traces | Stores turn-by-turn logs with salience scores. | content, importance, role |
semantic_facts | Stores distilled, durable knowledge (Triples). | subject, predicate, object |
memory_vectors | Stores 768-dim embeddings for similarity search. | embedding, source_type, source_id |
memory_graph_links | Stores edges for spreading activation. | from_id, to_id, relation, weight |
workflow_memories | Tracks long-term task and project trajectories. | workflow_id, status, outcome |
Sources: migrations/001_initial_schema.sql:15-180
Vector Search Implementation
Ethos uses the pgvector extension with an HNSW (Hierarchical Navigable Small World) index to perform efficient approximate nearest neighbor searches.
CREATE INDEX IF NOT EXISTS idx_vectors_hnsw
ON memory_vectors
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
Sources: migrations/001_initial_schema.sql:187-193
Configuration and Tuning
The engine's behavior, particularly regarding how it remembers and forgets, is controlled through a centralized configuration file (ethos.toml).
Key Configuration Modules
- Consolidation: Controls the frequency (
interval_minutes) and thresholds (importance_threshold,retrieval_threshold) for promoting episodes to facts. - Decay: Defines parameters for the Ebbinghaus curve, including
base_tau_days(defaulting to 7 days for never-accessed memories) and theltp_multiplierfor reinforcing frequently accessed data. - Retrieval: Sets the
confidence_gateand weights for the spreading activation algorithm (similarity vs. activation vs. structural weights).
Sources: ethos-core/src/config.rs:44-93, README.md:78-85
Memory Lifecycle Sequence
The following sequence diagram represents the background processing involved in consolidating memories.
This sequence demonstrates the transition of temporary episodic data into long-term semantic knowledge through the background consolidation loop.
Sources: README.md:105-135, ethos-server/src/main.rs:95-108
Summary
Ethos provides a robust infrastructure for persistent AI memory by combining traditional relational data management with modern vector search and neuromorphic algorithms. By automating the capture, embedding, consolidation, and eventual decay of information, it allows AI agents to maintain a contextually relevant knowledge base that evolves naturally with use, reducing the need for manual prompt engineering or memory management.