# OpenClaw Workspace Import

MindRoom supports a practical OpenClaw-compatible workflow focused on workspace portability:

- Reuse your OpenClaw markdown files (`SOUL.md`, `AGENTS.md`, `USER.md`, `MEMORY.md`, etc.) after copying them into the agent's canonical MindRoom workspace
- Use the `openclaw_compat` preset to enable a native MindRoom tool bundle
- Use MindRoom's unified memory backend (`memory.backend`) for persistence
- Optionally add semantic recall over workspace files via knowledge bases

## What this is (and is not)

MindRoom is compatible with OpenClaw workspace patterns, not a full OpenClaw gateway clone.

Works well:

- File-based identity and memory documents
- OpenClaw-inspired behavior and instructions
- Native MindRoom tool bundle via the `openclaw_compat` preset
- Native Matrix messaging via the `matrix_message` tool in the preset bundle
- Native sub-agent session orchestration via the `subagents` tool in the preset bundle

Not included:

- OpenClaw gateway control plane
- Device nodes and canvas platform tools
- OpenClaw alias-name wrapper APIs like `exec`, `process`, `web_search`, and `web_fetch`
- `tts` and `image` aliases (use MindRoom's native TTS/image tools directly)
- Heartbeat runtime - schedule heartbeats via `cron`/`scheduler` instead

## The `openclaw_compat` preset

`openclaw_compat` is a config macro, not a runtime toolkit.
`Config.get_agent_tools` expands it into native MindRoom tools and dedupes while preserving order.

Preset expansion:

- `shell`
- `coding`
- `duckduckgo`
- `website`
- `browser`
- `scheduler`
- `subagents`
- `matrix_message`
- `attachments` (auto-implied by `matrix_message` via `IMPLIED_TOOLS`, not listed in the preset directly)

Memory is not a separate OpenClaw subsystem in MindRoom.
It uses the normal MindRoom memory backend.

## Drop-in config

Use this as a starting point for importing an OpenClaw workspace into MindRoom's canonical agent workspace:

```yaml
agents:
  openclaw:
    display_name: OpenClawAgent
    include_default_tools: false
    learning: false
    memory_backend: file
    model: opus
    role: OpenClaw-style personal assistant with persistent file-based identity and memory.
    rooms: [personal]

    instructions:
      - You wake up fresh each session with no memory of previous conversations. Your context files are already loaded into your system prompt.
      - Important long-term context is persisted by the configured MindRoom memory backend. If something must be preserved exactly, write/update the relevant file directly.
      - MEMORY.md is curated long-term memory; daily files are short-lived notes and logs.
      - Ask before external/public actions and destructive operations.
      - Before answering prior-history questions, search memory files first with `search_memories`.

    context_files:
      - SOUL.md
      - AGENTS.md
      - USER.md
      - IDENTITY.md
      - TOOLS.md
      - HEARTBEAT.md

    tools:
      - openclaw_compat
      - memory
      - python

    skills:
      - transcribe

memory:
  file:
    max_entrypoint_lines: 200
  search:
    mode: semantic
    include:
      - memory/**/*.md
    include_entrypoint: false
  auto_flush:
    enabled: true
```

When using `memory_backend: file`, the file backend automatically loads `MEMORY.md` from the canonical workspace root, so there is no need to add it to `context_files`.
If you switch to `mem0`, add `MEMORY.md` back to `context_files` if you still want it preloaded.
The `openclaw_compat` preset already expands to native shell, coding, duckduckgo, website, browser, scheduler, sub-agent orchestration, and `matrix_message` tools (`attachments` is auto-implied by `matrix_message`), so listing those tools individually is not necessary.
Copy or sync your OpenClaw files into `agents/openclaw/workspace/` before using this config so `context_files`, file memory, and `search_memories` read the same canonical workspace.
Direct external edits to daily memory files are picked up lazily on the next semantic memory search.
File memory is already searchable on demand through `search_memories`.
When its agent-scoped semantic index is ready, configured file memory is also listed as a read-only source in `search_knowledge_base`.
Use `search_memories` for keyword fallback, team-visible memory, and memory IDs.
Use `knowledge_bases` only for non-memory project documents that should be searchable as external knowledge.

## Recommended workspace layout

```text
mindroom_data/
└── agents/
    └── openclaw/
        └── workspace/
            ├── SOUL.md
            ├── AGENTS.md
            ├── USER.md
            ├── IDENTITY.md
            ├── MEMORY.md
            ├── TOOLS.md
            ├── HEARTBEAT.md
            └── memory/
                ├── YYYY-MM-DD.md
                └── topic-notes.md
```

## Unified memory behavior

OpenClaw-compatible agents use the same memory system as every other MindRoom agent:

- `memory.backend: mem0` for vector memory (global default)
- `memory.backend: file` for file-first memory (global default)
- `memory.backend: none` or `memory: none` to disable built-in durable memory globally
- `memory_backend: file` on an individual agent to override the global default
- `memory_backend: none` on an individual agent to keep that agent stateless
- agents that use file memory store it under `agents/<name>/workspace/`, not under the shared global `memory.file.path` tree
- `context_files` should point into that same canonical workspace if you want one consistent file-first workflow
- optional `knowledge_bases` for semantic recall over arbitrary non-memory workspace folders

Recommended for OpenClaw-style setups: `memory_backend: file` with the canonical workspace layout and `memory.auto_flush.enabled: true`.

## Context Management

MindRoom includes built-in context controls for OpenClaw-style agents:

- **Conversation history** is stored in Agno sessions, but MindRoom decides what replay summary and raw history messages are injected into each run.
- **Replay depth** is controlled with `num_history_runs` or `num_history_messages`, and optional required compaction is controlled with `compaction` (see [Agents](https://docs.mindroom.chat/configuration/agents/)).
- **Preloaded role context** from `context_files` is hard-capped by `defaults.max_preload_chars` (configured in `config.yaml` under `defaults`). When the combined context exceeds this limit, chunks are trimmed from the end and a truncation marker is inserted.

## Known limitations

**Threading model:** MindRoom responds in Matrix threads by default. OpenClaw uses continuous room-level conversations. To match this behavior on mobile or via bridges (Telegram, Signal, WhatsApp), set `thread_mode: room` on the agent - this sends plain room messages with a single persistent session per room instead of creating threads.

## Privacy guidance

`context_files` apply to all rooms for that agent. If `MEMORY.md` is sensitive:

- Keep the agent in private rooms only, or
- Split into private/public agents and exclude sensitive files from the public agent

## Skills

For details on skill eligibility gating (`openclaw.os`, `openclaw.requires`, `openclaw.always`), see [Skills](https://docs.mindroom.chat/skills/).

Skills are loaded from `~/.mindroom/skills/<name>/`. To use an OpenClaw skill like `transcribe`, copy the skill directory from your OpenClaw workspace:

```bash
mkdir -p ~/.mindroom/skills
cp -r /path/to/openclaw-workspace/skills/transcribe ~/.mindroom/skills/
```

Set required environment variables (for example `WHISPER_URL`) as defined in the skill's `SKILL.md` frontmatter.
