Give your OpenClaw agent persistent, searchable memory — in plain text files you can read and edit.

Basic Memory stores AI knowledge in local Markdown files and indexes them into a semantic knowledge graph. Your agent writes notes. You can open them in any editor, read them, change them, and the changes sync back automatically. No black box. No proprietary format. Just files.

It does three things that work together:

• Stores knowledge in plain Markdown — everything lives in plain text files on your computer, not locked inside a database you can't read
• Creates connections automatically — notes link to each other through a searchable, traversable knowledge graph
• Searches by meaning, not just keywords — vector search finds relevant context even when the exact words don't match
• Keeps notes consistent — dynamic schemas and validation ensure your knowledge base stays structured and useful as it grows
• Enables two-way collaboration — both you and the AI read and write the same files

Over time, your agent builds a knowledge base that grows with you. Context that survives across sessions. Memory that belongs to you.

Learn more: basicmemory.com · GitHub · Docs

Source now lives in the canonical basic-memory repository under integrations/openclaw/. The npm package remains @basicmemory/openclaw-basic-memory.

Maintainer check from the monorepo root:

just package-check-openclaw

This plugin connects Basic Memory to OpenClaw so your agent can:

• Remember across sessions — search and recall past conversations, decisions, and context
• Track work in progress — structured tasks that survive context compaction
• Build knowledge over time — notes, observations, and relations that grow into a connected graph
• Search intelligently — hybrid full-text and vector search across the knowledge graph

All data stays on your machine as Markdown files indexed locally with SQLite. Cloud sync is available but entirely optional.

Prerequisite: uv (Python package manager) — used to install the Basic Memory CLI.

# macOS
brew install uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Then install the plugin:

openclaw plugins install @basicmemory/openclaw-basic-memory
openclaw config set plugins.slots.memory openclaw-basic-memory
openclaw config set plugins.slots.contextEngine openclaw-basic-memory
openclaw gateway restart

The plugin fills two OpenClaw slots, and each one does a different job:

• memory registers Basic Memory as OpenClaw's memory provider: gateway memory search and status, openclaw doctor health, Active Memory recall, and the pre-compaction memory flush.
• contextEngine runs automatic recall at session start and automatic conversation capture after each turn. Without this slot, nothing is captured or recalled automatically; the agent only remembers what it saves with an explicit tool call.

Tested with OpenClaw 2026.10.9. OpenClaw 2026.10 and later require context engines to commit turns through commitTurn, which this plugin implements; older plugin versions are degraded to OpenClaw's legacy engine on those hosts and capture nothing.

That's it. The plugin auto-installs the bm CLI on first startup if it's not already on your PATH. See SECURITY.md for details on how this works.

Verify:

openclaw plugins list
openclaw plugins inspect openclaw-basic-memory --json
openclaw plugins doctor

{
  plugins: {
    entries: {
      "openclaw-basic-memory": {
        enabled: true
      }
    },
    slots: {
      memory: "openclaw-basic-memory",
      contextEngine: "openclaw-basic-memory"
    }
  }
}

This uses sensible defaults: auto-generated project name, maps to your workspace root, captures conversations, and recalls active tasks on session start.

{
  plugins: {
    entries: {
      "openclaw-basic-memory": {
        enabled: true,
        config: {
          project: "my-agent",        // BM project name (default: "openclaw-{hostname}")
          projectPath: ".",            // Project directory (default: workspace root, or an existing project's folder)
          memoryDir: "memory/",        // Where task notes live
          memoryFile: "MEMORY.md",     // Working memory file
          autoCapture: true,           // Record conversations as daily notes
          autoRecall: true,            // Inject active tasks + recent activity at session start
          debug: false                 // Verbose logging
        }
      }
    },
    slots: {
      memory: "openclaw-basic-memory",
      contextEngine: "openclaw-basic-memory"
    }
  }
}

Agents search Basic Memory with search_notes and read results with read_note. The plugin adds a short system-prompt section that points the agent at these tools.

OpenClaw's built-in memory_search and memory_get tools belong to its bundled Memory Core plugin, which OpenClaw keeps loaded even when this plugin holds the memory slot. Those tools search only the workspace MEMORY.md and memory/ files, not Basic Memory.

As the memory slot owner, the plugin also serves OpenClaw's own memory consumers:

• Gateway memory search, get and status, and openclaw doctor read Basic Memory through the plugin's provider runtime.
• Active Memory deep recall uses search_notes, read_note and build_context.
• Pre-compaction flush saves durable context with write_note and edit_note instead of appending to a workspace file.

Search scores are shown as raw numbers. A score above 1 means the note matched on both keywords and meaning.

On each session start, the plugin loads active tasks and recently modified notes, giving the agent immediate awareness of ongoing work without being asked.

After each conversation turn, the plugin records the exchange as a timestamped entry in a daily note. This builds a searchable history of everything your agent has discussed. Capture requires the contextEngine slot. Each entry carries a hidden <!-- openclaw-turn:... --> marker so a turn OpenClaw retries after a crash is recorded only once.

The plugin keeps a long-lived Basic Memory process running over standard I/O. No cold starts per tool call. The connection auto-reconnects if it drops.

All tools accept an optional project parameter for cross-project operations.

Use the dedicated frontmatter parameters when creating structured notes:

write_note(
  title="auth-middleware-rollout",
  folder="tasks",
  note_type="Task",
  tags=["auth", "rollout"],
  metadata={"status": "active", "current_step": 2},
  content="""## Context
Rolling JWT middleware to all API routes."""
)

edit_note accepts metadata alongside any edit operation, so content and frontmatter state can be updated in one call. Metadata keys supplied by the caller are merged into existing frontmatter; unrelated fields remain unchanged.

openclaw basic-memory search "auth patterns" --limit 5
openclaw basic-memory read "projects/api-redesign"
openclaw basic-memory context "memory://projects/api-redesign" --depth 2
openclaw basic-memory recent --timeframe 24h
openclaw basic-memory status

These skills ship with the plugin — no installation needed:

• memory-comark — charts, tables, boards, and live views in notes with ::bm-* components
• memory-defrag — cleanup and reorganization of a project's notes
• memory-ingest — import existing material into Basic Memory
• memory-lifecycle — manage note/project lifecycle workflows
• memory-literary-analysis — analyze texts and reading notes
• memory-metadata-search — query notes by frontmatter fields
• memory-notes — guidance for writing well-structured notes
• memory-okf — make a project ready for OKF export
• memory-onboarding — guided setup of a new knowledge system
• memory-reflect — periodic consolidation of recent notes into durable memory
• memory-research — research synthesis into durable notes
• memory-schema — schema lifecycle (infer, create, validate, diff)
• memory-tasks — structured task tracking that survives context compaction

bun run fetch-skills

In the monorepo, this copies from the canonical top-level skills/ directory into the generated integrations/openclaw/skills/ package bundle.

The plugin works well with structured task notes in memory/tasks/:

---
title: auth-middleware-rollout
type: Task
status: active
current_step: 2
---

## Context
Rolling JWT middleware to all API routes.

## Plan
- [x] Implement middleware
- [x] Add refresh-token validation
- [ ] Roll out to staging
- [ ] Verify logs and error rates

Set status: done to mark complete. Done tasks are filtered out of active task results.

Everything works locally. Cloud adds cross-device sync, team workspaces, and persistent memory for hosted agents.

• Same knowledge graph on laptop, desktop, and CI
• Shared workspaces for teams
• Durable memory for production agents

Cloud extends local-first — still plain Markdown, still yours. Start a free trial and use code BMCLAW for 20% off for 3 months. See BASIC_MEMORY.md for setup.

bm not found — Install uv, then restart the gateway. Or install manually: uv tool install basic-memory --prerelease=allow (the flag is required — basic-memory depends on a FastMCP pre-release, and without it uv silently installs an older release)

Search returns nothing — Check that Basic Memory connected (look for connected to BM in logs). Verify files exist in the project directory.

Jiti cache issues — rm -rf /tmp/jiti/ "$TMPDIR/jiti/" then restart the gateway.

• Memory + Task Flow — practical runbook
• Cloud Setup — configure Basic Memory Cloud
• Security — how auto-installation and data handling work
• Development — contributing, tests, publishing
• Basic Memory docs
• Issues

This plugin does not collect telemetry. The Basic Memory CLI may send anonymous usage analytics — see the Basic Memory docs for opt-out instructions.

MIT