Fact & Episode Modeling
Relevant source files
The following files were used as context for generating this wiki page:
Fact & Episode Modeling represents the core memory architecture of Ethos, inspired by the human hippocampus. It distinguishes between short-term episodic traces—raw records of conversation turns—and long-term semantic facts, which are distilled, structured knowledge triples (subject-predicate-object).
The system manages the transition from episodic to semantic memory through a consolidation engine that runs periodically (every 15 minutes) when the system is idle. This modeling ensures that AI agents can maintain persistent, evolving knowledge while naturally pruning unimportant or outdated information via Ebbinghaus decay.
Sources: README.md:12-25, ethos-server/src/subsystems/consolidate.rs:1-12
Data Architecture
The memory system is structured into several tiers, ranging from raw events to durable knowledge.
Episodic Traces
Episodic traces capture individual conversation turns. They include salience scoring (importance, emotional tone, and novelty) and metadata like topics and entities. These records are indexed for semantic search using pgvector.
Sources: migrations/001_initial_schema.sql:32-60, ethos-server/src/subsystems/consolidate.rs:59-67
Semantic Facts
Semantic facts are promoted episodic memories that meet specific importance or retrieval thresholds. They are stored as structured triples to represent durable relationships and preferences.
Sources: migrations/001_initial_schema.sql:75-96, ethos-server/src/subsystems/consolidate.rs:184-210
Memory Schema Relationships
The following Entity-Relationship diagram illustrates how different memory components relate to one another within the PostgreSQL schema.
The diagram shows the hierarchy from sessions to episodes, the promotion to facts, and the graph links used for spreading activation.
Sources: migrations/001_initial_schema.sql:15-195
Consolidation Engine
The consolidation engine implements the transition from episodic memory to semantic memory. It triggers based on specific criteria to ensure only high-value information becomes permanent.
Promotion Criteria
An episodic trace is considered for promotion if it meets one of the following:
- Importance Threshold: Salience score $\ge 0.8$.
- Retrieval Frequency: Accessed $\ge 5$ times.
- Keywords: Contains explicit decision markers ("decided", "plan is") or preference markers ("prefers", "hates", "favorite").
- Explicit Markers: Contains "remember this" or "important:".
Sources: ethos-server/src/subsystems/consolidate.rs:7-12, ethos-server/src/subsystems/consolidate.rs:141-168
Conflict Resolution Logic
When new facts are extracted, they are compared against existing facts using subject and predicate matching.
| Resolution Type | Condition | Action |
|---|---|---|
| Refinement | Compatible objects (e.g., "Rust" and "Rust language") | Update existing fact, boost confidence |
| Supersession | Explicit new decision or significant confidence delta | Mark old fact as superseded by new fact |
| Flagging | Ambiguous contradiction | Mark both for human review in review_inbox |
| Sources: ethos-server/src/subsystems/consolidate.rs:14-20, ethos-server/src/subsystems/consolidate.rs:309-354 |
This flowchart details the logic path taken by the consolidation loop within the consolidate.rs subsystem.
Sources: ethos-server/src/subsystems/consolidate.rs:88-132, ethos-server/src/subsystems/consolidate.rs:309-354
Memory Decay and Salience
Ethos uses an Ebbinghaus-inspired decay model to manage the lifecycle of memories. Salience is calculated using time since last access and a Long-Term Potentiation (LTP) factor.
Salience Formula
The salience $S(t)$ is calculated as:
$S(t) = S_0 \times e^{-t/\tau_{eff}} \times (1 + \alpha f) \times (1 + \beta E)$
- $t$: Days since last access.
- $\tau_{eff}$: Effective decay constant, increased by retrieval count (LTP).
- $\alpha f$: Frequency boost.
- $\beta E$: Emotional weight boost.
Sources: ethos-server/src/subsystems/decay.rs:3-17, ethos-server/src/subsystems/decay.rs:114-142
Pruning
If the salience or confidence of a memory falls below the prune_threshold (default 0.05), the item is marked as pruned = true. Pruned items are soft-deleted and excluded from standard retrieval.
Sources: ethos-server/src/subsystems/decay.rs:164-170, ethos-core/src/config.rs:104
Retrieval and Spreading Activation
Retrieval utilizes both vector similarity and graph-based associative retrieval.
- Semantic Search: Initial "anchor" nodes are found using cosine similarity via
pgvector. - Spreading Activation: Activation propagates from anchors through
memory_graph_links. - Final Scoring: Combined score is a weighted sum of similarity, activation spread, and structural centrality.
Sources: ethos-core/src/graph.rs:10-25, ethos-core/src/graph.rs:86-118
Graph Link Types
Links are directed edges with specific relations that weight the spread of activation:
temporal_next: Sequential conversation flow.semantic_similar: Shared embeddings.derived_from: Fact-to-episode provenance.supports/contradicts: Logical relationships.
Sources: migrations/001_initial_schema.sql:179-181
Summary
Fact & Episode Modeling provides a multi-tiered memory system where raw interactions (episodes) are distilled into structured knowledge (facts). This architecture ensures AI agents retain critical information through consolidation while naturally filtering noise through a mathematical decay model, effectively mimicking biological long-term memory.
Sources: README.md:12-25, ethos-server/src/subsystems/consolidate.rs:1-12