High-Level Architecture

Relevant source files

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

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

Ethos is a standalone neuromorphic memory engine designed to provide AI agents with persistent, long-term memory modeled after the human hippocampus. It functions as a background service that records conversations, extracts structured facts, and manages memory salience over time using biological principles such as Ebbinghaus decay and Long-Term Potentiation (LTP).

The system is built with a focus on asynchronous processing and graceful degradation. It integrates with agents via Unix domain sockets for low-latency IPC or through a REST API for standard HTTP communication. The core engine is implemented in Rust, utilizing PostgreSQL with the pgvector extension for semantic similarity searches.

Sources: README.md:3-33, ethos-server/src/main.rs:1-85

System Components

The Ethos architecture consists of several specialized subsystems coordinated by a central server. These subsystems handle the lifecycle of a memory from initial ingestion to long-term consolidation and eventual pruning.

Core Subsystems

Subsystem	Responsibility
Ingest	Captures raw conversation turns (episodic traces) from external hooks.
Embedder	Asynchronously generates 768-dim Gemini embeddings for ingested content.
Retrieve	Performs semantic search using pgvector and spreading activation algorithms.
Consolidation	Distills episodic traces into structured semantic facts every 15 minutes.
Decay Engine	Implements Ebbinghaus decay to reduce salience of unused memories.
Linker	Builds graph edges between related memory nodes for associative retrieval.

The following diagram illustrates the interaction between external agents and the internal Ethos server components:

Data Architecture and Storage

Ethos organizes memory into a multi-tiered structure, simulating the transition from short-term episodic experiences to long-term semantic knowledge.

Memory Tiers

1. Session Events: Fast, raw logs of conversation turns.
2. Episodic Traces: Clusters of turns with initial salience scoring.
3. Semantic Facts: Durable, structured RDF-style triples (subject-predicate-object) extracted from important episodes.
4. Workflow Memories: Long-retention memories focused on task trajectories and project status.

Database Schema

The storage layer utilizes six primary tables to manage these memory types and their relationships:

Table	Purpose
sessions	Tracks active agent sessions and metadata.
episodic_traces	Stores conversation turns with importance and emotional tone.
semantic_facts	Stores promoted facts, decisions, and preferences.
workflow_memories	Tracks high-level task and project outcomes.
memory_vectors	Stores 768-dimensional embeddings for all memory types.
memory_graph_links	Stores directed edges for spreading activation.

Sources: README.md:108-140, migrations/001_initial_schema.sql:17-235

Memory Lifecycle and Decay

A defining feature of the Ethos architecture is the automated management of memory "salience" based on usage.

Ebbinghaus Decay and LTP

The system applies a mathematical formula to update memory salience:
$S(t) = S_0 \times e^{-t/\tau_{eff}} \times (1 + \alpha \times f) \times (1 + \beta \times E)$

Where $\tau_{eff}$ is the effective decay constant, which increases as a memory is retrieved more frequently (Long-Term Potentiation). Memories that fall below a prune_threshold (default 0.05) are soft-deleted.

Retrieval and Spreading Activation

Ethos goes beyond simple vector similarity by implementing Spreading Activation. This allows the engine to surface contextually related memories that may not directly match the search keywords.

Retrieval Logic

1. Anchor Search: Finds top-K cosine matches using pgvector HNSW indexes.
2. Propagation: Iteratively propagates activation scores through memory_graph_links.
3. Scoring: Combines cosine similarity, spread activation, and structural (in-degree) centrality into a final rank.

Communication Protocols

Ethos supports two primary modes of interaction:

Unix Domain Socket (IPC)

Used for high-performance, local communication with agents (e.g., OpenClaw). It uses a little-endian length-prefixed MessagePack payload.

• Socket Path: /tmp/ethos.sock (configurable).
• Actions: ping, health, ingest, search.

HTTP REST API

Exposed on port 8766 by default for cross-language or remote integration.

• POST /search: Semantic memory search.
• POST /ingest: Content ingestion.
• GET /health: System and database status.

Sources: README.md:188-198, ethos-server/src/http.rs:17-45

Summary

The Ethos architecture is a sophisticated implementation of neuromorphic memory principles. By separating raw data ingestion from background consolidation and decay processes, it ensures that AI agents can maintain a manageable and contextually relevant knowledge base. Its combination of vector similarity and graph-based spreading activation provides a more associative retrieval mechanism than standard RAG (Retrieval-Augmented Generation) systems.

Sources: README.md:5-20, ethos-server/src/main.rs:1-103