OpenClaw Integration

Relevant source files

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

• README.md
• ethos-ingest-ts/src/index.ts
• ethos-cli/src/main.rs
• ethos-server/src/http.rs
• ethos-server/src/main.rs
• ethos-ingest-ts/tests/setup.test.ts

Ethos integrates with the OpenClaw ecosystem to provide AI agents with a standalone long-term memory service. This integration allows agents to passively record every conversation turn and automatically surface relevant context without requiring manual memory management or significant changes to agent code. Ethos acts as a "Hippocampus" for OpenClaw agents, handling the transition of short-term episodic traces into durable semantic knowledge.

Sources: README.md:1-15, README.md:154-156

Integration Architecture

The integration relies on a dual-hook system implemented in TypeScript and a QMD-compatible CLI for semantic search. The system operates through Unix domain socket IPC for high-speed ingestion and a REST API for search and retrieval.

The diagram shows the flow of messages from OpenClaw hooks to the Ethos server via IPC and the injection of context back into the agent workspace.
Sources: README.md:83-112, ethos-ingest-ts/src/index.ts:1-40

Ingestion Pipeline

Ingestion is handled via the ethos-ingest hook. This hook captures both incoming and outgoing messages within the OpenClaw pipeline, ensuring a complete record of the conversation.

Event Handling

The integration hooks into two primary OpenClaw events:

• message:received: Captures user input and records it with the source set to user.
• message:sent: Captures assistant responses and records them with the source set to assistant.

Sources: ethos-ingest-ts/src/index.ts:13-35, ethos-ingest-ts/tests/setup.test.ts:31-45

Data Structure

Every captured message is packaged into an "ingest" action containing the message content and metadata (channel, author, and timestamp).

Field	Type	Description
action	String	Must be set to "ingest".
payload.content	String	The raw text of the message.
payload.source	String	Either "user" or "assistant".
payload.metadata	Object	Includes channel, author, and ts (ISO string).

Sources: ethos-ingest-ts/src/index.ts:15-32, README.md:183-195

Context Injection and Retrieval

Ethos provides context to OpenClaw agents through semantic search and the generation of an ETHOS_CONTEXT.md file in the agent workspace.

QMD Wire Protocol Compatibility

For active memory searching, the ethos-cli serves as a drop-in replacement for the qmd binary. OpenClaw's memory_search tool invokes ethos-cli search <query> -n <limit> --json to retrieve relevant memories.

The sequence shows how OpenClaw utilizes the CLI to interface with the Ethos search engine.
Sources: ethos-cli/src/main.rs:1-15, ethos-cli/src/main.rs:105-145

QMD Output Format

The CLI transforms internal Ethos search results into the specific JSON format expected by OpenClaw's QMD manager.

QMD Field	Ethos Mapping	Format/Example
docid	Short UUID	# + first 6 hex chars (e.g., #7b5c24)
score	Cosine Similarity	0.0 – 1.0
file	Memory URI	ethos://memory/{uuid}
title	Content Preview	First non-empty line (capped at 60 chars)
snippet	Diff-header snippet	@@ -1,4 @@ + content (truncated 300 chars)

Sources: ethos-cli/src/main.rs:80-101, ethos-cli/src/main.rs:188-210

Configuration

Integration requires enabling hooks in the OpenClaw configuration file (openclaw.json or similar).

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "ethos-ingest": { "enabled": true },
        "ethos-context": { "enabled": true }
      }
    }
  }
}

Sources: README.md:158-171

The integration also depends on the following server environment settings:

• ETHOS_SOCKET: Path to the Unix socket (defaults to /tmp/ethos.sock).
• ETHOS_HTTP_URL: Base URL for the REST API (defaults to http://127.0.0.1:8766).

Sources: ethos-ingest-ts/src/index.ts:6, ethos-cli/src/main.rs:19, ethos-server/src/http.rs:59

Technical Specifications

IPC Protocol

Communications via the Unix domain socket use Little-endian (LE) framed MessagePack.

• Header: 4-byte LE u32 length prefix.
• Payload: Named fields/maps serialized via MessagePack.

Sources: README.md:114-124, ethos-ingest-ts/tests/client-request.test.ts:41-48

HTTP Endpoints for OpenClaw

The Rust server provides several REST endpoints utilized by the integration components.

Endpoint	Method	Component	Purpose
/search	POST	ethos-cli	Semantic search with optional spreading activation.
/ingest	POST	Web UI/Hooks	Manual or HTTP-based ingestion.
/health	GET	ethos-cli	Verify connectivity and DB status.

Sources: ethos-server/src/http.rs:36-42, ethos-cli/src/main.rs:152-164

Summary

The OpenClaw integration provides a non-intrusive memory layer for AI agents. By capturing conversation turns via passive hooks and exposing memories through a QMD-compatible CLI, Ethos enables agents to build persistent context and "forget" noise naturally through decay, without requiring custom prompt engineering or manual state management.