HTTP API

Relevant source files

The following files were used as context for generating this wiki page:

• ethos-server/src/http.rs
• ethos-cli/src/main.rs
• ethos-server/src/main.rs
• ethos-core/src/config.rs
• ethos-server/tests/http_integration.rs
• README.md

The Ethos HTTP API is a RESTful interface built using the Axum framework that exposes the memory engine's search and ingestion capabilities over network protocols. It operates alongside the Unix domain socket IPC server, typically running on port 8766, to provide a cross-platform method for external tools and CLI applications to interact with the neuromorphic memory service.

The API is designed with a "thin handler" architecture, where HTTP endpoints delegate business logic to testable inner functions. This ensures high reliability and allows the API to serve as a bridge to the internal IPC router for processing memory operations.

Sources: ethos-server/src/http.rs:1-15, ethos-server/src/main.rs:100-112, README.md:204-209

Server Architecture

The HTTP server is conditionally spawned based on the HttpConfig provided in the system configuration. It utilizes a shared HttpState containing a PostgreSQL connection pool and the global system configuration.

The diagram shows the initialization flow from the main server entry point to the Axum request handling layer.

Shared State and Initialization

The server is initialized via start_http_server, which binds a TcpListener to a configured host and port (defaulting to 127.0.0.1:8766). It supports graceful shutdown via a broadcast channel.

Component	Description
HttpState	A cloneable struct containing PgPool and EthosConfig.
TcpListener	Standard library listener bound to the configured address.
Axum Router	Maps HTTP methods and paths to specific handler functions.

Sources: ethos-server/src/http.rs:35-40, ethos-server/src/http.rs:50-58, ethos-core/src/config.rs:115-125

API Endpoints

The API provides five primary routes for system health, information, and memory manipulation.

Health and System Information

• GET /health: Returns the status of the server, including database connection status, pgvector extension version, and the path to the IPC socket.
• GET /version: Provides the current semantic version of the Ethos server and the protocol version (currently ethos/1).

Sources: ethos-server/src/http.rs:118-145, ethos-server/src/http.rs:148-153

Memory Search

• POST /search: Performs semantic memory search using vector similarity.

The search process involves a translation from an HTTP SearchRequest to an internal EthosRequest::Search.

Search Parameters:

Parameter	Type	Default	Description
query	String	(Required)	The text to search for in semantic memory.
limit	u32	5	Maximum number of results to return.
use_spreading	bool	false	Whether to enable spreading activation for associative retrieval.
min_score	f64	None	Informational threshold for filtering results.

Sources: ethos-server/src/http.rs:85-93, ethos-server/src/http.rs:156-177, ethos-cli/src/main.rs:10-15

Memory Ingestion and Consolidation

• POST /ingest: Allows raw content to be submitted to the memory pipeline. The payload is passed directly to the ingest subsystem for embedding and storage.
• POST /consolidate: Manually triggers the consolidation cycle (promoting episodic memories to semantic facts), optionally for a specific session.

Sources: ethos-server/src/http.rs:200-215, ethos-server/src/http.rs:224-240

CLI Integration (QMD Protocol)

The ethos-cli serves as a reference implementation of the HTTP API client. It specifically implements a "QMD-compatible" output format, allowing it to act as a drop-in replacement for standard memory search tools in environments like OpenClaw.

Result Transformation

When the --json flag is provided to ethos-cli, the HTTP response is transformed from the native Ethos format into the QMD wire protocol format:

pub struct QmdResult {
    pub docid: String,   // "#" + first 6 hex chars of UUID
    pub score: f64,      // Similarity score 0.0–1.0
    pub file: String,    // "ethos://memory/{uuid}"
    pub title: String,   // First non-empty line (capped 60 chars)
    pub snippet: String, // Diff-header + content preview
}

Sources: ethos-cli/src/main.rs:88-100, ethos-cli/src/main.rs:103-125

Error Handling

The API utilizes a standardized ErrorResponse structure for unsuccessful requests. Inner functions return StatusCode and serde_json::Value pairs to allow the Axum handlers to return appropriate HTTP status codes (e.g., 400 Bad Request for empty queries or 500 Internal Server Error for database failures).

{
  "error": "query field is required",
  "status": "error"
}

Sources: ethos-server/src/http.rs:103-112, ethos-server/src/http.rs:160-167

Conclusion

The HTTP API provides a robust and standardized gateway to the Ethos memory engine. By abstracting the complex internal IPC and database interactions into simple RESTful endpoints, it enables integration with a wide variety of AI agents and external tools. Its design emphasizes testability and compatibility, particularly through its support for the QMD wire protocol via the accompanying CLI.