docs(memory): document active-memory circuit breaker config and lancedb memory query CLI

vincentkoc · vincentkoc · commit c357235fe6e6 · 2026-04-29T04:41:06.000-07:00
- 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 89cd2b6, 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 6b44dce 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).
diff --git 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
@@ -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 <columns>`: comma-separated column allowlist (defaults to `id`, `text`, `importance`, `category`, `createdAt`).
+- `--filter <condition>`: SQL-style WHERE clause; capped at 200 characters and restricted to alphanumerics, comparison operators, quotes, parentheses, and a small set of safe punctuation.
+- `--limit <n>`: positive integer; default `10`.
+- `--order-by <column>:<asc|desc>`: 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
