openclaw-mem-engine admin ops (P0-1)¶

This page documents the operator-facing admin surfaces added for openclaw-mem-engine.

Core memory runtime capability¶

openclaw-mem-engine registers with OpenClaw's core memory runtime capability when the host exposes registerMemoryCapability or the legacy registerMemoryRuntime hook. This lets core doctor/status and memory-search health checks see the engine as the active memory plugin instead of treating it as only a sidecar tool/hook plugin.

The runtime adapter is intentionally thin:

search routes through the existing LanceDB-backed hybrid recall path and returns bounded synthetic memory citations.
readFile supports synthetic openclaw-mem-engine/<id>.md previews with direct ID lookup and line slicing for core UI/debug consumers.
status, probeEmbeddingAvailability, and probeVectorAvailability expose the same backend facts operators already see in plugin logs.

Older OpenClaw hosts remain compatible. If the host lacks the core capability hook, the plugin logs core memory runtime registration skipped and continues to provide its existing tools, docs cold lane, auto-capture, and prompt-hook behavior.

Verification after enabling or upgrading:

openclaw doctor
openclaw status

Expected capable-host log line:

openclaw-mem-engine: registered core memory runtime capability

What is supported¶

Comparable admin capabilities are now available for the engine backend:

list memories (filterable by scope / category, bounded by limit)
stats (counts by scope / category + size/age summaries)
export (sanitized, deterministic JSONL/JSON)
import (append mode, with dedupe and dry-run validation)

All admin operations return a receipt/debug block with:

operation
filtersApplied
returnedCount (or importedCount / skippedCount / failedCount for import)
backend context (dbPath, tableName, latency)

CLI commands¶

OpenClaw core may not ship built-in openclaw memory list|stats|export|import yet. This plugin registers equivalent admin commands under both surfaces when loaded:

openclaw memory <subcommand> (extends existing memory command)

openclaw ltm <subcommand> (fallback compatibility namespace)

List¶

openclaw memory list --scope openclaw-mem --limit 20 --json
# fallback:
openclaw ltm list --scope openclaw-mem --limit 20 --json

Stats¶

openclaw memory stats --scope openclaw-mem --json
# fallback:
openclaw ltm stats --scope openclaw-mem --json

Export (sanitized by default)¶

openclaw memory export \
  --scope openclaw-mem \
  --out /path/to/tmp/mem_export_test.jsonl \
  --format jsonl \
  --json

# fallback:
openclaw ltm export --scope openclaw-mem --out /tmp/mem.json --format json --json

Deterministic ordering: createdAt ASC, then id ASC
Default redaction: obvious API/token/private-key patterns in text are masked
Use --no-redact only in trusted/local scenarios

Import (append + dedupe + dry-run)¶

openclaw memory import \
  --in /path/to/tmp/mem_export_test.jsonl \
  --dedupe id_text \
  --dry-run \
  --json

# fallback:
openclaw ltm import --in /tmp/mem.jsonl --dedupe id_text --dry-run --json

Dedupe modes:

none – no dedupe
id – skip rows with existing IDs
id_text (default) – skip existing IDs and normalized duplicate text

Import behavior:

append-only; no destructive overwrite
if vector is missing, engine attempts embedding generation
if embeddings are unavailable and no vector provided, row is counted as failed

Tool API surface¶

The same admin operations are also exposed as tools:

memory_list
memory_stats
memory_export
memory_import

This keeps admin functionality available in agent/tool workflows even if CLI wiring differs across OpenClaw versions.

Docs Memory cold lane (installable)¶

openclaw-mem-engine now includes an optional docs cold lane for operator-authored markdown (DECISIONS/roadmaps/specs) without writing those chunks into hot memory rows.

New tools¶

memory_docs_ingest — bounded ingest into openclaw-mem docs SQLite index
memory_docs_search — bounded docs snippets (operator provenance)

memory_recall and autoRecall can consult docs cold lane only when hot recall is insufficient (minHotItems threshold).

Config knobs¶

{
  "plugins": {
    "entries": {
      "openclaw-mem-engine": {
        "enabled": true,
        "config": {
            "docsColdLane": {
              "enabled": true,
              "sqlitePath": "~/.openclaw/memory/openclaw-mem.sqlite",
              "sourceRoots": [
              "/path/to/decision-docs",
              "/path/to/project-docs"
              ],
            "sourceGlobs": ["**/*.md", "**/ROADMAP*.md", "**/*SPEC*.md"],
            "scopeMappingStrategy": "repo_prefix", // none|repo_prefix|path_prefix|map
            "scopeMap": {
              "openclaw-mem": ["openclaw-mem/docs", "openclaw-mem/specs"]
            },
            "maxChunkChars": 1400,
            "embedOnIngest": true,
            "ingestOnStart": false,
            "maxItems": 2,
            "maxSnippetChars": 280,
            "minHotItems": 2,
            "searchFtsK": 20,
            "searchVecK": 20,
            "searchRrfK": 60
          }
        }
      }
    }
  }
}

Verification commands¶

# 1) Ingest allowlisted docs
openclaw tools invoke memory_docs_ingest --json '{}'

# 2) Query docs lane directly
openclaw tools invoke memory_docs_search --json '{"query":"status code decision","scope":"openclaw-mem"}'

# 3) Verify cold-lane marker in recall receipt/logs
# expect: openclaw-mem-engine:docsColdLane.search
# and autoRecall receipt field: coldLane.{consulted,returned,strategy}

Log markers / receipts¶

ingest: openclaw-mem-engine:docsColdLane.ingest
search: openclaw-mem-engine:docsColdLane.search
includes bounded search counters such as requested, returned, filteredByScope, rawCandidates, and scopedCandidates
recall receipt (openclaw-mem-engine.recall.receipt.v1) now carries optional coldLane summary

Scoped docs search note: - when a strict scope is present, the plugin now over-fetches a bounded candidate pool before applying scope filtering, reducing false 0-hit cases caused by filter-after-limit starvation.

Rollback¶

Fast rollback (no code revert):

openclaw config set plugins.entries.openclaw-mem-engine.config.docsColdLane.enabled false
openclaw gateway restart

Hard rollback (remove lane tools as well): revert to previous commit and restart gateway.