# EverOS OpenClaw Plugin

Persistent memory for **OpenClaw** through normal conversation.

This plugin keeps the current OpenClaw `context-engine` architecture and connects it to a self-hosted EverOS backend powered by [EverOS](https://github.com/EverMind-AI/EverOS).

## What it does

- Recalls relevant memory before each reply through `assemble()`
- Saves new conversation content after each turn through `afterTurn()`
- Works through normal natural-language chat
- Does not require manual `memory_store` or `memory_search` tool calls

Important:

- This is a `context-engine` plugin
- This is not a `memory` slot plugin
- To avoid conflicts, installation sets `plugins.slots.memory = "none"`

## Quick start

Recommended install:

```bash
npx --yes --package @evermind-ai/openclaw-plugin everos-install
```

The installer:

- reuses `~/.openclaw/openclaw.json` if it already exists
- adds the plugin path to `plugins.load.paths`
- adds `evermind-ai-everos` to `plugins.allow`
- sets `plugins.slots.contextEngine = "evermind-ai-everos"`
- sets `plugins.slots.memory = "none"`
- creates or updates the plugin entry with sane defaults

After install:

```bash
openclaw gateway restart
```

Then verify with natural language:

```text
Remember: I like espresso.
What coffee do I like?
```

## Backend

Default backend URL:

```text
http://localhost:1995
```

Health check:

```bash
curl http://localhost:1995/health
```

If you have not started the EverOS backend yet:

```bash
git clone https://github.com/EverMind-AI/EverOS.git
cd EverOS
docker compose up -d
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
cp env.template .env
# edit .env
uv run python src/run.py
```

## How natural-language memory works

Runtime flow:

1. The user sends a normal message.
2. `assemble()` searches the EverOS backend for relevant memory.
3. Matching memory is injected as context.
4. OpenClaw replies normally.
5. `afterTurn()` saves the new turn back to the EverOS backend.

This means the user experience is:

- "Remember: I prefer dark mode"
- later: "What UI style do I prefer?"

without any explicit memory tool usage.

## OpenClaw config

Expected config shape:

```json
{
  "plugins": {
    "allow": ["evermind-ai-everos"],
    "slots": {
      "memory": "none",
      "contextEngine": "evermind-ai-everos"
    },
    "entries": {
      "evermind-ai-everos": {
        "enabled": true,
        "config": {
          "baseUrl": "http://localhost:1995",
          "userId": "everos-user",
          "groupId": "everos-group",
          "topK": 5,
          "memoryTypes": ["episodic_memory"],
          "retrieveMethod": "hybrid",
          "apiVersion": "auto",
          "agentMode": false
        }
      }
    }
  }
}
```

## Configuration

| Field | Default | Description |
| --- | --- | --- |
| `baseUrl` | `http://localhost:1995` | EverOS backend URL |
| `userId` | `everos-user` | Memory owner identity |
| `groupId` | `everos-group` | Shared memory namespace |
| `topK` | `5` | Max retrieved entries |
| `memoryTypes` | `["episodic_memory"]` | Memory types to search; `agent_memory` is auto-added when `agentMode` is on |
| `retrieveMethod` | `hybrid` | Retrieval mode (`keyword` / `vector` / `hybrid` / `agentic`; `rrf` deprecated) |
| `apiVersion` | `auto` | Backend API version; `auto` probes once at bootstrap, `v1` / `legacy` to force |
| `agentMode` | `false` | Capture full tool-call trajectories — see [Agent Memory](#agent-memory) below |

## Agent Memory

When the backend is on V1 EverMemOS (auto-detected), set `agentMode: true` to enable a richer memory loop that captures the agent's full tool-call trajectory (not just the user/assistant text):

```json
"config": {
  ...
  "agentMode": true
}
```

### What changes when `agentMode` is on

- **Write path** switches from `POST /api/v1/memories` (text-only) to `POST /api/v1/memories/agent` — the entire turn is sent including `tool_calls` (assistant) and `tool_call_id`-chained results (tool role).
- **Search path** auto-includes `agent_memory` in the search request, so retrieval surfaces:
  - **`agent_case`** — concrete past trajectories (task intent, the approach the agent actually took, key decision insights, quality score)
  - **`agent_skill`** — clustered, reusable patterns extracted from multiple cases (name, description, pattern body, confidence, maturity score)
- **Prompt injection** adds `<skills>` and `<cases>` blocks before the existing `<episodic>` block — high-confidence reusable patterns are surfaced first.

### Why opt in

In testing on a tool-heavy task (4-day Kyoto trip planning with web_search + doc_create + Feishu API scripting):

- First run: agent ran 18-message trajectory of tool calls (web search, blocks JSON build, custom Python script for Feishu API append) to produce the result.
- A similar follow-up ("plan a 7-day Sapporo trip"): with the previously-extracted skill `Multi-Part Travel Planning with Document Automation` injected into the prompt, the agent **reused the pattern directly** and produced the answer in 2 messages — no exploratory tool calls needed.

The trade-offs you should know:

| Cost | Notes |
| --- | --- |
| Larger writes per turn | Trajectory POST is 5-10× the size of text-only |
| Backend LLM cost | Each agent trajectory triggers one extra LLM call for `agent_case` extraction (~7s, runs async on the backend) |
| Boundary lag | Cases are extracted on conversation boundary (or via flush); short single-turn DMs may not produce a case until enough context accumulates |
| Backend requirement | Requires V1 EverMemOS; on legacy backends the plugin warns once and falls back to text-only |

If you don't opt in, the plugin behaves exactly as 2.0 (text-only writes, episodic memory only). On a V1 backend, the plugin logs a one-time hint at startup nudging you to enable it:

```text
[evermind-ai-everos] tip: backend supports V1 agent memory.
Set "agentMode": true in the plugin config to enable agent_case / agent_skill retrieval.
```

## Manual install

```bash
npm install -g @evermind-ai/openclaw-plugin
everos-install
```

## Troubleshooting

| Problem | Fix |
| --- | --- |
| Plugin not loading | Check `plugins.allow`, `plugins.load.paths`, and `plugins.slots.contextEngine` |
| Backend connection failed | Verify `baseUrl` and run `curl <baseUrl>/health` |
| Memory not recalled | Check backend data and try a more specific query |
| Memory not saved | Verify the EverOS backend write API is healthy |
| Conflict with another memory plugin | Ensure `plugins.slots.memory = "none"` |

## Related files

- `index.js`: plugin entry point (register)
- `src/engine.js`: ContextEngine lifecycle hooks
- `src/convert.js`: OpenClaw message to EverOS format conversion
- `src/api.js`: EverOS backend REST client
- `src/messages.js`: message normalization and turn collection
- `src/prompt.js`: memory search response parsing and prompt building
- `src/subagent-assembler.js`: memory context assembly
- `bin/install.js`: installer and config bootstrap
- `openclaw.plugin.json`: plugin metadata and config schema

## License

Apache-2.0