Spreading Activation & Retrieval
Relevant source files
The following files were used as context for generating this wiki page:
The Spreading Activation & Retrieval system is the core mechanism by which Ethos surfaces relevant context for AI agents. Modeled after hippocampal function, the system combines high-dimensional vector similarity (semantic search) with graph-based associative traversal. This dual approach ensures that agents can access not only direct matches to a query but also related concepts that "light up" through associative links in the memory graph.
Sources: README.md:12-25, ethos-core/src/graph.rs:1-10
Retrieval Architecture
The retrieval process follows a tiered pipeline: it begins with a semantic vector search to identify "anchor" nodes and then optionally propagates activation through connected memories.
Retrieval Pipeline Flow
The following diagram illustrates the lifecycle of a search request from the initial query to the final ranked results.
The retrieval system is implemented primarily in the retrieve subsystem, which handles the interaction between the embedding client, the PostgreSQL pgvector index, and the spreading activation module.
Sources: ethos-server/src/subsystems/retrieve.rs:15-25, ethos-core/src/graph.rs:136-150
Semantic Vector Search
Ethos utilizes 768-dimensional Gemini embeddings stored in a PostgreSQL database using the pgvector extension. Search is performed using cosine similarity against the memory_vectors table.
Vector Search Specifics
- Distance Metric: The system uses
vector_cosine_ops. The final score is calculated as1 - (vector <=> query_vector), mapping the distance to a 0.0–1.0 similarity scale. - Indexing: An HNSW (Hierarchical Navigable Small World) index is utilized for efficient approximate nearest neighbor search.
- Task Types: Queries are embedded using the
RETRIEVAL_QUERYtask type, while stored documents useRETRIEVAL_DOCUMENT.
Sources: migrations/001_initial_schema.sql:178-210, ethos-server/src/subsystems/retrieve.rs:75-100
Spreading Activation Algorithm
Spreading activation is a graph-traversal algorithm that propagates relevance scores from "anchor" nodes (top-K cosine matches) to neighboring nodes in the memory_graph_links table.
Scoring Components
The final relevance of a memory node is determined by a weighted combination of three distinct scores:
| Score Component | Description |
|---|---|
| Cosine Score | Direct semantic similarity between the query and the memory content. |
| Spread Score | Activation received from neighboring nodes during iterative propagation. |
| Structural Score | Importance based on graph topology (specifically in-degree centrality). |
Sources: ethos-core/src/graph.rs:20-28, ethos-core/src/graph.rs:114-125
Iterative Propagation Logic
The spreading process is iterative, controlled by the RetrievalConfig. In each iteration, an active node distributes a portion of its activation to neighbors based on edge weights and a global spreading_strength factor.
// core/src/graph.rs:88-92
for edge in neighbors {
let contribution = node_activation * edge.weight * config.spreading_strength;
let current = new_activation.entry(edge.to_id).or_insert(0.0);
*current += contribution;
}
Sources: ethos-core/src/graph.rs:80-100
Data Structures & Schema
The retrieval system relies on specific database tables to maintain the relationship between raw content, vectors, and graph edges.
Database Relationship Diagram
This diagram shows how vectors and graph links reference the primary memory entities.
Configuration Parameters
Retrieval behavior is tuned through the RetrievalConfig structure, which defines the influence of spreading activation and the limits of the search.
| Parameter | Default/Type | Description |
|---|---|---|
spreading_strength | f32 | Multiplier for activation flow across edges (e.g., 0.85). |
iterations | u32 | Number of hops to propagate activation (e.g., 3). |
weight_similarity | f32 | Weight for the cosine similarity component in the final score. |
weight_activation | f32 | Weight for the spreading activation component in the final score. |
weight_structural | f32 | Weight for the graph centrality component in the final score. |
anchor_top_k | i64 | Number of initial results to use as seeds for spreading. |
Sources: ethos-core/src/graph.rs:160-172, ethos-server/src/subsystems/retrieve.rs:60-70
Long-Term Potentiation (LTP)
Retrieval is not a read-only operation in Ethos. Every time a memory is retrieved, the system performs an asynchronous "Long-Term Potentiation" (LTP) update. This increases the memory's retrieval_count and boosts its salience, effectively protecting it from the Ebbinghaus decay sweep.
// server/src/subsystems/decay.rs:77-83
UPDATE episodic_traces
SET retrieval_count = retrieval_count + 1,
last_retrieved_at = NOW(),
salience = LEAST(salience * 1.1, 1.0)
WHERE id = $1
Sources: ethos-server/src/subsystems/decay.rs:70-95, ethos-server/src/subsystems/retrieve.rs:175-185
Client Interaction
Clients interface with the retrieval system through the ethos-cli or via the Unix domain socket IPC. The CLI provides a QMD-compatible output format for integration with tools like OpenClaw.
IPC Request Structure
{
"action": "search",
"payload": {
"query": "user's search text",
"limit": 5,
"use_spreading": true
}
}
Sources: ethos-cli/src/main.rs:114-130, README.md:214-230
The retrieval system effectively bridges the gap between raw data storage and associative human-like memory, ensuring that relevant information is always available to the agent regardless of whether it matches the query keywords exactly.