# OpenClaw Plugin

> Give OpenClaw agents persistent Basic Memory with composited search, auto-capture, slash commands, and bundled workflow skills.

The [openclaw-basic-memory](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/openclaw) plugin connects Basic Memory to OpenClaw, giving agents persistent, searchable memory stored as plain Markdown files. Agents gain composited memory search, automatic context recall, conversation capture, slash commands, and bundled workflow skills — all with zero configuration.
The plugin is open source and lives in the basic-memory monorepo — browse the source in [`integrations/openclaw`](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/openclaw).

<tip>

Requires [OpenClaw](https://openclaw.dev) and [uv](https://docs.astral.sh/uv/) (`brew install uv` or the curl installer). The plugin auto-installs the `bm` CLI via uv on first startup if it's not already on your PATH.

</tip>

---

## Installation

<docs-video alt="Installing the plugin and pointing it at a Basic Memory Cloud project" poster="/videos/posters/docs-openclaw-cloud.png" src="/videos/docs-openclaw-cloud.mp4">



</docs-video>

Install the plugin and restart the gateway:

```bash
openclaw plugins install @basicmemory/openclaw-basic-memory
openclaw gateway restart
```

That's the whole install. It enables the plugin and claims OpenClaw's `memory`
slot for you — you should see it report:

```text
Exclusive slot "memory" switched from "memory-core" to "openclaw-basic-memory".
Installed plugin: openclaw-basic-memory
```

Verify with `openclaw plugins doctor`, which prints the project it resolved and
`No plugin issues detected.`

By default the plugin creates and uses a project named `openclaw-{hostname}`. To
point it at a project you already have, add a `config` block in
`~/.openclaw/openclaw.json`:

```json5
{
  plugins: {
    entries: {
      "openclaw-basic-memory": {
        enabled: true,
        config: { project: "My Project" }
      }
    }
  }
}
```

<note>

OpenClaw needs to be working with a model provider before any of this. Setting
that up is covered in OpenClaw's own documentation, not here.

</note>

### Using Basic Memory Cloud

By default the plugin writes to a **local** project on that machine. If you want
your agent's memory in Basic Memory Cloud — synced across devices, shared with a
team, reachable from hosted agents — point it at a cloud-routed project.

Sign in once:

```bash
bm cloud login
```

Then either use a project you already have, or create one routed to Cloud:

```bash
bm project add my-agent --cloud --workspace "My Workspace"
```

Name that project for the plugin:

```bash
openclaw config set plugins.entries.openclaw-basic-memory.config.project "my-agent"
```

That writes the same thing you could set by hand in `~/.openclaw/openclaw.json`:

```json5
{
  plugins: {
    entries: {
      "openclaw-basic-memory": {
        enabled: true,
        config: { project: "my-agent" }
      }
    }
  }
}
```

`openclaw plugins doctor` will report the project it resolved. Confirm the
routing with `bm project list` — the project's **Route** column should read
`cloud`. From then on everything the agent writes lands in your cloud workspace,
and anything already there is available to it.

---

## Configuration

The plugin works out of the box with `enabled: true`. For advanced setups, configure via your OpenClaw plugin settings:

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        project
      </code>
    </td>
    
    <td>
      <code>
        openclaw-{hostname}
      </code>
    </td>
    
    <td>
      Basic Memory project name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        projectPath
      </code>
    </td>
    
    <td>
      <code>
        .
      </code>
      
       (workspace root)
    </td>
    
    <td>
      Path to project directory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        memoryDir
      </code>
    </td>
    
    <td>
      <code>
        memory/
      </code>
    </td>
    
    <td>
      Directory for memory files
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        memoryFile
      </code>
    </td>
    
    <td>
      <code>
        MEMORY.md
      </code>
    </td>
    
    <td>
      Primary memory file name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        autoCapture
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Record conversation turns as daily notes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        autoRecall
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Load active tasks and recent notes at session start
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        debug
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Enable debug logging
    </td>
  </tr>
</tbody>
</table>

---

## How It Works

### Composited Memory Search

When your agent searches memory, the plugin queries three sources in parallel and merges the results:

1. **MEMORY.md** — Text search of your primary memory file
2. **Knowledge Graph** — Hybrid full-text + vector search across all notes
3. **Active Tasks** — Scans `memory/tasks/` for in-progress work

This means a single search returns context from structured notes, free-form memory, and active task tracking simultaneously.

### Auto-Recall

At session start, the plugin automatically loads active tasks and recent notes so your agent has immediate context without you needing to ask.

<docs-video alt="An agent recalling open tasks at session start, then writing back to the note" poster="/videos/posters/docs-openclaw-remembers.png" src="/videos/docs-openclaw-remembers.mp4">



</docs-video>

### Auto-Capture

Conversation turns are recorded as timestamped entries in daily notes, building a searchable log of your interactions over time.

### Persistent Connection

The plugin maintains a long-lived Basic Memory process over stdio, avoiding startup overhead on each tool call.

### Multi-Project & Cloud Access

Because the plugin uses the full Basic Memory stack, your OpenClaw agent has access to every project in your knowledge base — not just a single workspace. Use `list_memory_projects` to browse projects, then pass the optional `project` parameter on any tool call to operate on a different project.

This also means your agent benefits from [local/cloud routing](/cloud/routing). You can keep the agent's own memory local while routing shared or team projects through Basic Memory Cloud, or run everything in the cloud for cross-device access. The agent uses the same tools either way — routing is transparent.

In practice, your OpenClaw agent gets:

- **Its own long-term memory** — auto-captured conversations and task tracking that persist across sessions
- **Access to external projects** — search and read notes from any project in your knowledge base
- **Local/cloud hybrid** — mix local and cloud-routed projects depending on sensitivity, collaboration needs, or device portability

---

## Agent Tools

The plugin exposes Basic Memory's tools to your OpenClaw agent:

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        memory_search
      </code>
    </td>
    
    <td>
      Composited search across all memory sources
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        memory_get
      </code>
    </td>
    
    <td>
      Retrieve a specific memory entry
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        search_notes
      </code>
    </td>
    
    <td>
      Full-text and semantic search across notes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        read_note
      </code>
    </td>
    
    <td>
      Read a note by title, permalink, or memory:// URL
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        write_note
      </code>
    </td>
    
    <td>
      Create or update a note
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        edit_note
      </code>
    </td>
    
    <td>
      Incremental edits (append, prepend, find/replace, replace section)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        delete_note
      </code>
    </td>
    
    <td>
      Delete a note from the knowledge base
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        move_note
      </code>
    </td>
    
    <td>
      Move a note with database consistency
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        build_context
      </code>
    </td>
    
    <td>
      Navigate the knowledge graph via memory:// URLs
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list_memory_projects
      </code>
    </td>
    
    <td>
      List all projects with status
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list_workspaces
      </code>
    </td>
    
    <td>
      List available workspaces
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        schema_validate
      </code>
    </td>
    
    <td>
      Validate notes against a schema
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        schema_infer
      </code>
    </td>
    
    <td>
      Infer a schema from existing notes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        schema_diff
      </code>
    </td>
    
    <td>
      Detect schema drift
    </td>
  </tr>
</tbody>
</table>

---

## Slash Commands

Three built-ins, plus one command per bundled skill (the skill name minus the `memory-` prefix):

<table>
<thead>
  <tr>
    <th>
      Command
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        /bm-setup
      </code>
    </td>
    
    <td>
      Install or update the Basic Memory CLI (requires uv)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /remember
      </code>
    </td>
    
    <td>
      Save something to memory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /recall
      </code>
    </td>
    
    <td>
      Search and retrieve from memory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /tasks
      </code>
    </td>
    
    <td>
      Manage structured task notes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /reflect
      </code>
    </td>
    
    <td>
      Review conversations and extract insights
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /defrag
      </code>
    </td>
    
    <td>
      Split bloated files, merge duplicates, restructure
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /schema
      </code>
    </td>
    
    <td>
      Schema lifecycle — infer, validate, detect drift
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /notes
      </code>
      
      , <code>
        /ingest
      </code>
      
      , <code>
        /lifecycle
      </code>
      
      , <code>
        /metadata-search
      </code>
      
      , <code>
        /research
      </code>
    </td>
    
    <td>
      One per remaining bundled skill
    </td>
  </tr>
</tbody>
</table>

---

## Bundled Skills

The plugin bundles a core subset of the [skills collection](/integrations/skills) — drawn from the same source, covering note format, tasks, schemas, reflection, defrag, metadata search, ingest, lifecycle, and research. No separate install needed for those.

<note>

Skills not bundled (like memory-capture, memory-continue, memory-curate, and memory-literary-analysis) can be installed from the [full collection](/integrations/skills).

</note>

---

## Next Steps

<card-group>
<card icon="i-lucide-sparkles" title="Agent Skills" to="/integrations/skills">

Learn more about the individual skills bundled with the plugin.

</card>

<card icon="i-lucide-wrench" title="MCP Tools Reference" to="/reference/mcp-tools-reference">

Full reference for all Basic Memory MCP tools.

</card>

<card icon="i-lucide-cloud" title="Local & Cloud Routing" to="/cloud/routing">

Run some projects locally and others in the cloud.

</card>

<card icon="i-lucide-shield-check" title="Schema System" to="/concepts/schema-system">

Understand schema validation for structured notes.

</card>

<card icon="i-lucide-github" title="GitHub Repository" to="https://github.com/basicmachines-co/basic-memory/tree/main/integrations/openclaw">

Source code, issues, and contributing guide.

</card>
</card-group>