Vector Storage & pgvector
Relevant source files
The following files were used as context for generating this wiki page:
Ethos utilizes a specialized vector storage system built on PostgreSQL with the pgvector extension to enable semantic long-term memory for AI agents. This system bridges the gap between raw conversation logs and durable, searchable knowledge by storing high-dimensional embeddings and facilitating similarity-based retrieval.
The core of this architecture is the memory_vectors table, which serves as a unified index for various memory types, including episodic traces and semantic facts. By leveraging Hierarchical Navigable Small World (HNSW) indexes, Ethos performs efficient approximate nearest neighbor searches, allowing agents to recall relevant context based on semantic meaning rather than simple keyword matching.
Sources: README.md:12-16, migrations/001_initial_schema.sql:138-142
Architecture and Schema
The vector storage system is centered around the memory_vectors table, which acts as a central repository for 768-dimensional embeddings generated via the Gemini API.
Database Schema
The schema defines a strict structure for vectors, linking them back to their source content through polymorphic identifiers.
| Column | Type | Description |
|---|---|---|
id | UUID | Primary key for the vector entry. |
source_type | TEXT | The type of source memory: episode, fact, workflow, or query. |
source_id | UUID | Foreign reference to the specific memory item in its respective table. |
embedding | vector(768) | The 768-dimensional embedding vector. |
model | TEXT | The embedding model used (default: gemini-embedding-001). |
importance | FLOAT | Dynamic salience/importance score (stored as importance or salience). |
Sources: migrations/001_initial_schema.sql:144-173, ethos-server/src/subsystems/decay.rs:135-140
Entity Relationships
The following diagram illustrates how memory vectors relate to the primary memory storage tables within the Ethos database.
The memory_vectors table stores snapshots of content and their corresponding embeddings, referencing episodic_traces, semantic_facts, and workflow_memories via source_id.
Sources: migrations/001_initial_schema.sql:24-190
Embedding Pipeline
Ethos employs an asynchronous background pipeline to generate embeddings, ensuring that data ingestion remains non-blocking for the user or agent.
Background Processing
When a memory is ingested, it is initially stored with a NULL vector. A background task or scheduled sweep then processes these pending rows.
- Poll: The
Embeddersubsystem identifies rows wherevector IS NULL. - Request: Content is sent to the Gemini API (
gemini-embedding-001) to generate a 768-dimensional vector. - Update: The resulting vector is written back to the
memory_vectorstable.
Retrieval and Similarity Search
Semantic retrieval is implemented using the pgvector cosine distance operator (<=>).
Search Logic
Retrieval involves embedding the incoming query and performing a nearest-neighbor search. The score is calculated as 1 - cosine_distance, normalizing results between 0.0 and 1.0.
SELECT
id, content, source,
1 - (vector <=> $1::vector) AS score
FROM memory_vectors
WHERE vector IS NOT NULL
ORDER BY vector <=> $1::vector
LIMIT $2;
Sources: ethos-server/src/subsystems/retrieve.rs:90-108
Spreading Activation
Beyond simple similarity, Ethos uses a "Spreading Activation" algorithm. This propagates relevance scores through edges in the memory_graph_links table, allowing the system to surface contextually related memories that may not have the highest direct cosine similarity.
| Score Component | Weight | Description |
|---|---|---|
| Similarity | 0.5 | Direct cosine similarity to the query. |
| Activation | 0.3 | Propagation of scores from similar "anchor" nodes to neighbors. |
| Structural | 0.2 | Based on in-degree centrality (how connected a node is). |
Sources: ethos-core/src/graph.rs:11-15, ethos-server/src/subsystems/retrieve.rs:136-160
Performance Optimization (HNSW)
To handle large memory sets, Ethos implements an HNSW (Hierarchical Navigable Small World) index on the embedding column. This allows for approximate nearest neighbor (ANN) searches which are significantly faster than exact scans.
CREATE INDEX IF NOT EXISTS idx_vectors_hnsw
ON memory_vectors
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
The configuration uses m=16 for node connections and ef_construction=64 to balance index build speed and search accuracy.
Sources: migrations/001_initial_schema.sql:179-183, migrations/README.md:12-14
Lifecycle and Decay
Vector importance is not static. Ethos applies an Ebbinghaus Decay model where the importance/salience of a vector decreases over time unless reinforced.
Long-Term Potentiation (LTP)
When a memory is retrieved, its salience is boosted, and its effective decay time constant ($\tau_{eff}$) is extended. This mimics the biological process where frequently accessed memories become more permanent.
- Initial State: New vectors start with high salience ($1.0$).
- Decay: Salience drops following $S(t) = S_0 \times e^{-t/\tau_{eff}}$.
- Pruning: Once salience falls below the
prune_threshold(default 0.05), the vector is marked aspruned = true.
Sources: ethos-server/src/subsystems/decay.rs:11-30, README.md:65-75
Summary
The Vector Storage system in Ethos provides a robust, biologically-inspired memory layer. By combining pgvector for similarity, Gemini for high-quality embeddings, and a custom Decay Engine, it ensures that AI agents can efficiently retrieve relevant information while naturally "forgetting" noise over time. This architecture supports both direct semantic search and complex associative retrieval through spreading activation.