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.5.0 the plugin warns at startup (MIN_OPENCLAW_VERSION); CLI subcommands, contracts.tools, and api.version may be missing. Gateways ≥2026.5.0 but <2026.6.1 log an info at startup (RECOMMENDED_OPENCLAW_VERSION) — core memory works; Skill Workshop integration and related features are feature-detected. Prefer OpenClaw 2026.6.1+; 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.

Tip: Quiet bootstrap output (#2095) Full bootstrap (DB init, vault open, doctor/config checks) logs a lot of info-level progress noise ahead of a command’s actual output — most visible on status/digest pending/maintenance status. Pass --quiet (or the short -q) anywhere after hybrid-mem, or set OPENCLAW_HYBRID_MEM_QUIET=1, to drop that info/debug noise; warnings and errors are never suppressed. --help and --version are already quiet by default — they skip full bootstrap entirely and don’t need this flag.

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)
Smoke testing smoke e2e [--json]
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
Error-reporter queue error-reports status [--json], error-reports peek [--limit N] [--json], error-reports flush [--timeout ms] [--json]
Contacts contacts list, contacts suggest-merges, contacts merge <fromId> <intoId>, contacts import --from <file>, contacts sync --from <file>
Graph & audit graph repair --collapse-event-hubs [--apply], graph health / audit health [--json] [--strict\|--strict-errors] [--output <path>], graph get <factId>, graph path <fromFactOrEntity> <toFactOrEntity>, audit log
Links link create <sourceFactId> <targetFactId> --type <type> [--strength N], link list <factId>, link delete <linkId>
Issues issues create <title> --symptoms <list>, issues update <id>, issues list, issues search <query>, issues show <id>, issues link-fact <issueId> <factId>
Provenance provenance <factId> [--json]
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.).
graph repair --collapse-event-hubs [--apply] [--threshold N] [--json] Repair historical graph pathologies: collapse legacy dream-cycle/session-heartbeat DERIVED_FROM mega-hubs into provenance_json and delete the eligible links. Dry-run by default; --apply performs the migration.
graph health [--json] [--strict\|--strict-errors] [--timeout-ms N] [--output <path>] Alias for audit health (below), grouped under graph alongside graph repair for discoverability.
graph get <factId> [--json] Show a fact plus its outgoing/incoming graph links (#2090).
graph path <fromFactOrEntity> <toFactOrEntity> [--max-depth N] [--json] Shortest path between two facts by id or entity name via bidirectional BFS over the memory graph; exits 1 when no path is found within --max-depth (default 5) (#2090).
link create <sourceFactId> <targetFactId> --type <type> [--strength N] [--json] Create a typed link between two facts (SUPERSEDES, CAUSED_BY, PART_OF, RELATED_TO, DEPENDS_ON, CONTRADICTS, INSTANCE_OF, PRECEDED_BY). CONTRADICTS records a bidirectional contradiction and reduces confidence instead of a plain link. CLI parity for memory_link (#2090).
link list <factId> [--json] List a fact’s outgoing and incoming links (#2090).
link delete <linkId> [--json] Delete a link by id; decrements graph degree counters where applicable. Exits 1 if the id doesn’t exist (#2090).
issues create <title> --symptoms <list> [--severity <sev>] [--tags <list>] [--json] Create a tracked issue (lifecycle: open → diagnosed → fix-attempted → resolved → verified, or wont-fix). CLI parity for memory_issue_create (#2090).
issues update <id> [--status <status>] [--root-cause <text>] [--fix <text>] [--rollback <text>] [--symptoms <list>] [--json] Update fields and/or advance status; --status validates the allowed transition (#2090).
issues list [--status <list>] [--severity <list>] [--tags <list>] [--limit N] [--json] List tracked issues with optional filters (#2090).
issues search <query> [--json] Search issues by title/symptoms (LIKE-based text matching) (#2090).
issues show <id> [--json] Show one issue (#2090).
issues link-fact <issueId> <factId> Associate a memory fact with an issue for cross-referencing (#2090).
provenance <factId> [--json] Show a fact’s provenance chain: source session/turn plus DERIVED_FROM/CONSOLIDATED_FROM/REFLECTED_FROM edges. Requires provenance.enabled: true. CLI parity for memory_provenance (#2090).
audit health [--json] [--strict\|--strict-errors] [--timeout-ms N] [--output <path>] One-shot non-destructive hybrid-memory health report: plugin/DB schema version, storage, categories, decay, graph schema validity (memory_links table/columns/indexes, #2226), graph hub-degree guard stats, entity-enrichment backlog, credentials status, warnings/remediation. --strict exits 2 on any warning/error/partial status; --strict-errors exits 2 only on errors/degraded status (including a missing memory_links table). --output writes the JSON artifact atomically instead of stdout.
audit log [--hours N] [--agent <id>] [--outcome <o>] [--target <t>] [--format lines\|summary\|timeline] Cross-agent audit trail (issue #790): query logged memory operations.
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.
categories discovered [list\|approve <label>\|reject <label>] [--json] Review labels proposed by category discovery (see AUTOMATIC-CATEGORIES.md) before they’re promoted into config. list (default) shows pending + previously-rejected labels; approve/reject remove a label from the pending queue — approve prints the manual promotion steps (discovery is advisory-only, it never auto-applies), reject also records the label so future discovery runs never re-propose it (#2100).
list [--limit N] [--category c] [--entity e] [--key k] [--source s] [--tier hot\|warm\|cold\|structural] List recent facts (default limit 10), filterable by category/entity/key/source/tier. Not a per-type browser — patterns/rules are just categories (list --category pattern), procedures need procedure list, and persona proposals / self-correction items have their own proposals list / corrections list commands. See List, show, and review below.
show <id> Show full detail for a fact by ID (JSON). For a persona proposal id it prints a pointer to proposals show <id> rather than the proposal itself; procedures are not covered — use procedure show <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.
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. Alias: 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.
maintenance run list\|status\|artifacts\|explain\|resume Inspect orchestrator / JobRun artifacts (#1877). See maintenance-job-runs.md.
maintenance nightly\|cycle\|full [--json] [--summary-out <path>] Orchestrator tiers; --json / --summary-out emit machine-readable run summary.
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 [--dry-run] [--json] Nightly pipeline: prune expired facts, consolidate event log into facts, reflect, reflect-rules. Requires nightlyCycle.enabled. Cron: nightly-dream-cycle. --dry-run (#2089) previews what would be pruned/decayed/consolidated/reflected without mutating facts, links, episodes, proposals, or files — every follow-up stage after the core cycle (verification, tool effectiveness, crystallization, cost-log prune, …) is skipped entirely since none of them have a preview mode. --json is only supported together with --dry-run and emits the full result object on stdout.
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).
credentials revisions list --service <name> --type <type> [--json] List historical revisions kept when a credential is overwritten (issue #2104) — metadata only, no values.
credentials revisions get --service <name> --type <type> --revision <id> [--show-value\|--value-only] [--json] Retrieve a specific revision’s value intentionally. Masked by default.
credentials revisions restore --service <name> --type <type> --revision <id> [--yes] Restore/promote a revision back to current (default: dry-run; use --yes to apply). The value it replaces is itself kept as a new revision.
credentials revisions purge --service <name> --type <type> [--revision <id>\|--all] [--yes] Hard-delete revision(s) — cannot be undone (default: dry-run; use --yes to apply).
credentials revisions pin --service <name> --type <type> --revision <id> [--unpin] Pin a revision so it never expires, or --unpin to re-expose it to normal TTL expiry.
contacts list [--prefix <name>] [--limit <n>] [--json] List contacts (id, name, role, org, email). Issue #2014.
contacts suggest-merges [--json] List unambiguous partial-name duplicate candidates (e.g. “Daniel” vs. “Daniel Thunberg”).
contacts merge <fromId> <intoId> Merge fromId into intoId (each arg accepts a contact id or a name): repoints NER mentions and entity_contact_id FKs, folds in profile fields (manual wins conflicts), deletes fromId.
contacts import [--from <path>] [--dry-run] [--embed] [--no-part-of] Upsert organizations/contacts/roster facts from a CONTACTS.md-style roster file (plus a per-org summary roster fact and PART_OF links from each person’s roster fact to it). Idempotent. --from defaults to contacts.importPath; --embed is a no-op (roster facts embed via the normal store path); --no-part-of skips the PART_OF links. See CONFIGURATION.md for the file format.
contacts sync [--from <path>] [--force] Re-run contacts import only if the file’s mtime changed since the last sync. --from defaults to contacts.importPath.
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] [--dry-run] [-v|--verbose]

Options:

  • --tier <n>: Sensor tier to run (1, 2, or all). Defaults to all.
  • --dry-run: Preview without writing events.
  • -v, --verbose: Log progress before each sensor.

There is currently no dedicated CLI command to browse individual Event Bus rows (no sensor-events) — the bus is an internal decoupling mechanism between sensor producers and maintenance/Dream consumers (backends/event-bus.ts, status lifecycle raw → processed → surfaced → pushed → archived). Use openclaw hybrid-mem audit health / stats for aggregate storage state, or query event-bus.db directly for row-level inspection.

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.

Smoke testing

openclaw hybrid-mem smoke e2e [--json] runs a first-class end-to-end pipeline check (issue #2088): store → embed → recall → link → episode → forget → verify, using two disposable, uniquely-tagged test facts. Unlike verify/doctor (which check config/connectivity), smoke e2e proves new memories actually flow through every intended feature:

  1. Store two facts (decayClass: "ephemeral", tagged with a unique run id) and confirm the SQLite rows.
  2. Store canonical vectors and confirm the fact_embeddings cache row (model + dimensions).
  3. Confirm the LanceDB vector row exists with the expected dimension.
  4. Keyword recall (FTS5) finds the fact.
  5. Semantic recall finds the fact for a paraphrased query.
  6. Create an explicit RELATED_TO graph link; confirm it’s readable both directions and that out_degree/in_degree incremented.
  7. Record and search an episode.
  8. Forget/delete everything created (facts, embeddings cache rows, LanceDB vectors, the link, the episode) — always attempted, regardless of which earlier step failed.
  9. Verify no leftover rows in SQLite, LanceDB, links, the embedding cache, or episodes.
  10. Verify the storage-sync drift state (see verify below) didn’t regress.

Safe to run against a production local memory store — every artifact is uniquely tagged and cleanup is mandatory, not opt-in. --json emits the full structured result (runId, overall, per-step {name, status, detail, durationMs}, and leftover artifact ids). Without --json, a failed run whose cleanup could not fully complete prints exact commands (link delete <id>, forget <id> --yes) to remove leftovers manually. Exits 1 when any step fails.

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 runs a standalone set of health diagnostics (🟢 pass, 🟡 warn, 🔴 fail) covering SQLite/LanceDB connectivity, the embedding provider, config validity, SQLite ↔ LanceDB sync, the alias Lance index (if aliases are enabled), disk space, WAL health, FTS index/trigger consistency, retrieval/recall stats, maintenance job staleness, the error-reporter queue, and quarantined goal files (if goal stewardship is enabled). Exit code is 1 if any check fails.

--fix repairs what it safely can, then re-checks and reports the real post-repair state (not just “a repair ran”):

  • FTS population drift — rebuilds facts_fts from facts.
  • FTS structural drift (missing facts_fts table/columns/triggers) — recreates it live via the same idempotent migration (runFactsMigrations) that already runs on every FactsDB open, then chains straight into a population rebuild so one --fix pass fully self-heals. If a gateway is currently running, restart it afterward so its own connection picks up the corrected schema.
  • Storage structural drift (duplicate/fragmented Lance rows, no orphans) — runs the same repair verify --fix uses (optimize + dedupe + rebuild), matching issue #2103.
  • Alias Lance index mismatch — rebuilds the alias Lance table from SQLite (re-embeds if the dimension changed).
  • Quarantined goal files — restores any .json.corrupt goal file that still parses as valid Goal JSON.

Add --reconcile to also check for SQLite ↔ LanceDB orphan drift (mismatched ID sets; issue #904). --reconcile alone is report-only; combine with --fix (doctor --fix --reconcile) to actually delete vector-side orphans and rebuild missing SQLite-side vectors — the one destructive repair in scope, so doctor takes a checkpoint backup first and aborts the repair (leaving the drift untouched) if the backup fails. --reconcile-policy <conservative|balanced|aggressive> (default balanced) and --reconcile-max-fixes <n> bound how much rebuild work runs, mirroring verify --reconcile --fix.

--deep additionally runs a savepointed FTS trigger round-trip probe (insert/update/delete).

Checks that need human judgement or aren’t safely repairable from inside the running process stay suggestion-only: SQLite/LanceDB connection failures, missing/misconfigured embedding provider, low disk space, WAL disabled/unavailable/circuit-breaker-tripped/journal-corrupt (data-loss risk — needs root-cause investigation first), and stale maintenance jobs.

--json: prints the full check list and summary as a single JSON object to stdout instead of the human-readable banner/icon lines — { overall: "healthy"|"degraded"|"unhealthy", checks: [{ name, status, message, fix? }], summary: { passed, warnings, failed }, durationMs, timestamp }. overall is "unhealthy" (and the process exits 1) if any check failed, "degraded" if only warnings are present, else "healthy". Composes with --fix/--reconcile/--deep — the repairs still run, only the output format changes. Useful for scripting/monitoring the nightly hybrid-mem:nightly-doctor-repair cron job (see Maintenance cron jobs) without having to parse the human-readable text: check checks for the "Database Sync"/"FTS Index/Triggers"/"Alias Lance Index"/"Goal registry quarantine" entries specifically before treating an unrelated failing check (e.g. embedding provider down) as a reconcile failure.

openclaw hybrid-mem doctor --fix --reconcile runs nightly by default via the hybrid-mem:nightly-doctor-repair cron job (see Maintenance cron jobs below) — existing installs pick it up the next time install or verify --fix runs.

Scheduled-run health (issue #2231): openclaw hybrid-mem maintenance status and maintenance cron-health monitor hybrid-mem:nightly-doctor-repair alongside hybrid-mem:maintenance-nightly — a missing/stale/failed doctor-repair run is now reported (and fails cron-health’s exit code) the same way the nightly maintenance job already was. maintenance status/--json also reports lastSuccessfulRunAt per job: a locally persisted (SQLite maintenance_runs) record of the most recent run each cron lane’s maintenance validate-exit step actually validated as successful, independent of whether GlitchTip error-reporting telemetry is enabled — distinct from lastRunAt/lastStatus, which only reflect OpenClaw’s own cron-store snapshot of the most recent firing (which may itself have failed, and carries no history).

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.

Quiet mode (--quiet/-q or OPENCLAW_HYBRID_MEM_QUIET=1, issue #2095): By default, hybrid-mem commands print plugin bootstrap telemetry (startup checkpoints, registered ... confirmations, credential-vault-OK lines) before the command’s real output, which can bury the result in a smoke suite or cron harness. Pass --quiet (or -q) anywhere after hybrid-mem, or set the env var to 1, to drop that info/debug boilerplate:

openclaw hybrid-mem maintenance status --quiet
OPENCLAW_HYBRID_MEM_QUIET=1 openclaw hybrid-mem digest pending --json

Warnings and errors are never suppressed by quiet mode — only routine progress logging is trimmed. --help invocations are already quiet (they short-circuit before the plugin/storage stack bootstraps) and are unaffected by this flag. Quiet mode composes with --json: bootstrap warn/error lines still route to stderr as usual, just without the info/debug noise ahead of them. Note: the [plugins] loading ... lines the OpenClaw host itself prints before the plugin registers are outside this plugin’s control.

Digest backlog hygiene

digest pending reports age-bucket hygiene per queue (persona proposals, tool proposals, crystallization proposals), but on a large backlog reviewing items one at a time doesn’t scale. digest batch-reject (issue #2098) finds duplicate/stale/low-confidence items and rejects them in bulk through each queue’s existing reject primitive — dry-run by default:

# Preview: duplicates (same target/name, newest kept) across persona proposals
openclaw hybrid-mem digest batch-reject --queue persona --duplicates-only

# Preview: items 30+ days old in the tool-proposal queue
openclaw hybrid-mem digest batch-reject --queue tools --older-than 30d

# Preview: low-confidence crystallization proposals, then apply
openclaw hybrid-mem digest batch-reject --queue crystallization --max-confidence 0.3
openclaw hybrid-mem digest batch-reject --queue crystallization --max-confidence 0.3 --yes
--queue is required (persona tools crystallization); pass at least one of --older-than <duration>, --max-confidence <n>, or --duplicates-only. Filters combine — an item matching any of them becomes a candidate. --yes applies; without it the command only previews and never mutates. --json emits the structured preview/result instead of the human-readable list.

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.

Workboard integration

When workboard.enabled is true, hybrid-memory syncs active tasks and goals to OpenClaw’s Workboard Kanban UI. The sync runs on a configurable interval (default: every 5 minutes).

No dedicated CLI commands are needed — the sync is automatic. Workboard cards are managed through the Workboard UI in OpenClaw’s Control Panel.

How it works:

  • Active tasks and goals are created as Workboard cards with the configured cardTag (default: "hybrid-memory")
  • Status changes map to column names (e.g. in_progress → “In Progress”)
  • When bidirectional is true, moving a card between columns in the Workboard UI updates the task/goal status in hybrid-memory
  • Cards include a description derived from the task/goal details and a link back to the hybrid-memory entity

Diagnostics:

  • Check openclaw hybrid-mem verify — reports Workboard connectivity and sync status when the feature is enabled
  • Gateway logs contain memory-hybrid: workboard sync entries for each sync cycle

Wiki integration and Dreaming UI

When wikiIntegration.enabled is true, hybrid-memory facts are bridged to OpenClaw’s memory-wiki plugin and visible in the Dreaming UI tab.

What gets exposed:

  • Facts appear in the Dreaming UI under “Imported Insights” and “Memory Palace” (via publicArtifacts)
  • Facts are included in memory_search corpus=all and wiki_search corpus=all results (via corpusSupplement)
  • Dream findings (patterns, consolidation summaries, digests) from the nightly dream cycle are stored as facts and also bridged

Bidirectional editing (when mutations.enabled is true):

Gateway RPC methods under hybrid-mem.facts.*:

# These are called programmatically by memory-wiki or other Gateway clients.
# List facts
curl -X POST http://localhost:9119/gateway/rpc \
  -d '{"method": "hybrid-mem.facts.list", "params": {"query": "TypeScript"}}'

# Get a specific fact
curl -X POST http://localhost:9119/gateway/rpc \
  -d '{"method": "hybrid-mem.facts.get", "params": {"id": "<fact-id>"}}'

# Update a fact
curl -X POST http://localhost:9119/gateway/rpc \
  -d '{"method": "hybrid-mem.facts.update", "params": {"id": "<fact-id>", "text": "Updated text"}}'

# Supersede (replace or delete) a fact
curl -X POST http://localhost:9119/gateway/rpc \
  -d '{"method": "hybrid-mem.facts.supersede", "params": {"id": "<fact-id>"}}'

# Create a new fact
curl -X POST http://localhost:9119/gateway/rpc \
  -d '{"method": "hybrid-mem.facts.create", "params": {"text": "New fact", "category": "technical"}}'

HTTP equivalent: POST /plugins/memory-public/fact/mutate with { "action": "update"|"supersede"|"create", ... }.

Wiki CLI:

openclaw hybrid-mem wiki status          # config + mirror status
openclaw hybrid-mem wiki status --json
openclaw hybrid-mem wiki export          # run workspace mirror sync now
openclaw hybrid-mem wiki export --json

openclaw hybrid-mem verify includes a UI integrations (Workboard / Dreaming) section when wikiIntegration or workboard is enabled.

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

list has no <type> argument — it lists recent facts filtered by --category/--entity/--key/--source/--tier. Patterns, rules, and directives are not separate item kinds; procedures, proposals, and corrections each have their own dedicated command:

openclaw hybrid-mem list --category pattern [--limit 10]
openclaw hybrid-mem list --category rule [--limit 10]
openclaw hybrid-mem procedure list [--limit 10]
openclaw hybrid-mem proposals list [--status pending]
openclaw hybrid-mem corrections list [--workspace path]
  • patterns / rules — Facts stored with category: "pattern" / "rule" (written by reflect / reflect-rules). Non-superseded only. “Directives” extracted by extract-directives are similarly filed under an existing category (preference, rule, pattern, decision, or fact) rather than their own type — there’s no single clean filter for them.
  • procedures — procedure list reads the procedures table (task patterns, positive/negative) — a different table from list.
  • proposals — proposals list (persona proposals; requires persona proposals enabled). Filter by --status pending|approved|rejected|applied.
  • corrections — corrections list 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 or persona proposal and prints JSON details (a proposal id just prints a pointer to proposals show <id>). Procedures aren’t resolved here — use procedure show <id>.

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.

Research (proactive loop)

The research group is the contract between the overnight research cron agent and the memory store (see PROACTIVE-RESEARCH.md):

Command Description
research pick --json Agent-facing: fetch tonight’s queued topic + evidence chain ({"status":"none"} on quiet nights); flips the topic in-progress.
research store --topic-id <id> (--file <p>\|--stdin) --sources <urls> [--title <t>] The single writer for briefing facts: validates topic state, caps length/sources, records provenance incl. URLs, marks the topic done.
research status [--json] [--days <n>] Operator audit view: queue, briefings, unread flags, evidence counts.

Maintenance cron jobs

Install and verify –fix create or repair maintenance cron jobs in ~/.openclaw/cron/jobs.json. By default (maintenance.orchestrator.consolidatedCronJobs unset or true), this installs a single consolidated job, hybrid-mem:maintenance-nightly (daily 02:00, runs openclaw hybrid-mem maintenance nightly --verbose — the orchestrator resolves due nightly/weekly/monthly steps itself), plus a handful of jobs that stay standalone even under consolidation (nightly-doctor-repair, maintenance-log-analyzer, weekly-pending-digest, weekly-pending-digest-autopilot, research-overnight, and feature-gated ones like sensor-sweep). Set maintenance.orchestrator.consolidatedCronJobs: false to install the legacy per-task layout instead — the table below documents that legacy layout (it predates consolidation and is no longer what a fresh install creates by default). See MAINTENANCE-TASKS-MATRIX.md for the authoritative current breakdown. 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.
hybrid-mem:research-overnight 03:30 daily (research.schedule) research-overnight: isolated heavy-model agent — research pick → web research → research store. Gated by research.enabled (default on); announce delivery only with explicit research.delivery.channel + to.
hybrid-mem:nightly-doctor-repair 03:15 daily nightly-doctor-repair: doctor --fix --reconcile — self-heals storage structural drift, orphan vectors (with an automatic backup before deletion), alias Lance mismatches, and quarantined goal files (issue #2103). Runs after the night’s memory-sweep/dream-cycle writes settle, before the 03:30 jobs.
  • 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.