openclaw-memory

Files (11)

• SKILL.md
• active-memory.md · references/
• dreaming.md · references/
• honcho-persistence.md · references/
• memory-builtin.md · references/
• memory-config.md · references/
• memory-honcho.md · references/
• memory-overview.md · references/
• memory-qmd.md · references/
• memory-search.md · references/
• memory.md · references/

SKILL.md (first lines)

## Routing hints

You should route to this skill when the user asks about OpenClaw memory — backends (builtin/QMD/Honcho), embedding providers, active memory, dreaming, the memory search config, `~/.openclaw/memory/`, semantic search, or memory compaction. References: `memory-config.md`, `memory-builtin.md`, `memory-qmd.md`, `memory-honcho.md`, `dreaming.md`, `memory-search.md`, `embedding-providers.md`, `memory-compaction.md`, `memory-cli.md`, `memory-plugins.md`.


# OpenClaw Memory

OpenClaw memory spans three layers: **what files get written**, **which backend indexes them**, and **how search retrieves results**. Getting any one of those wrong means broken recall.

## Layer map

| Layer | Lives under | What it does |
|---|---|---|
| **Memory files** | `~/.openclaw/workspace/` | `MEMORY.md`, `memory/YYYY-MM-DD.md`, `DREAMS.md` |
| **Active memory backend** | `plugins.slots.memory` + `memory.backend` | Which plugin owns recall/search |
| **Search config** | `agents.defaults.memorySearch` | Which embedding provider, hybrid weights, MMR, decay |
| **Memory-wiki** | `plugins.entries.memory-wiki` | Optional compiled knowledge vault layer |

---

## The slot override: `plugins.slots.memory`

Every memory backend is selected through `plugins.slots.memory`. This is the single override point — you set the slot once, and all three backends plug in through it.

```json5
plugins: {
  slots: { memory: "memory-core" },  // default — builtin SQLite
  // slots: { memory: "openclaw-honcho" }  // Honcho
  // slots: { memory: "none" }  // disable memory plugins entirely
}
```

**⚠️ For Honcho: you MUST set `plugins.slots.memory = "openclaw-honcho"`.** Honcho registers its own tools (`honcho_context`, `honcho_search_conclusions`, `honcho_search_messages`, `honcho_session`, `honcho_ask`) AND requires the memory slot to be set to `openclaw-honcho` to function as the memory backend. Leave `slots.memory` at default (`memory-core`) only when using builtin or QMD.

---

## Three backends

### Builtin (default) — `memory-core`

No config needed. Auto-detects any OpenAI/Gemini/Voyage/Mistral/Bedrock API key and enables hybrid search.

```json5
plugins: { slots: { memory: "memory-core" } }
```

Best for: getting started, simple single-agent setups.

### QMD — local reranking sidecar

```json5
memory: { backend: "qmd" }
plugins: { slots: { memory: "memory-core" } }  // QMD hooks through memory-core
```

Adds: BM25 + vector reranking, query expansion, indexing of paths outside workspace, session transcript recall.

Prerequisites: `npm install -g @tobilu/qmd` (or `bun install -g @tobilu/qmd`), QMD on `PATH`.

QMD home: `~/.openclaw/agents/<agentId>/qmd/`. OpenClaw manages collection lifecycle automatically. Falls back to builtin if QMD is unavailable.

### Honcho — cross-session, user modeling

```json5
plugins: {
  slots: { memory: "openclaw-honcho" },
  entries: {
    "openclaw-honcho": {
      enabled: true,
      config: {
        workspaceId: "openclaw",        // memory isolation namespace
        baseUrl: "http://127.0.0.1:8000" // self-hosted; omit for managed
        // apiKey: "..."                 // only for managed api.honcho.dev
      }
    }
  }
}
```

| Hosting | `baseUrl` | `apiKey` |
|---|---|---|
| Self-hosted | `http://127.0.0.1:8000` (or your host) | omit |
| Managed (api.honcho.dev) | omit (defaults to managed) | required |

Tools registered: `honcho_context`, `honcho_search_conclusions`, `honcho_search_messages`, `honcho_session`, `honcho_ask`.

Honcho vs QMD vs builtin:

| | Builtin/QMD | Honcho |
|---|---|---|
| Storage | Workspace Markdown | Dedicated service (local or hosted) |
| Cross-session | Via memory files | Automatic after every turn |
| User modeling | Manual | Automatic profiles |
| Search | Vector + keyword hybrid | Semantic over observations |
| Multi-agent | Not tracked | Parent/child awareness |
| Tools | `memory_search`, `memory_get` | `honcho_*` + `memory_*` |
| Install | Built-in (builtin) / npm (QMD) | Plugin |

---

## Embedding providers

Configured under `agents.defaults.memorySearch`, used by builtin and QMD backends.

| Provider | ID | Auto | Notes |
|----------|-----|------|-------|
| OpenAI | `openai` | ✅ | `text-embedding-3-small` default |
| Gemini | `gemini` | ✅ | Supports multimodal (image + audio) |
| Voyage | `voyage` | ✅ | |
| Mistral | `mistral` | ✅ | |
| Ollama | `ollama` | ❌ | Set explicitly |
| Local | `local` | ✅ (first) | GGUF model, ~0.6GB auto-download |
| Bedrock | `bedrock` | ✅ | AWS SDK credential chain, no API key |

Auto-detect order: `local` → `openai` → `gemini` → `voyage` → `mistral` → `bedrock`

**Pinning a provider** (recommended for production):

```json5

From Hashi-Ai-Dev/openclaw-clawdoc, MIT.

More from Hashi-Ai-Dev/openclaw-clawdoc