TypeScript Client SDK
Relevant source files
The following files were used as context for generating this wiki page:
The Ethos TypeScript Client SDK provides a high-level interface for interacting with the Ethos Neuromorphic Memory Engine. It abstracts the underlying IPC (Inter-Process Communication) details, allowing developers to integrate long-term memory capabilities into AI agents and Node.js applications with minimal friction.
The SDK is primarily designed to facilitate "Passive recording" of conversation turns and "Semantic search" retrieval. It communicates with the ethos-server over a Unix domain socket using a framed MessagePack protocol.
Sources: README.md:1-20, ethos-ingest-ts/src/client.ts:50-55
Architecture and Protocol
The SDK implements a client-side library that connects to the Ethos Rust server via a Unix domain socket, typically located at /tmp/ethos.sock. The communication protocol follows a specific framing requirement: a 4-byte Little-Endian unsigned 32-bit integer (u32) representing the length of the subsequent MessagePack-encoded payload.
The diagram above illustrates the data encapsulation and transmission flow between the TypeScript SDK and the Ethos server.
Sources: README.md:124-131, ethos-ingest-ts/tests/ipc.test.ts:25-45, ethos-ingest-ts/src/client.ts:150-165
Key Classes and Components
EthosClient
The EthosClient class is the central entry point for the SDK. It extends EventEmitter and manages the lifecycle of the socket connection, including automatic reconnection logic and request-response tracking.
| Component | Description |
|---|---|
connect() | Establishes the Unix socket connection with exponential backoff retries. |
send(request) | A fire-and-forget method primarily used for ingest operations. |
request(request) | An asynchronous method that returns a Promise, used for search operations. |
handleData(data) | Internal buffer management for reassembling fragmented IPC frames. |
destroy() | Closes the socket and rejects any pending promises in the request queue. |
Sources: ethos-ingest-ts/src/client.ts:48-65, ethos-ingest-ts/src/client.ts:80-105, ethos-ingest-ts/tests/client.test.ts:37-55
Data Structures and Interfaces
The SDK defines strict TypeScript interfaces to match the Rust IPC EthosRequest and EthosResponse enums.
Request Types
Requests are tagged with an action field to facilitate dispatching within the Rust server.
export type EthosSource = 'user' | 'assistant' | 'system';
export interface IngestRequest {
action: 'ingest';
payload: {
content: string;
source: EthosSource;
metadata?: Record<string, any>;
};
}
export interface SearchRequest {
action: 'search';
query: string;
limit?: number;
}
Sources: ethos-ingest-ts/src/client.ts:7-30
Response Handling
The SDK maintains a pendingRequests Map to associate incoming responses with their original Promises. This is essential for the request-response pattern used during semantic search.
This sequence ensures that even with asynchronous background processing, the correct response is returned to the specific caller.
Sources: ethos-ingest-ts/src/client.ts:135-148, ethos-ingest-ts/tests/client-request.test.ts:30-70
Configuration Options
The client is configured via the EthosClientOptions interface, allowing customization of the connection behavior.
| Parameter | Type | Default | Description |
|---|---|---|---|
socketPath | string | (Required) | The filesystem path to the Ethos Unix socket. |
retryInterval | number | 1000 | Initial delay (ms) before retrying a failed connection. |
maxRetryInterval | number | 60000 | Maximum cap for the exponential backoff delay. |
Sources: ethos-ingest-ts/src/client.ts:41-46, ethos-ingest-ts/src/client.ts:60-65
Dependencies and Environment
The SDK is built as a CommonJS module and utilizes the following primary dependencies:
- msgpack5: Used for high-performance binary serialization/deserialization.
- Node.js
netandevents: Core modules for socket communication and event handling.
Tests are implemented using Jest, ensuring reliability of connection retries, IPC framing, and timeout logic.
Sources: ethos-ingest-ts/package.json:15-30, ethos-ingest-ts/tests/setup.test.ts:5-15
Summary
The TypeScript Client SDK acts as the primary gateway for Node.js-based integrations with Ethos. By providing robust connection management and abstracting the framed MessagePack IPC protocol, it enables agents to record conversations via ingest and retrieve associative context via semantic search. Its design prioritizes resilience through exponential backoff and structured error handling for asynchronous operations.