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

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 — composited search across working memory, the knowledge graph, and active tasks in parallel

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 gateway restart

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 info openclaw-basic-memory

{
  "openclaw-basic-memory": {
    enabled: true
  }
}

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

{
  "openclaw-basic-memory": {
    enabled: true,
    config: {
      project: "my-agent",        // BM project name (default: "openclaw-{hostname}")
      projectPath: ".",            // Project directory (default: workspace root)
      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
    }
  }
}

When your agent calls memory_search, three sources are queried in parallel:

1. MEMORY.md — text search with surrounding context
2. Knowledge Graph — hybrid full-text + vector search across all indexed notes
3. Active Tasks — scans memory/tasks/ for in-progress work

Results come back in clear sections so the agent knows where each piece of context came from.

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.

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.

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

Six skills ship with the plugin — no installation needed:

• memory-tasks — structured task tracking that survives context compaction
• memory-reflect — periodic consolidation of recent notes into durable memory
• memory-defrag — cleanup and reorganization of memory files
• memory-schema — schema lifecycle (infer, create, validate, diff)
• memory-metadata-search — query notes by frontmatter fields
• memory-notes — guidance for writing well-structured notes

npx skills add basicmachines-co/basic-memory-skills --agent openclaw

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

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.

Disable semantic search — Set BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=false to fall back to full-text only.

• 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