CLI Reference — memory-hybrid

All commands are available via openclaw hybrid-mem <command>.

If you are new here, start with TASKS.md for the task-based map and COMMON-TASKS-CHEATSHEET.md for copy/paste commands.

Note: Below OpenClaw v2026.3.8 the plugin warns at startup (peer + MIN_OPENCLAW_VERSION); CLI subcommands and api.version may be missing. Prefer a current 2026.3.x gateway; CI uses the openclaw version in extensions/memory-hybrid/package-lock.json.

Tip: Verbosity level CLI output is controlled by the config verbosity setting (silent, quiet, normal, verbose). You can change it with openclaw hybrid-mem config-set verbosity silent.

Agent tools (LLM): Commands below are CLI entry points. Tools the agent invokes through the gateway use underscore names only (memory_store, memory_recall, memory_directory, …), with no . in the tool id — required by providers such as Anthropic. memory_directory lists contacts and returns org-centric views (people + fact ids for an organization)—stable structured data, not a replacement for ranked memory_recall search. See CONFIGURATION.md § Agent tool names.

Commands by category

Category Commands
Setup & installation install (setup), verify [--fix] (preflight), doctor [--fix], status, dashboard, config (settings)
Maintenance run-all, compact, prune, checkpoint, backfill-decay, backfill, dream-cycle, resolve-contradictions
Stats & query stats [--efficiency], test, context-audit, search <query>, lookup <id>, forget <id> [--yes], list [--limit, --category, --tier], show <id>, categories
Proposals & corrections proposals list|show|approve|reject <id>, corrections list, corrections approve-all, review
Store & ingestion store <text>, ingest-files, distill, distill-window, record-distill, extract-daily, extract-procedures, extract-directives, extract-reinforcement, generate-auto-skills, skills-suggest, generate-proposals
Reflection & classification reflect, reflect-rules, reflect-meta, classify, build-languages, enrich-entities
Dedup & consolidation find-duplicates, consolidate
Self-correction self-correction-extract, self-correction-run
Export & config export, config, config-mode <mode> (mode), config-set <key> <value> (set)
Credentials & scope credentials migrate-to-vault, scope list|stats|prune|promote
Plugin lifecycle upgrade [version], uninstall
Goals & working memory goals …, goals config, active-tasks, active-tasks config, active-tasks complete <label>, active-tasks stale, active-tasks reconcile, active-tasks hygiene [--dry-run|--apply] [--older-than <duration>], active-tasks add <label> <desc>, active-tasks render, task-queue-status, task-queue-touch

Commands

Command Purpose
stats [--efficiency] [--brief] Rich output (default): storage (SQLite/LanceDB sizes, WAL), knowledge (facts, entities, categories), learned behavior (procedures, directives, rules, patterns, meta-patterns), graph links, operational (credentials, proposals, last distill/reflect/compact), decay distribution. Use --brief for legacy storage + decay only. --efficiency adds tier/source breakdown, token estimates, and token-savings note.
test Memory diagnostics: store a marker fact, verify structured/semantic/hybrid search and auto-recall, then clean up.
context-audit Report token usage per injected context source (auto-recall, procedures, active tasks, workspace files) and recommendations. Active tasks show ledger vs filtered vs injected counts separately from the token budget.
compact Run tier compaction: completed tasks → COLD, inactive preferences → WARM, active blockers → HOT. Prints hot/warm/cold counts.
store --text <text> [options] Store a fact (for scripts; agents use memory_store).
lookup <entity> [--key <key>] [--tag <tag>] [--as-of <date>] [--include-superseded] Exact lookup in SQLite. --as-of = point-in-time (ISO or epoch); --include-superseded = include historical facts.
search <query> [--tag <tag>] [--as-of <date>] [--include-superseded] [--user-id <id>] ... Semantic search over LanceDB + FTS5. --as-of, --include-superseded for bi-temporal queries. Scope filters for user/agent/session.
forget <id> [--yes] Remove a memory by ID (SQLite + LanceDB). ID can be full UUID or a short hex prefix. Without --yes, prints a preview and exits; use --yes to confirm.
extract-daily [--dry-run] [--force\|--full] --days N Extract facts from daily logs (memory/YYYY-MM-DD.md). Override flags accepted for run-all/cron parity (no scan cursor).
prune [--hard] [--soft] [--dry-run] Remove expired facts (decay/TTL). --hard only expired; --soft only confidence decay.
checkpoint Create a checkpoint (pre-flight state).
backfill [--dry-run] [--workspace path] [--limit N] Ingest facts from MEMORY.md / memory/*/.md. Progress bar in TTY.
backfill-decay Backfill decay classes for existing rows.
build-languages [--dry-run] [--model M] Detect top 3 languages from fact samples, generate multilingual trigger/category/decay keywords via LLM, write .language-keywords.json. See MULTILINGUAL-SUPPORT.md.
enrich-entities [--limit N] [--all] [--dry-run] [--model M] [--adaptive-catch-up] [--batch-size N] [--batch-delay-ms N] [--time-budget-sec N] [--max-concurrency N] [--provider-pressure-budget N] [--json] Backfill PERSON/ORG extraction for facts that have no stored entity-mention rows yet (same franc + LLM pipeline as store-time enrichment when graph.enabled). Queue priority is hot → warm → structural → cold, then recent access, recall/access counts, importance, and created-at. Use --limit for bounded catch-up batches or --all for one-shot exhaustive backfill. Add --adaptive-catch-up to automatically ramp throughput after consecutive successful batches and back off on pressure/rate-limit signals (429/retry hints/transient failures), starting from the provided --batch-size/--batch-delay-ms baseline. With adaptive mode, --time-budget-sec stops cleanly between facts/batches, --max-concurrency bounds parallel LLM calls per batch, --provider-pressure-budget stops after cumulative rate-limit/timeout pressure, and --json emits issue #1791 telemetry (avgSecPerFact, provider429s, timeouts, nextRecommendedLimit, nextRecommendedTimeoutSec, etc.).
classify [--dry-run] [--limit N] [--model M] Auto-classify “other” facts using LLM. Progress bar in TTY.
categories List all configured categories with per-category fact counts.
list <type> [--limit N] [--status s] List items by type: patterns, rules, directives, procedures, proposals, or corrections. --limit caps output (default 50). For proposals/corrections, --status filters (e.g. pending). See List, show, and review below.
show <id> Show full details of a fact, procedure, or persona proposal by ID.
proposals list [--status s] List persona proposals (pending, approved, rejected, applied).
proposals approve <id> Approve a persona proposal. Then use openclaw proposals apply <id> to apply to file.
proposals reject <id> [--reason text] Reject a persona proposal.
corrections list [--workspace path] List proposed corrections from the latest self-correction report (memory/reports/self-correction-*.md).
corrections approve [--all] [--workspace path] Apply all suggested TOOLS rules from the latest report to TOOLS.md. Requires --all.
review [--workspace path] Interactive review: step through pending proposals and corrections (a=approve, r=reject, s=skip).
find-duplicates [--threshold 0.92] [--include-structured] [--limit 300] Report pairs of facts with embedding similarity ≥ threshold. Report-only; no merge.
consolidate [--threshold 0.92] [--include-structured] [--dry-run] [--limit 300] [--model M] Merge near-duplicate facts: cluster by embedding similarity, LLM-merge each cluster.
reflect [--window <days>] [--dry-run] [--model M] [--force\|--full] Analyze recent facts, extract behavioral patterns. --force / --full accepted for CLI parity (no scan cooldown on reflection).
reflect-rules [--dry-run] [--model M] [--force\|--full] Synthesize patterns into actionable rules.
reflect-meta [--dry-run] [--model M] [--force\|--full] Synthesize higher-level meta-patterns.
install [--dry-run] Guided first-run setup. Applies recommended config, auto-detects a sensible embedding default, creates starter workspace files/directories, refreshes the workspace skill + TOOLS.md block, and prints what is done vs left. Alias: setup.
config-mode <preset> Set preset: local (offline), minimal (cheap cloud help), enhanced (balanced), complete (enhanced + verbose). Writes to openclaw.json. Restart gateway after. See CONFIGURATION-MODES.md. Aliases: mode, set-mode.
help config-set <key> Show current value and a short description (tweet-length) for a config key. Example: help config-set autoCapture.
config Show current configuration and feature toggles (mode, core and optional features on/off), plus a plain-English mode summary. Alias: settings.
config-set <key> [value] Set a plugin config key (use true / false for booleans). Omit value to show current value and description (same as help config-set <key>). Alias: set.
upgrade [version] Upgrade from npm. Removes current install, fetches version (or latest), rebuilds native deps. Restart gateway afterward. Optional version e.g. 2026.2.181.
verify [--fix] [--log-file <path>] [--test-llm] Beginner-friendly preflight check for config, SQLite, LanceDB, embeddings, credentials, and scheduled jobs. Prints guided fix suggestions plus the Mission Control URL. Alias: preflight.
status [--json] Unified health home: quick summary of memory size, cron health, audit failures, agent alerts, current task, and the Mission Control dashboard URL. Alias: home.
dashboard Print the Mission Control dashboard URL. Alias: mission-control.
doctor [--fix] [--dry-run] [--test-llm] Guided onboarding flow: install defaults step + verify step, with optional auto-remediation.
addons [--json] Show modular add-on ecosystem domains (analysis, learning, observability, self-extension).
distill [--all] [--days N] [--since YYYY-MM-DD] [--dry-run] [--model M] [--verbose] [--force\|--full] [--max-sessions N] [--max-session-tokens N] Index session JSONL into memory (LLM extraction, dedup, store). Uses local Ollama pre-filtering if extraction.preFilter.enabled is true. Default: last 3 days. Progress: when run in a TTY, shows a progress bar. --model M overrides the LLM; otherwise uses distill.defaultModel if set, else distill.modelTier (unset → maintenance) and the first model in that tier. All LLM calls go through the OpenClaw gateway. Long-context models use larger batches (500k tokens). See LLM-AND-PROVIDERS.md.
ingest-files [--dry-run] [--workspace path] [--paths globs] Index workspace markdown (skills, TOOLS.md, etc.) as facts via LLM extraction. Config ingest.paths or defaults: skills/**/*.md, TOOLS.md, AGENTS.md. See SEARCH-RRF-INGEST.md.
export --output <path> [--include-credentials] [--sources X,Y,Z] [--mode replace\|additive] Export memory to vanilla OpenClaw–compatible MEMORY.md + memory/ directory layout. Plain markdown, one file per fact. Default: exclude credentials, replace mode. Filter by fact source with --sources (e.g. conversation, distillation, cli, ingest, reflection).
distill-window [--json] Print the session distillation window (full or incremental).
record-distill Record that session distillation was run (timestamp for verify).
extract-procedures [--dir path] [--days N] [--dry-run] [--force\|--full] Extract tool-call procedures from session JSONL; store positive/negative procedures.
self-correction-extract [--days N] [--output path] Extract user correction incidents from session JSONL (last N days). Uses .language-keywords.json — run build-languages first for non-English.
self-correction-run [--extract-path path] [--workspace path] [--dry-run] [--approve] [--model M] [--no-apply-tools] [--force\|--full] Analyze incidents, auto-remediate (memory + TOOLS section or LLM rewrite). --force bypasses the 23h scan cooldown. Use --approve to apply suggested TOOLS rules; or set selfCorrection.autoRewriteTools: true for LLM rewrite. Report: memory/reports/self-correction-YYYY-MM-DD.md. See SELF-CORRECTION-PIPELINE.md.
analyze-feedback-phrases [--days N] [--model M] [--output path] [--learn] Analyze session logs to discover your praise/frustration phrases. Uses nano-tier for sentiment pre-filter and heavy-tier for phrase extraction (model-agnostic; omit --days for auto 30 days first run, then 3 days). Use --learn to merge into .user-feedback-phrases.json. Malformed JSONL in a session file sets error in the result and skips phrase extraction for that run (other session files are still scanned, but reinforcement/correction output stays empty until the bad file is fixed). See SELF-CORRECTION-PIPELINE.md.
generate-auto-skills [--dry-run\|--apply] [--max N] [--policy auto-safe\|draft-only\|manual] Generate bounded draft skills under skills/auto/ (SKILL.md, recipe.json, evals/, verification.json). Enforces OpenClaw 256 KB loader limit, Skill Creator frontmatter, and deterministic usefulness evals.
skills audit [--path <dir>] [--json] [--quarantine] Scan skills/auto for oversized/unloadable or suspicious generated skills; --quarantine moves matches to skills/auto-quarantine/YYYY-MM-DD/.
skills queue [--status <s>] [--limit N] [--json] List crystallization proposals. --status accepts lifecycle values plus aliases pending, approved, ready (validated + validation allow), and needs-override (validated + allow-with-override). Unknown values error instead of returning empty.
skills show <id> [--json] Show one proposal (card + draft SKILL.md).
skills validate <id> [--json] Run static SkillValidator on draft content.
skills reject <id> [--reason <text>] [--json] Reject a proposal (symmetric to install).
skills install <id> [--name …] [--category …] [--description …] [--override-warnings] [--json] Approve and write SKILL.md under the configured crystallization output directory.
skills rescan [--json] Re-read each installed crystallization proposal’s on-disk SKILL.md, run generated-skill validation, update stored results; set status quarantined when validation returns deny. See OPERATIONS.md § Crystallization: weekly skill rescan.
skills telemetry [skill-name] [--json] Report generated skill activation telemetry, false-positive/false-negative signals, lifecycle state, and promotion/demotion/archive recommendations.
skills record … / skills correct … Record activation telemetry or mark a false positive (see PROCEDURAL-MEMORY.md).
skills demote <skill-name> --reason "<reason>" Manually demote a generated skill (for example when it is over-triggering).
generate-proposals [--dry-run] [--verbose] Generate persona proposals from recent reflection (patterns, rules, meta). Proposal inputs follow autoRecall.scopeFilter; set it in shared-memory setups to avoid cross-user/agent contamination. Requires personaProposals enabled. Cron: weekly-persona-proposals.
run-all [--dry-run] [--verbose] [--force\|--full] Run all maintenance tasks in optimal order: backfill-decay (once), prune, compact, distill, extract-daily, extract-directives, extract-reinforcement, extract-procedures, generate-auto-skills, reflect, reflect-rules, reflect-meta, generate-proposals, self-correction-run, build-languages. --force / --full propagate to scan-style steps (distill, extract-*, self-correction-run). See MAINTENANCE-TASKS-MATRIX.md.
dream-cycle Nightly pipeline: prune expired facts, consolidate event log into facts, reflect, reflect-rules. Requires nightlyCycle.enabled. Cron: nightly-dream-cycle.
resolve-contradictions Resolve conflicting/superseded facts. Use --auto --dry-run / --auto --apply for the autonomous pipeline, --export-review / --apply-review for the manual queue, and --llm [--model ...] for opt-in adjudication. Cron: step 4 of nightly-memory-sweep.
credentials migrate-to-vault Move credential facts from memory into vault and redact originals.
credentials list [--service <pattern>] List vault entries (service, type, url; no values). Use --service to filter by substring (e.g. --service unifi).
credentials get --service <name> [--type <type>] [--value-only] [--show-value] Retrieve a credential value. Use --type when multiple types exist for the service. --value-only: print only the secret (for piping). --show-value: reveal the secret in the default (metadata) output.
credentials audit [--json] Flag suspicious entries (natural language, long service names, duplicates).
credentials prune [--yes] [--only-flags ...] Remove flagged entries (default: dry-run; use --yes to apply).
scope list List all scopes present in memory (from facts).
scope stats Show fact counts by scope (global, user, agent, session).
scope prune --scope <s> [--scope-target <id>] Remove all facts in a given scope (destructive). Use --scope-target when scope is user/agent/session.
scope promote [--dry-run] [--threshold-days N] [--min-importance 0.7] Promote high-importance session-scoped facts to global. Cron: weekly-deep-maintenance. See MEMORY-SCOPING.md.
goals config Print goal stewardship settings from plugin config (goalStewardship.*). For toggling: config-set goalStewardship enabled or disabled.
goals status No args: overview — stewardship on/off, goals directory, active goals (same columns as goals list). goals status <label-or-uuid>: full detail for one goal. --json: overview object or single goal JSON.
active-tasks List active tasks. With activeTask.enabled: false, only active-tasks config runs; enable with config-set activeTask enabled. With activeTask.ledger: markdown (default), reads ACTIVE-TASKS.md. With activeTask.ledger: facts, reads category:project facts (same store as memory_store).
active-tasks config Print active task settings from plugin config (activeTask.*).
active-tasks complete <label> Mark task Done and flush to memory log.
active-tasks stale Show tasks not updated within staleThreshold.
active-tasks reconcile Move in-progress tasks whose OpenClaw session transcript is missing to Completed (issues #978, #981).
active-tasks hygiene [--dry-run|--apply] [--older-than <duration>] Detect duplicate normalized task entities and stale rows (failed tasks, dead-session in-progress tasks). --dry-run reports findings; --apply marks rows as abandoned/superseded (history kept) and writes an audit fact.
active-tasks add <label> <desc> Add or update a task entry (markdown file or project facts).
active-tasks render Write ACTIVE-TASKS.md as a projection from the facts ledger (use with activeTask.ledger: facts).
task-queue-status Print state/task-queue/current.json as JSON (or a structured missing-file object for cron). Adds recognized: true/false when the file is valid JSON. Use --with-active-tasks to merge a summary of ACTIVE-TASKS.md (same paths as active-tasks).
task-queue-touch Create the task-queue state dir and an idle current.json placeholder if missing. Use --repair to archive a metadata-only or unrecognized current.json to history/ and write the canonical idle placeholder (issue #1037).
uninstall [--clean-all] [--force-cleanup] [--leave-config] Revert to default OpenClaw memory (memory-core).

Goals & active tasks — names

  • Plugin JSON uses camelCase: goalStewardship, activeTask (same as other keys under plugins.entries[…].config).
  • CLI uses kebab-case with a plural command: active-tasks (not active-task or ActiveTask).
  • Working-memory file default is ACTIVE-TASKS.md (activeTask.filePath). If you still have the legacy ACTIVE-TASK.md, rename it or set activeTask.filePath accordingly.

Export 

openclaw hybrid-mem export --output <path> [--include-credentials] [--sources <sources>] [--mode replace|additive]

Export all memory (facts + procedures) to a vanilla OpenClaw–compatible layout: MEMORY.md root index + memory/<category>/ markdown files. Plain markdown, one file per fact; compatible with memorySearch and memory-core. Use for inspection, backup, or copying to another bot.

Option Description
--output <path> Output directory (created if missing). Required.
--include-credentials Include credential pointer facts (default: exclude). Never exports actual secrets.
--sources <sources> Filter by fact source: comma-separated (e.g. conversation,cli,distillation,ingest,reflection). Omit for all.
--mode replace Replace the output directory (atomic). For safety, refuses when --output contains unexpected files; use an empty directory or a prior export directory.
--mode additive Add/overwrite; do not clear. Existing files overwritten on conflict.

Layout: MEMORY.md, manifest.json, memory/<category>/<tag>/<slug>-<id>.md (one file per fact). Re-import via openclaw hybrid-mem backfill --workspace <path> or copy into a vanilla workspace.

Ingest-files 

openclaw hybrid-mem ingest-files [--dry-run] [--workspace <path>] [--paths <glob1,glob2,...>]

Index workspace markdown as facts via LLM extraction. Default patterns: skills/**/*.md, TOOLS.md, AGENTS.md (or config ingest.paths).

Option Description
--dry-run Preview without storing
--workspace <path> Workspace root (default: OPENCLAW_WORKSPACE or cwd)
--paths <globs> Comma-separated globs (overrides config)

→ Full docs: SEARCH-RRF-INGEST.md

Build-languages (multilingual) 

openclaw hybrid-mem build-languages [--dry-run] [--model <model>]

Detect the top 3 languages in your stored facts, then generate intent-based trigger/category/decay keywords for those languages and write ~/.openclaw/memory/.language-keywords.json. Used for multi-language capture, category detection, and decay classification.

Option Description
--dry-run Detect languages and generate keywords but do not write the file
--model <model> LLM for detection and generation (default: same as autoClassify, e.g. gpt-4o-mini)

→ Full docs: LANGUAGE-KEYWORDS.md

Store options 

openclaw hybrid-mem store --text <text> [--category <cat>] [--entity <e>] [--key <k>] [--value <v>] [--source-date YYYY-MM-DD] [--tags "a,b,c"] [--scope global|user|agent|session] [--scope-target <id>] [--supersedes <fact-id>]
  • --source-date: When the fact originated (ISO-8601). Include when parsing old memories.
  • --tags: Comma-separated topic tags. Omit for auto-tagging.
  • --category: Override category (default: other).
  • --scope: Memory scope: global (default), user, agent, or session. See MEMORY-SCOPING.md.
  • --scope-target: Required when scope is user, agent, or session — the userId, agentId, or sessionId.
  • --supersedes: Fact id this one supersedes (replaces).
  • When store.classifyBeforeWrite is true in config, store runs ADD/UPDATE/DELETE/NOOP classification against similar facts before writing.

Sensor Sweep (Event Bus)

The sensor-sweep CLI executes cron-based background data collection without relying on the LLM. It queries configured sensors (Tier 1 and Tier 2) and writes structured events to the Event Bus (event-bus.db).

openclaw hybrid-mem sensor-sweep [--tier 1|2|all] [--source <names>] [--dry-run] [--json]

Options:

  • --tier <n>: Sensor tier to run (1 for Tier 1 only, 2 for Tier 2, all for both). Defaults to 1.
  • --source <names>: Comma-separated list of sensors (e.g. garmin,github,weather).
  • --dry-run: Preview what would be collected without writing events.

You can inspect the collected events using the sensor-events command:

openclaw hybrid-mem sensor-events [--type <type>] [--status <status>] [--limit 20] [--json]

Options:

  • --type <type>: Filter by event type (e.g., sensor.garmin).
  • --status <status>: Filter by event status (raw, processed, surfaced, pushed, archived). Defaults to raw.
  • --limit <n>: Max events to return.

Stats and efficiency

openclaw hybrid-mem stats shows fact counts, LanceDB vectors, and decay breakdown.

Add --efficiency for an extended view:

openclaw hybrid-mem stats --efficiency

This adds:

  • By tier (hot/warm/cold): Fact counts and estimated tokens per tier
  • By source: How facts were added (conversation, cli, distillation, reflection, auto-capture, etc.)
  • Estimated tokens in memory: Total token size of stored facts (same heuristic as auto-recall)
  • Token savings note: Explains that providers can cache injected memories; Cache Read is typically 90%+ cheaper than Input. Compare your provider dashboard (Input vs Cache Read) to see actual savings — many users see 90–97% reduction.

Verify and doctor

openclaw hybrid-mem verify checks config, DBs, and embedding API. Feature toggles are shown as true / false to match openclaw.json. It checks:

  • Config (embedding required; optional llm model preference)
  • SQLite and LanceDB accessibility
  • Embedding API reachability
  • Credentials vault (if enabled)
  • Session distillation last run
  • Optional/suggested jobs (all 9 maintenance jobs; see Maintenance cron jobs below)
  • Feature flags (autoCapture, autoRecall, autoClassify, credentials, fuzzyDedupe, classifyBeforeWrite)
  • Compaction model watchdog (reports provider/model/reason and warns when routing appears stronger than mini)

Issues are listed as load-blocking (prevent OpenClaw from loading) or other, with fixes for each.

--fix applies safe fixes: missing embedding block, memory directory, and optional jobs. Adds any missing maintenance cron jobs to ~/.openclaw/cron/jobs.json (see Maintenance cron jobs); does not re-enable jobs you disabled. It also normalizes isolated hybrid-mem:* jobs by removing an explicit top-level sessionKey so they use OpenClaw’s default per-job session key (cron:<jobId>). --log-file <path> scans the file for memory-hybrid or cron errors.

Embedding ↔ LanceDB alignment: Verify includes a check that the live embedding API output dimension matches the LanceDB table width (see #941). That implies one real embedding request during verify (API usage / quota), even when everything else is healthy. If the probe reports a different width than the configured provider dimension, follow the on-screen steps before relying on semantic search.

Compaction model safety: Verify warns when compaction appears to route to a stronger-than-mini model (for example gpt-5.5). minimax/MiniMax-M2.7 is explicitly allowed and does not trigger this warning.

Exit codes (for scripting): 0 = all checks passed, no restart needed; 1 = issues found (see output); 2 = all checks passed but restart pending (config was changed via config-mode/config-set; restart gateway for changes to take effect). A dimension mismatch between embeddings and LanceDB counts as failure (1) so scripts and monitors can detect silent semantic-search breakage. After fixing embedding.* / vector.*, run openclaw hybrid-mem re-index if vectors were built with the wrong model. See Troubleshooting — dimension mismatch.

--json and stdout (scripting): When you pass --json, machine-readable output goes to stdout only. Human-oriented diagnostics (warnings, fix hints, progress lines) go to stderr so pipelines stay valid:

openclaw hybrid-mem verify --json 2>/dev/null | jq .
openclaw hybrid-mem verify --json 2>verify-human.log | jq '.ok'

The same contract applies to other JSON commands (status --json, skills queue --json, config when emitting JSON, etc.): do not parse stdout as JSON if you did not pass --json, and avoid mixing log lines into stdout in custom wrappers.

openclaw hybrid-mem doctor adds a guided onboarding wrapper around install + verify:

  • step 1: checks/applies recommended defaults (install)
  • step 2: runs runtime/storage checks (verify)
  • step 3: prints remediation summary and next actions

Use --fix to apply install defaults and verify repairs, or --dry-run to preview changes.

JSON output contract (scripting)

Several commands support --json. Follow these rules when automating:

Rule Detail
stdout JSON only when --json is set (or the command is JSON-only, e.g. goals status --json).
stderr Human diagnostics, warnings, and fix text (especially verify --json).
Exit codes See per-command sections (e.g. verify: 0 / 1 / 2).

Commands that register plugin config during startup must not print non-JSON lines to stdout when you use JSON mode (for example corrections/config registration during config --json). If jq fails with “parse error”, check stderr for the real message and upgrade to 2026.5.190+ if you hit legacy stdout pollution.

Session observability (CLI)

Use openclaw hybrid-mem audit session to inspect a coherent session timeline:

openclaw hybrid-mem audit session --format summary
openclaw hybrid-mem audit session --format timeline --limit 30
openclaw hybrid-mem audit session --format json --session-id <id>

It surfaces capture vs injection visibility, suppressions, and “why recalled” context from local stores.

Benchmarks and quality reports

Generate recurring quality reports:

openclaw hybrid-mem benchmark report --format markdown
openclaw hybrid-mem benchmark report --format json --out /tmp/hybrid-mem-quality.json

Reports include latency, recall accuracy (when measured), feature failure rate, and tracked token/cost metrics.

Telemetry summary and encrypted sync

Local telemetry summary (no network calls):

openclaw hybrid-mem telemetry-summary
openclaw hybrid-mem telemetry-summary --hours 168 --json

Encrypted replication bundle workflow:

export HYBRID_MEM_SYNC_PASSPHRASE='your-strong-passphrase'
openclaw hybrid-mem sync-export --out /tmp/hm-sync.hm-sync
openclaw hybrid-mem sync-import --in /tmp/hm-sync.hm-sync --out /tmp/hm-sync.json

Uninstall

openclaw hybrid-mem uninstall reverts to the default OpenClaw memory manager (memory-core). Safe: your data is kept unless you pass --clean-all (removes SQLite and LanceDB; irreversible). Use --leave-config to skip modifying openclaw.json. Full guide: UNINSTALL.md.

Safety note: --clean-all only deletes storage under ~/.openclaw/memory/ by default. To allow deleting custom-configured paths, set OPENCLAW_HYBRID_MEM_UNINSTALL_DANGEROUS=1.

Tips

  • Run classify --dry-run first to preview, then run without --dry-run to apply.
  • Run find-duplicates to review candidates, then consolidate --dry-run before applying.
  • Run verify as a health check after installation or upgrades.
  • Use install --dry-run to preview config changes before applying.

List, show, and review

After running the maintenance pipeline (distill, extract-*, reflect, self-correction-run), the plugin produces patterns, rules, directives, procedures, persona proposals, and self-correction suggestions. These commands let you browse and act on them without querying SQLite directly.

List by type 

openclaw hybrid-mem list patterns [--limit 10]
openclaw hybrid-mem list rules [--limit 10]
openclaw hybrid-mem list directives [--limit 10]
openclaw hybrid-mem list procedures [--limit 10]
openclaw hybrid-mem list proposals [--status pending]
openclaw hybrid-mem list corrections [--workspace path]
  • patterns / rules / directives — From the facts table (category or source). Non-superseded only.
  • procedures — From the procedures table (task patterns, positive/negative).
  • proposals — Persona proposals (requires persona proposals enabled). Filter by --status pending|approved|rejected|applied.
  • corrections — Parses the latest memory/reports/self-correction-YYYY-MM-DD.md and shows the “Suggested TOOLS.md rules” and “Proposed (review before applying)” sections.

Show one item 

openclaw hybrid-mem show <fact-id-or-proposal-id>

Resolves the ID as a fact, procedure, or persona proposal and prints JSON details.

Proposals (persona)

  • proposals list — Same data as list proposals; optional --status.
  • proposals approve <id> — Mark as approved. Apply to the target file with openclaw proposals apply <id> (top-level OpenClaw command).
  • proposals reject <id> — Mark as rejected; optional --reason.

Corrections (self-correction)

  • corrections list — Show proposed TOOLS rules and other suggestions from the latest report.
  • corrections approve –all — Insert all suggested TOOLS rules from that report into TOOLS.md under the configured self-correction section (e.g. “Self-correction rules”). Uses workspace root (default OPENCLAW_WORKSPACE or ~/.openclaw/workspace).

Interactive review 

openclaw hybrid-mem review

Steps through pending persona proposals and the latest correction report. For each proposal: prompt for [a]pprove, [r]eject, or [s]kip. For corrections: [a]pprove all (apply TOOLS rules) or [s]kip.

Maintenance cron jobs

Install and verify –fix create or repair maintenance cron jobs in ~/.openclaw/cron/jobs.json. The canonical list is 9 jobs (see table). Install/verify also creates ~/.openclaw/logs/cron-hybrid-mem/ for first-run log paths.

Default job messages embed a bash harness: one foreground shell (set -euo pipefail, set -x), per-step hm_step that tees to HM_LOG and appends exit=<code> lines to HM_EXIT, plus log headers (HM_JOB, RUN_ID, openclaw --version). Logs default to ~/.openclaw/logs/cron-hybrid-mem/ (fallback: /tmp/openclaw-cron-hybrid-mem-$USER if that directory is not writable). The message instructs the agent not to update the guard file after a failed step and to paste HM_EXIT in the reply.

Job (pluginJobId) Schedule Purpose
hybrid-mem:nightly-distill 02:00 daily nightly-memory-sweep: prune → distill –days 1 → extract-daily (7d) → resolve-contradictions → enrich-entities (see config skips in message).
hybrid-mem:self-correction-analysis 02:30 daily self-correction-analysis: self-correction-run --verbose. Skip if selfCorrection disabled.
hybrid-mem:nightly-dream-cycle 02:45 daily nightly-dream-cycle: dream-cycle --verbose. Requires nightlyCycle.enabled.
hybrid-mem:weekly-reflection Sun 03:00 weekly-reflection: reflect / reflect-rules / reflect-meta (each --verbose). Requires reflection.enabled.
hybrid-mem:weekly-extract-procedures Sun 04:00 weekly-extract-procedures: extract-procedures → extract-directives → extract-reinforcement → generate-auto-skills (each --verbose where supported).
hybrid-mem:weekly-deep-maintenance Sat 04:00 weekly-deep-maintenance: compact → vectordb-optimize → scope promote.
hybrid-mem:weekly-persona-proposals Sun 10:00 weekly-persona-proposals: generate-proposals --verbose. Requires personaProposals enabled.
hybrid-mem:monthly-consolidation 1st 05:00 monthly-consolidation: consolidate → build-languages → backfill-decay → enrich-entities –limit ${HYBRID_MEM_CLI_JOB_ENRICH_LIMIT:-25} (default 25; set env var to override).
hybrid-mem:sensor-sweep every 4h (configurable) sensor-sweep: tier 1 + tier 2. Requires sensorSweep.enabled.
  • Install: Adds any missing jobs (does not change existing jobs or re-enable disabled ones).
  • Verify –fix: Adds any missing jobs and can normalize schedule/pluginJobId; does not re-enable disabled jobs by default.
  • Jobs are identified by pluginJobId so upgrades can add new jobs without duplicating.
  • For isolated maintenance jobs, do not set sessionKey to agent:main:main (or any interactive chat session key). Leave sessionKey unset so OpenClaw uses isolated per-job keys (cron:<jobId>), avoiding main-session contention.

Feature-gating: When a feature is disabled in config, the corresponding CLI command exits 0 without doing work. Leave all jobs defined; they no-op when e.g. procedures.enabled or reflection.enabled is false. See MAINTENANCE-TASKS-MATRIX.md for full context.

Back to top

OpenClaw Hybrid Memory — durable agent memory

This site uses Just the Docs, a documentation theme for Jekyll.