From c357235fe6e6f4e29e86f623582b304678ff70de Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Wed, 29 Apr 2026 04:40:43 -0700 Subject: [PATCH] docs(memory): document active-memory circuit breaker config and lancedb memory query CLI - docs/concepts/active-memory.md: extend the "Useful tuning fields" config table with the new `config.circuitBreakerMaxTimeouts` and `config.circuitBreakerCooldownMs` keys (with their schema-declared ranges and defaults) added by 89cd2b6362, so operators tuning Active Memory recall after consecutive timeouts can find the knobs alongside `cacheTtlMs`. - docs/plugins/memory-lancedb.md: extend the "Commands" section with the new `openclaw memory query` subcommand 6b44dce0c8 registered when memory-lancedb is the active memory plugin, including the `--cols`, `--filter`, `--limit`, and `--order-by` options and the safety bounds (200-character filter cap, sanitized character allowlist, positive integer limit, in-memory order-by). --- docs/concepts/active-memory.md | 18 ++++++++++-------- docs/plugins/memory-lancedb.md | 13 +++++++++++++ 2 files changed, 23 insertions(+), 8 deletions(-) diff --git a/docs/concepts/active-memory.md b/docs/concepts/active-memory.md index 8a00d046aa0..1f5cc7a3676 100644 --- a/docs/concepts/active-memory.md +++ b/docs/concepts/active-memory.md @@ -579,14 +579,16 @@ The most important fields are: Useful tuning fields: -| Key | Type | Meaning | -| ----------------------------- | -------- | ---------------------------------------------------------------------------------- | -| `config.maxSummaryChars` | `number` | Maximum total characters allowed in the active-memory summary | -| `config.recentUserTurns` | `number` | Prior user turns to include when `queryMode` is `recent` | -| `config.recentAssistantTurns` | `number` | Prior assistant turns to include when `queryMode` is `recent` | -| `config.recentUserChars` | `number` | Max chars per recent user turn | -| `config.recentAssistantChars` | `number` | Max chars per recent assistant turn | -| `config.cacheTtlMs` | `number` | Cache reuse for repeated identical queries (range: 1000-120000 ms; default: 15000) | +| Key | Type | Meaning | +| ---------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `config.maxSummaryChars` | `number` | Maximum total characters allowed in the active-memory summary | +| `config.recentUserTurns` | `number` | Prior user turns to include when `queryMode` is `recent` | +| `config.recentAssistantTurns` | `number` | Prior assistant turns to include when `queryMode` is `recent` | +| `config.recentUserChars` | `number` | Max chars per recent user turn | +| `config.recentAssistantChars` | `number` | Max chars per recent assistant turn | +| `config.cacheTtlMs` | `number` | Cache reuse for repeated identical queries (range: 1000-120000 ms; default: 15000) | +| `config.circuitBreakerMaxTimeouts` | `number` | Skip recall after this many consecutive timeouts for the same agent/model. Resets on a successful recall or after the cooldown expires (range: 1-20; default: 3). | +| `config.circuitBreakerCooldownMs` | `number` | How long to skip recall after the circuit breaker trips, in ms (range: 5000-600000; default: 60000). | ## Recommended setup diff --git a/docs/plugins/memory-lancedb.md b/docs/plugins/memory-lancedb.md index 9bce67a12d1..cf184a4681d 100644 --- a/docs/plugins/memory-lancedb.md +++ b/docs/plugins/memory-lancedb.md @@ -221,6 +221,19 @@ openclaw ltm search "project preferences" openclaw ltm stats ``` +The plugin also extends `openclaw memory` with a non-vector `query` subcommand +that runs against the LanceDB table directly: + +```bash +openclaw memory query --cols id,text,createdAt --limit 20 +openclaw memory query --filter "category = 'preference'" --order-by createdAt:desc +``` + +- `--cols `: comma-separated column allowlist (defaults to `id`, `text`, `importance`, `category`, `createdAt`). +- `--filter `: SQL-style WHERE clause; capped at 200 characters and restricted to alphanumerics, comparison operators, quotes, parentheses, and a small set of safe punctuation. +- `--limit `: positive integer; default `10`. +- `--order-by :`: in-memory sort applied after the filter; the sort column is auto-included in the projection. + Agents also get LanceDB memory tools from the active memory plugin: - `memory_recall` for LanceDB-backed recall