IPC Protocol
Relevant source files
The following files were used as context for generating this wiki page:
The Ethos IPC (Inter-Process Communication) protocol is the primary mechanism for high-performance communication between AI agent integration hooks and the core Ethos memory engine. It uses a Unix domain socket to facilitate low-latency, reliable data exchange, enabling passive memory recording and context injection without blocking conversation delivery.
The protocol follows a framed MessagePack structure, allowing for complex, typed data payloads while maintaining minimal overhead. It supports both asynchronous fire-and-forget patterns for high-volume ingest operations and synchronous request-response patterns for semantic search and health monitoring.
Sources: README.md:104-124, ethos-ingest-ts/src/client.ts:1-12
Wire Format and Framing
Ethos utilizes a Unix domain socket, typically located at /tmp/ethos.sock, for all IPC communication. The framing mechanism ensures that the receiver can correctly identify and extract complete MessagePack payloads from the stream.
Message Framing Structure
Every message sent over the wire consists of two parts:
- Length Prefix: A 4-byte, Little-Endian unsigned 32-bit integer (
u32 LE) representing the total length of the following payload in bytes. - Payload: A MessagePack-encoded object containing the request or response data.
| Component | Type | Description |
|---|---|---|
| Length | u32 (LE) | 4-byte little-endian length of the payload |
| Payload | MessagePack | Encoded request or response map |
Sources: README.md:126-133, ethos-ingest-ts/src/client.ts:98-102, ethos-ingest-ts/tests/ipc.test.ts:31-35
Data Flow Diagram
The following diagram illustrates the flow of a message from a TypeScript client to the Rust server.
The client buffers data until a complete frame (prefix + payload) is received before decoding.
Sources: ethos-ingest-ts/src/client.ts:133-155, ethos-ingest-ts/tests/ipc.test.ts:31-40
Protocol Actions
The protocol is action-oriented. Requests must contain an action field which determines the structure of the payload and the internal routing within the Ethos server.
Request Types
| Action | Pattern | Description |
|---|---|---|
ping | Request-Response | Basic connectivity test |
health | Request-Response | Returns detailed status of DB and pgvector |
ingest | Fire-and-Forget | Records new conversation turns or memories |
search | Request-Response | Performs semantic search with optional spreading activation |
consolidate | Request-Response | Triggers an immediate episodic-to-semantic promotion cycle |
Sources: README.md:175-215, ethos-ingest-ts/src/client.ts:13-33, ethos-server/src/http.rs:162-177
Communication Sequence
Semantic search operations require a full request-response cycle to return memory results to the agent.
Client Implementation
The EthosClient class in TypeScript provides the reference implementation for the protocol. It manages socket persistence, automatic reconnection, and request ID tracking for synchronous calls.
Connection Management
The client implements an exponential backoff strategy for reconnections, starting with a retryInterval (default 1000ms) up to a maxRetryInterval (default 60000ms).
Synchronous vs. Asynchronous Operations
send(): Used foringest. It writes the frame to the socket and returnstrueimmediately if the socket is available.request(): Used forsearch. It returns aPromise, assigns a local request ID, and sets a timeout (default 5000ms). The promise resolves when a MessagePack frame is received and decoded.
Sources: ethos-ingest-ts/src/client.ts:47-91, ethos-ingest-ts/src/client.ts:114-131
Configuration
The IPC server behavior is governed by the EthosConfig, loaded from ethos.toml.
| Key | Type | Default | Description |
|---|---|---|---|
service.socket_path | String | /tmp/ethos.sock | Filesystem path for the Unix socket |
http.enabled | Boolean | true | Whether to also expose IPC actions via REST |
http.port | u16 | 8766 | Port for the HTTP proxy |
Sources: ethos-core/src/config.rs:15-20, ethos-server/src/main.rs:94-106
Summary
The Ethos IPC Protocol provides a robust, low-latency interface for neuromorphic memory operations. By combining Unix sockets with MessagePack and a strict length-prefix framing protocol, it ensures that memory ingestion and retrieval can occur at scale with minimal impact on agent performance. Its dual-support for fire-and-forget and request-response patterns allows it to handle both passive recording and active semantic querying within a single unified interface.