Embedding Subsystem

Relevant source files

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

• ethos-core/src/embeddings.rs
• ethos-core/src/config.rs
• ethos-server/src/router.rs
• migrations/001_initial_schema.sql
• README.md
• ethos-server/src/subsystems/linker.rs

The Embedding Subsystem is a critical component of the Ethos neuromorphic memory engine responsible for transforming textual data into high-dimensional vector representations. It leverages the Gemini API to generate 768-dimensional embeddings, which are then stored in PostgreSQL using the pgvector extension. These embeddings enable semantic search capabilities, allowing AI agents to retrieve memories based on conceptual similarity rather than simple keyword matching.

Sources: README.md:1-15, ethos-core/src/embeddings.rs:1-12

The subsystem operates as an asynchronous pipeline. While data ingestion is near-instant, the resource-intensive process of communicating with the Google AI Studio API happens in background tasks, ensuring that conversation delivery to agents is never blocked. This architecture supports features such as Semantic Search and automatic graph linking.

Sources: README.md:46-55, ethos-server/src/router.rs:36-45

Architecture and Data Flow

The subsystem is built around a background processing loop that handles batching and rate-limiting for API requests. It interfaces directly with the database to store and retrieve vector data.

System Overview Diagram

The following diagram illustrates how the Embedding Subsystem interacts with the API and the database during the ingestion process.

Implementation Components

The core logic is distributed across several modules:

• ethos-core/src/embeddings.rs: Contains the GeminiEmbeddingClient, which manages HTTP communication, JSON serialization for the Gemini API, and exponential backoff retry logic.
• ethos-server/src/router.rs: Dispatches manual and automatic embedding requests through handle_embed_request.
• ethos-core/src/config.rs: Defines the EmbeddingConfig structure, which controls parameters like model selection, dimensions, and rate limits.

Sources: ethos-core/src/embeddings.rs:101-118, ethos-server/src/router.rs:98-115, ethos-core/src/config.rs:30-41

Gemini API Integration

Ethos specifically utilizes the gemini-embedding-001 model. The subsystem is hard-coded to handle 768 dimensions, which is the standard output for this model.

API Request Configuration

The subsystem uses specific TaskType values to optimize embedding quality based on the use case.

Task Type	Usage	Description
RETRIEVAL_DOCUMENT	Default	Used for embedding memories (episodes, facts) for storage.
RETRIEVAL_QUERY	Search	Used for embedding user queries to find matching documents.

Sources: ethos-core/src/embeddings.rs:19-27, ethos-core/src/embeddings.rs:151-154

Resilience and Retries

The GeminiEmbeddingClient implements a robust retry strategy using tokio_retry. It employs exponential backoff with jitter to handle 429 Rate Limit Exceeded and 500 Internal Server Error responses from the Gemini API.

// ethos-core/src/embeddings.rs:155-161
let retry_strategy = ExponentialBackoff::from_millis(self.config.retry_delay_ms)
    .max_delay(Duration::from_secs(10))
    .map(jitter)
    .take(self.config.max_retries);

Sources: ethos-core/src/embeddings.rs:155-175

Database Schema: memory_vectors

The results of the embedding process are persisted in the memory_vectors table. This table uses the vector(768) type provided by pgvector.

Vector Table Definition

Column	Type	Description
id	UUID	Primary key.
source_type	TEXT	'episode', 'fact', 'workflow', or 'query'.
source_id	UUID	Foreign key to the original memory source.
embedding	vector(768)	The 768-dimensional floating point vector.
model	TEXT	Default: 'gemini-embedding-001'.

Sources: migrations/001_initial_schema.sql:163-195

HNSW Indexing

To ensure high-performance semantic retrieval, the subsystem creates an HNSW (Hierarchical Navigable Small World) index on the embedding column using cosine distance operators.

-- migrations/001_initial_schema.sql:197-202
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:197-202

Graph Linking Integration

The Embedding Subsystem provides the foundation for the Linker subsystem. After a memory is embedded, the Linker performs a cosine similarity search to find related existing memories.

Hebbian Strengthening Logic

If a new memory's vector is similar to an existing memory (threshold ≥ 0.6), the system creates an edge in the memory_graph_links table. If a link already exists, the weight is increased by 0.1, simulating Hebbian learning ("cells that fire together, wire together").

Sources: ethos-server/src/subsystems/linker.rs:11-30, ethos-server/src/subsystems/linker.rs:80-100

Configuration Options

The behavior of the embedding subsystem is defined in the [embedding] section of ethos.toml.

Option	Type	Default	Description
gemini_model	String	gemini-embedding-001	The model used for API requests.
gemini_dimensions	u32	768	Fixed output dimensionality.
rate_limit_rpm	u32	-	Maximum requests per minute allowed.
max_retries	usize	3	Number of attempts for failed API calls.

Sources: ethos-core/src/config.rs:30-41, ethos-core/src/embeddings.rs:79-90

Conclusion

The Embedding Subsystem serves as the "sensory processor" for Ethos, converting raw text into a mathematical format suitable for neuromorphic memory operations. By combining the Gemini API with efficient pgvector storage and HNSW indexing, it enables the high-speed semantic retrieval and associative graph linking that characterize the Ethos engine.