CLI Utility

Relevant source files

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

• ethos-cli/src/main.rs
• ethos-cli/Cargo.toml
• ethos-server/src/http.rs
• ethos-server/src/main.rs
• Cargo.toml
• README.md

The ethos-cli is a command-line interface designed for semantic memory search within the Ethos ecosystem. It serves as a QMD wire-protocol-compatible frontend, allowing it to act as a drop-in replacement for the qmd binary often used by OpenClaw's memory_search tool. Its primary function is to interface with the Ethos HTTP server to perform searches, queries, and health status checks.

The utility is built using Rust and utilizes the clap crate for argument parsing and reqwest for executing synchronous HTTP requests against the Ethos server's REST API. It supports outputting results in both a human-readable format and a specialized QMD-compatible JSON format required for integration with agentic workflows.

Sources: ethos-cli/src/main.rs:1-12, ethos-cli/Cargo.toml:1-14, README.md:213-217

Architecture and Command Structure

The CLI is structured around three primary subcommands: search, query, and status. It is configured via command-line arguments or environment variables, specifically ETHOS_HTTP_URL, which defaults to http://127.0.0.1:8766.

Subcommand Definitions

Command	Alias	Purpose
search	N/A	Performs semantic search against the Ethos memory engine.
query	search	An alias for the search command, providing the same functionality.
status	N/A	Queries the /health endpoint of the Ethos server to report system status.

Sources: ethos-cli/src/main.rs:16-75

Data Flow for Search Operations

The following diagram illustrates the flow of a search request from the CLI through the Ethos infrastructure.

The CLI acts as a bridge between the user (or an automated tool like OpenClaw) and the memory engine's HTTP server.

Sources: ethos-cli/src/main.rs:125-155, ethos-server/src/http.rs:133-157

QMD Protocol Compatibility

A critical feature of ethos-cli is its compatibility with the QMD wire protocol. When the --json flag is provided, the CLI transforms standard EthosSearchResult objects into a specific QmdResult structure.

QMD Data Transformation Logic

The transformation involves several specific formatting rules to match the expected QMD output:

• DocID Generation: Constructed by prepending # to the first 6 hex characters of the memory's UUID (with dashes removed).
• File URI: Formatted as ethos://memory/{uuid}.
• Title: Extracted from the first non-empty line of the content, truncated to 60 characters.
• Snippet: Formatted with a diff-header (@@ -1,4 @@) followed by the content truncated to 300 characters.

Sources: ethos-cli/src/main.rs:101-123

QMD Result Schema

Field	Type	Description
docid	String	Short ID (e.g., #7b5c24)
score	f64	Cosine similarity score (0.0–1.0)
file	String	Source URI protocol ethos://memory/
title	String	Capped first line of content
snippet	String	Diff-header format + preview

Sources: ethos-cli/src/main.rs:88-99

Server Interaction and API Integration

The CLI interacts with the ethos-server via its REST API endpoints. The server must have the HTTP subsystem enabled in its configuration for the CLI to function.

The CLI handles connection failures and non-success HTTP status codes by printing error messages to stderr and exiting with a non-zero status code.

Sources: ethos-cli/src/main.rs:142-155, ethos-server/src/http.rs:37-65, ethos-server/src/main.rs:103-115

Health and Status Monitoring

The status command provides insight into the backend engine's health by consuming the /health endpoint. This includes the versions of the server, PostgreSQL, and pgvector, as well as the status of the Unix socket.

// ethos-cli/src/main.rs:189-195
match resp {
    Ok(r) if r.status().is_success() => {
        let body: serde_json::Value = r.json().unwrap_or_default();
        println!("Ethos server: {}", body["status"].as_str().unwrap_or("unknown"));
        println!("Version:      {}", body["version"].as_str().unwrap_or("?"));
        println!("PostgreSQL:   {}", body["postgresql"].as_str().unwrap_or("?"));
        println!("pgvector:     {}", body["pgvector"].as_str().unwrap_or("?"));
// ...

Sources: ethos-cli/src/main.rs:182-206, ethos-server/src/http.rs:101-124

Configuration and Dependencies

The CLI is a standalone binary within the Ethos workspace. Its dependencies are managed in a local Cargo.toml, while inheriting some settings from the workspace root.

• clap: Used for command-line argument parsing with "derive" and "env" features.
• reqwest: Configured with blocking and rustls-tls for synchronous networking.
• serde / serde_json: Used for serializing QMD output and deserializing server responses.
• anyhow: Employed for flexible error handling.

Sources: ethos-cli/Cargo.toml:10-15, Cargo.toml:1-60

Summary

The ethos-cli utility is a critical integration component of the Ethos project. By providing a QMD-compatible interface, it allows existing agent frameworks to leverage Ethos's advanced neuromorphic memory features—such as semantic search and spreading activation—without requiring significant changes to their internal tooling. It acts as a lightweight, reliable gateway to the memory engine's capabilities.