OpenClaw Integration

Why

OpenClaw writes memory files (markdown) which are a solid foundation for long-term memory. But flat files aren't enough to reliably recall what's happening, what needs follow-up, or to build a continuous improvement loop.

Keep integrates with OpenClaw as a context engine — it owns how context is captured, assembled, and enriched across the agent's lifecycle.

What this gives you:

1. Semantic context assembly — every agent turn, keep surfaces relevant

memories: similar items, open commitments, learnings, edge relationships. The agent starts each turn knowing what matters, not just what's recent.

2. Continuous capture — user and assistant messages are ingested as

versioned items after each turn. Background processing (summarize, analyze, tag, link extraction) runs automatically.

3. Inflection-aware reflection — after each turn, keep detects topic shifts,

commitments, and significant moments. When it finds one, it triggers the reflective practice in the background.

4. Memory indexing — daemon-driven watches keep workspace files, memory

markdown, and git history continuously indexed. No manual steps needed.

5. Session persistence — each session is a versioned item keyed by its

routing identity. Turns accumulate as versions. No archival step needed.

6. Memory tools — memory_search and memory_get provide semantic

recall over memory files, replacing OpenClaw's built-in flat-file search.

Quick Start

1. Install the plugin

# From ClawHub (recommended):
openclaw plugins install clawhub:keep

# Or from a local path (for development):
openclaw plugins install -l $(keep config openclaw-plugin)

The plugin auto-configures plugins.slots.contextEngine: "keep" on install.

2. Agent-guided setup

If the Python runtime (keep CLI) is not yet installed, the plugin registers a bootstrap context engine that instructs the agent to guide you through setup. On your first conversation after installing the plugin, the agent will walk you through:

1. Installing keep — uv pip install keep-skill[local]
2. Configuring providers — openclaw keep setup (interactive wizard)
3. Restarting — openclaw gateway restart

You can also do this manually:

uv tool install keep-skill                    # API providers included
# Or: uv tool install 'keep-skill[local]'    # Local models, no API keys needed
keep config --setup                           # Interactive provider wizard
openclaw gateway restart

3. Verify

openclaw plugins list                         # Should show: keep (loaded)
openclaw keep doctor                          # Check keep store health

How It Works

Context Engine (automatic)

When the plugin is installed, OpenClaw activates keep as the context engine (plugins.slots.contextEngine: keep). This means keep participates in every stage of the agent lifecycle:

The agent doesn't need to do anything — context flows in automatically.

Practice Layer (agent-initiated)

The agent also has voluntary access to keep via MCP tools:

keep_flow(state="get", params={item_id: "now"})          # Current intentions
keep_flow(state="query-resolve", params={query: "topic"})        # Semantic search
keep_flow(state="put", params={content: "insight", tags: {type: "learning"}})  # Capture
keep_prompt(name="reflect")                                       # Full reflection
keep_help(topic="flow-actions")                                   # Documentation

These are injected into the agent's system prompt as cacheable static instructions (appendSystemContext), so they don't add per-turn token cost.

Memory Indexing (automatic)

The plugin sets up daemon-driven watches on the workspace directory (including memory/ and MEMORY.md) on the first agent turn. The daemon polls for changes automatically — no manual indexing needed. Git repositories in the workspace are also discovered and their commit history is ingested incrementally.

Memory Tools (memory_search / memory_get)

The plugin registers memory_search and memory_get as agent tools, providing the same interface as OpenClaw's built-in memory-core plugin. OpenClaw's system prompt instructions ("run memory_search before answering questions about prior work...") work automatically.

memory_search(query, maxResults?, minScore?) — Searches MEMORY.md and memory/*.md using keep's semantic search with scope-constrained find. Returns results in memory-core's format: path, startLine, endLine, score, snippet, source. Line positions come from keep's part analysis and keyword fallback.

memory_get(path, from?, lines?) — Safe file read constrained to MEMORY.md and memory/*.md paths. Supports from (1-indexed start line) and lines (count) for slicing. Path validation prevents traversal outside memory paths.

Slot Configuration

The plugin declares kind: "context-engine" in its manifest. On install, OpenClaw automatically sets plugins.slots.contextEngine: "keep".

For memory_search/memory_get, the plugin registers these tools directly at runtime. To avoid conflicts with the built-in memory-core plugin, disable it:

{
  "plugins": {
    "slots": {
      "contextEngine": "keep",
      "memory": "none"
    }
  }
}

If you prefer to keep memory-core active (e.g., for its QMD backend), the plugin's memory_search registration will take precedence when keep is loaded.

Customizing Context Assembly

The context assembly is driven by a keep prompt template (prompt-agent-openclaw-assemble) backed by a state doc (state-get/openclaw). Edit them to change what context the agent sees:

keep get .prompt/agent/openclaw-assemble       # View prompt template
keep get .state/get/openclaw                   # View state doc (retrieval queries)
keep config --reset-system-docs                # Restore defaults

The default runs parallel queries for:

1. intentions — current now content (cross-session intentions)
2. similar — semantically similar items to the current user prompt
3. meta — resolved meta-docs (learnings, todos, open commitments)
4. edges — edge relationships from now (references, speakers, threads)
5. session — the current session item (versioned turn history)

All results are token-budgeted so they fit within the context window.

Plugin Configuration

Configure in OpenClaw's config under plugins.entries.keep.config:

Example:

{
  "plugins": {
    "entries": {
      "keep": {
        "enabled": true,
        "config": {
          "contextBudgetRatio": 0.25
        }
      }
    }
  }
}

CLI Commands

The plugin registers CLI commands under openclaw keep:

Provider Configuration

keep auto-detects AI providers from environment variables:

export OPENAI_API_KEY=...      # Handles both embeddings + summarization
# Or: GEMINI_API_KEY=...       # Also does both
# Or: VOYAGE_API_KEY=... and ANTHROPIC_API_KEY=...  # Separate services

If Ollama is running locally, it's auto-detected with no configuration needed.

For explicit setup: openclaw keep setup or keep config --setup

For local-only operation (no API keys): uv tool install 'keep-skill[local]'

See QUICKSTART.md for full provider options and troubleshooting.

Recommended: Daily Reflection Cron

For automatic deep reflection:

openclaw cron add \
  --name keep-reflect \
  --cron "0 21 * * *" --tz "America/New_York" \
  --session isolated \
  --agent-turn "Daily reflection. Run \keep prompt reflect\ and follow the practice.

This is the deeper review — not just what happened, but what it means."

This runs nightly in an isolated session. Memory files (workspace memory/ directory, MEMORY.md, etc.) are indexed automatically by the plugin's workspace watch — no manual keep put needed.

Integration Layers

Architecture

OpenClaw Gateway (Node.js)
  └── keep plugin (TypeScript, in-process)
        ├── Context Engine
        │     ├── bootstrap (session init)
        │     ├── assemble (prompt template + state doc queries)
        │     ├── afterTurn (message ingest + inflection detection)
        │     ├── compact (advisory)
        │     └── prepareSubagentSpawn, onSubagentEnded
        ├── Bootstrap CE (when keep CLI is missing or unconfigured)
        │     └── assemble → injects setup instructions for agent
        └── MCP Client (stdio transport, global singleton)
              └── keep mcp (Python, persistent process)
                    ├── keep store (SQLite + ChromaDB)
                    └── daemon (watches, git ingest, background work)

The MCP transport is a Symbol.for global singleton that survives gateway soft restarts (SIGUSR1). It spawns keep mcp as a persistent stdio process at gateway start. If the MCP process exits between turns, the plugin auto-reconnects on the next operation. All operations have per-type timeouts (8s for assemble/prompts, 15s for writes, 30s for queries).

Upgrading

After upgrading keep:

uv tool upgrade keep-skill
openclaw gateway restart

If using a local path install:

openclaw plugins install -l $(keep config openclaw-plugin)
openclaw gateway restart

Troubleshooting

Plugin loads but MCP not connected:

keep config                    # Verify keep is configured
keep config providers          # Verify providers are set
openclaw keep doctor           # Run health check

The plugin auto-reconnects MCP on each operation. If the MCP process keeps dying, check keep mcp stderr output or run it manually:

keep mcp                       # Should start and wait on stdin

Context engine not activating: Check that plugins.slots.contextEngine is set to "keep":

grep contextEngine ~/.openclaw/openclaw.json

Slow context assembly: The assemble flow runs parallel queries. If one is slow (e.g., embedding provider timeout), it blocks assembly. Check:

keep doctor --log              # Watch flow execution in real time

Agent sees setup instructions instead of context: The bootstrap context engine is active — keep CLI is either not installed or providers aren't configured. Follow the agent's instructions, then restart.

Reset to defaults:

# Reset context engine slot to legacy
# Edit ~/.openclaw/openclaw.json: set plugins.slots.contextEngine to "legacy"
openclaw gateway restart

# Reset keep's state docs
keep config --reset-system-docs