Security Considerations
Relevant source files
The following files were used as context for generating this wiki page:
Ethos is designed as a standalone memory service that prioritizes reliability and structural isolation through its multi-layered architecture. Security within Ethos is primarily managed through interface isolation (Unix domain sockets vs. HTTP), environment-based secret management, and database-level constraints.
The system facilitates "passive recording" of AI agent conversations, which necessitates careful handling of sensitive data during ingestion, embedding via external APIs (Gemini), and long-term storage in PostgreSQL.
Sources: README.md:1-25
Interface Isolation and IPC Security
Ethos employs a dual-interface strategy to balance local performance with remote accessibility. The primary communication channel is a Unix domain socket, which provides inherent local-only access control.
Unix Domain Socket IPC
The IPC protocol uses a Unix domain socket located at /tmp/ethos.sock by default. This limits interaction to processes running on the same host with appropriate filesystem permissions. Data is serialized using MessagePack and framed with a 4-byte Little-Endian length prefix to prevent buffer overruns and ensure message integrity.
The diagram shows the local isolation of the IPC layer using Unix sockets.
Sources: README.md:118-132, ethos-ingest-ts/src/client.ts:103-118
HTTP REST API
Ethos also exposes an Axum-based HTTP REST API on port 8766. While this increases the attack surface compared to Unix sockets, it is configured by default to listen on 127.0.0.1, restricting access to the local loopback interface.
| Feature | Configuration Option | Default Value | Security Impact |
|---|---|---|---|
| Socket Path | service.socket_path | /tmp/ethos.sock | Local filesystem permission gating |
| HTTP Enable | http.enabled | true | Enables remote/local network access |
| HTTP Host | http.host | 127.0.0.1 | Restricts API to local loopback |
| Port | http.port | 8766 | Standard port for service discovery |
Sources: ethos-core/src/config.rs:104-125, ethos-server/src/http.rs:15-30
Database Security and Data Integrity
The storage layer relies on PostgreSQL with the pgvector extension. Security is enforced through schema design, constraints, and connection management.
Schema Hardening
The database schema uses strict type checking and constraints to prevent malformed data insertion. For instance, the episodic_traces table enforces role validation ('user', 'assistant', 'system') and defaults to a specific user_id and tenant_id to support multi-tenancy isolation.
The diagram illustrates the relationships and isolation keys used in the database schema.
Sources: migrations/001_initial_schema.sql:35-85
Secret Management
Ethos explicitly avoids hardcoding credentials. Database connection strings and API keys (such as the GOOGLE_API_KEY) are loaded via .env files or system environment variables. In production, the use of a secrets manager is recommended.
// ethos-server/src/main.rs:26-28
#[tokio::main]
async fn main() -> anyhow::Result<()> {
// Load .env file if present (dev convenience — production uses real env vars)
dotenvy::dotenv().ok();
// ...
}
Sources: ethos-server/src/main.rs:26-28, migrations/README.md:80-85
External API and Embedding Security
Ethos integrates with Google Gemini for generating embeddings. This introduces a dependency on an external cloud provider, which has specific security implications.
Embedding Pipeline
- API Key Exposure: The Gemini API key must be provided via the
GOOGLE_API_KEYenvironment variable. - Data Outbound: Raw conversation content is sent to Google's servers for embedding. While ingest is "instant" and non-blocking via an async pipeline, developers must be aware that data leaves the local environment.
- Rate Limiting: The
EmbeddingConfigincludesrate_limit_rpmto prevent API abuse or accidental flooding that could lead to account suspension or high costs.
Sources: README.md:100-110, ethos-core/src/config.rs:28-38
Conflict Resolution and Review Workflow
To prevent the corruption of long-term knowledge, Ethos implements a "Conflict Resolution" system during the consolidation of episodic memories into semantic facts.
If a new fact contradicts an existing one and the confidence delta is low, the system does not overwrite the data. Instead, it flags the record for human review.
Review Inbox
Conflicts are written to a "review inbox" file (e.g., a Markdown file). This manual gate ensures that automated processes do not inadvertently delete or overwrite critical information through incorrect pattern matching.
The sequence shows the logic for handling conflicting memories during consolidation.
Sources: ethos-server/src/subsystems/consolidate.rs:250-320
Conclusion
The security of Ethos is centered on local isolation via Unix sockets and loopback HTTP bindings, combined with database-level integrity checks. While the system provides a robust framework for neuromorphic memory, the primary security responsibility lies in the management of the external Gemini API key and the oversight of the conflict review inbox to maintain memory accuracy.
Sources: README.md:255-265, ethos-server/src/subsystems/consolidate.rs:340-350