fix(openclaw): apply configured defaults to dynamic banks (#2441)

* fix(openclaw): apply configured defaults to dynamic banks

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(openclaw): route knowledge tools through identity resolution for user-scoped banks

Knowledge tool factories now use resolveAndCacheIdentity before deriving bank IDs,
matching auto-recall/retain so PluginToolContext sessions hit the correct per-user
bank. Unresolved user identity returns a clear tool error instead of querying
anonymous/openclaw fallbacks, and bank defaults are applied before execution.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(agent-sdk): stop mapping max_results to recall max_tokens

NemoClaw passed max_results=25 expecting a result-count cap, but the SDK
used it as max_tokens=25 and starved recall. max_tokens now defaults to
1024 from max_tokens only; max_results slices the results array (1-50).

Co-authored-by: Cursor <cursoragent@cursor.com>

* refactor(openclaw): drop dead alias exports + tighten entityLabels shape

- Remove unused @deprecated hasConfiguredMissions/applyConfiguredMissions
  aliases (new exports nothing imports).
- normalizeEntityLabels now only accepts the server's shapes (a list, or a
  { attributes: [...] } object); a plain keyed object is dropped client-side
  instead of being sent and silently ignored by parse_entity_labels.
- Update docs (types.ts, plugin.json, README) and tests to match.

* fix(agent-sdk): drop unsupported max_results from recall tool

The recall tool's max_results was previously aliased to the recall token
budget (a no-op for result count). Rather than make it a real cap, remove
it entirely — the tool accepts only max_tokens; use recallTopK for an
auto-recall count cap.

Also document the new per-user dynamic bank defaults (retainExtractionMode,
enableObservations, enableAutoConsolidation, dispositions, entityLabels) on
the docs-site OpenClaw page and fix its stale max_results guidance.

---------

Co-authored-by: DK09876 <Dikshant.pradhan@vectorize.io>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Nicolò Boschi <boschi1997@gmail.com>

Author: 4 people

hindsight-docs/docs-integrations/openclaw.md

@@ -123,7 +123,14 @@ Optional settings in `~/.openclaw/openclaw.json`:
 - `llmModel` - LLM model used with `llmProvider` (provider default if omitted)
 - `llmApiKey` - API key for the LLM provider. **Sensitive** — set via `openclaw config set ... --ref-source env --ref-id OPENAI_API_KEY` to reference an env var.
 - `llmBaseUrl` - Optional base URL override for OpenAI-compatible providers (e.g. `https://openrouter.ai/api/v1`)
-- `bankMission` - Agent identity/purpose stored on the memory bank. Helps the memory engine understand context for better fact extraction during retain. Set once per bank on first use — not a recall prompt.
+- `bankMission` - Agent identity/purpose stored on the memory bank's `reflect_mission`. **Only affects `reflect`** — does not steer retain or recall. Set once per bank on first use.
+- `retainMission` - Stamped onto the bank's `retain_mission` on first use. Steers what gets extracted as facts during retain.
+- `observationsMission` - Stamped onto the bank's `observations_mission` on first use. Controls what gets synthesised into observations during consolidation.
+- `retainExtractionMode` - Fact extraction mode stamped on first bank use: `concise`, `verbose`, `custom`, `verbatim`, or `chunks`. Leave unset to keep the server default.
+- `enableObservations` - Toggle observation consolidation after retain, stamped on first bank use.
+- `enableAutoConsolidation` - Toggle automatic consolidation scheduling, stamped on first bank use (via the bank config API).
+- `dispositionSkepticism` / `dispositionLiteralism` / `dispositionEmpathy` - Reflect disposition traits (`1`–`5`) stamped on first bank use.
+- `entityLabels` - Controlled vocabulary for entity labels. Either a list of attribute defs (e.g. `[{ "name": "person", "description": "Human user" }]`) or a `{ "attributes": [...] }` object; other shapes are ignored. Stamped on first bank use.
 - `dynamicBankId` - Enable per-context memory banks (default: `true`)
 - `bankId` - Static bank ID used when `dynamicBankId` is `false`.
 - `bankIdPrefix` - Optional prefix for bank IDs (e.g. `"prod"` → `"prod-slack-C123"` or `"prod-shared-bank"`)
@@ -146,7 +153,7 @@ Optional settings in `~/.openclaw/openclaw.json`:
 - `enableKnowledgeTools` - Register `agent_knowledge_*` tools for explicit agent-driven lookup, reflection, ingest, and knowledge-page management (default: `false`).
 - `debug` - Enable debug logging (default: `false`).
 
-When using `agent_knowledge_recall` manually, pass `max_tokens` to control how much memory text the recall response may contain. Do not use `max_results` for this tool; OpenClaw auto-recall uses `recallTopK` when you need a count cap for automatically injected memories.
+When using `agent_knowledge_recall` manually, pass `max_tokens` to control how much memory text the recall response may contain. The tool has no `max_results` parameter — to cap the number of automatically injected memories, use `recallTopK` on auto-recall instead.
 
 When using `agent_knowledge_reflect`, keep the default conservative settings unless you intentionally need a deeper synthesis: `budget` defaults to `low`, `max_tokens` defaults to `1024`, and `fact_types` defaults to `world`, `experience`, and `observation`. Reflect calls can be more expensive than recall because they retrieve memories and then call the configured Reflect LLM to generate an answer. For production banks, set a finite bank-level `reflect_source_facts_max_tokens` value (for example `4096` or `8192`) instead of leaving it unlimited, so ad-hoc reflection cannot pull an unbounded amount of source facts into the LLM context.
 
@@ -181,6 +188,41 @@ Available isolation fields:
 
 Use `bankIdPrefix` to namespace bank IDs across environments (e.g. `"prod"`, `"staging"`). Set `dynamicBankId` to `false` to use a single shared bank for all conversations. In static mode, the plugin uses `bankId` if set, otherwise the default `openclaw` bank name.
 
+### Per-user bank defaults
+
+With `dynamicBankId` enabled (the default), each derived bank otherwise inherits only the Hindsight **server** defaults (`concise` extraction, no entity labels, etc.). To make every per-user bank match your intended base/shared bank, set the bank-default options below — they are stamped onto each bank **on first use**, before its first retain or recall:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "hindsight-openclaw": {
+        "enabled": true,
+        "config": {
+          "dynamicBankId": true,
+          "dynamicBankGranularity": ["agent", "channel", "user"],
+          "retainExtractionMode": "verbose",
+          "enableObservations": true,
+          "enableAutoConsolidation": true,
+          "dispositionSkepticism": 3,
+          "dispositionLiteralism": 3,
+          "dispositionEmpathy": 4,
+          "entityLabels": [
+            { "name": "person", "description": "A human user or contact" },
+            { "name": "project", "description": "A software project or product" }
+          ],
+          "retainMission": "Extract durable preferences, decisions, and project context.",
+          "observationsMission": "Synthesise stable user preferences and active projects.",
+          "bankMission": "You are a helpful assistant with long-term memory across channels."
+        }
+      }
+    }
+  }
+}
+```
+
+Unset options are not sent, so existing behaviour is unchanged when you only configure missions. Each bank is configured at most once per gateway process.
+
 ### Retention Controls
 
 By default, the plugin retains `user` and `assistant` messages after each turn. You can customize this behavior:

hindsight-integrations/openclaw/README.md

@@ -86,6 +86,13 @@ Optional settings in `~/.openclaw/openclaw.json` under `plugins.entries.hindsigh
 | `bankMission`              | —                              | Mission stamped onto the bank's `reflect_mission` column on first use. **Only affects the `reflect` operation** — does not steer retain or recall. Leave unset (or empty) to manage missions out-of-band via `PATCH /banks/{id}`.                                                                           |
 | `retainMission`            | —                              | Mission stamped onto the bank's `retain_mission` column on first use. Steers what gets extracted as facts during retain. Leave unset to use built-in extraction rules.                                                                                                                                      |
 | `observationsMission`      | —                              | Mission stamped onto the bank's `observations_mission` column on first use. Controls what gets synthesised into observations during consolidation.                                                                                                                                                          |
+| `retainExtractionMode`     | —                              | Fact extraction mode stamped on each bank's first use: `concise`, `verbose`, `custom`, `verbatim`, or `chunks`. Use with dynamic banks so per-user banks match your analytics/base bank settings.                                                                                                           |
+| `enableObservations`       | —                              | When set, stamped on first bank use to toggle observation consolidation after retain.                                                                                                                                                                                                                       |
+| `enableAutoConsolidation`  | —                              | When set, stamped on first bank use (via bank config API) to toggle automatic consolidation scheduling.                                                                                                                                                                                                     |
+| `dispositionSkepticism`    | —                              | Reflect skepticism trait (`1`–`5`) stamped on first bank use.                                                                                                                                                                                                                                               |
+| `dispositionLiteralism`    | —                              | Reflect literalism trait (`1`–`5`) stamped on first bank use.                                                                                                                                                                                                                                               |
+| `dispositionEmpathy`       | —                              | Reflect empathy trait (`1`–`5`) stamped on first bank use.                                                                                                                                                                                                                                                  |
+| `entityLabels`             | —                              | Controlled vocabulary for entity labels. Either a list of attribute defs (see example below) or a `{ "attributes": [...] }` object — other shapes are ignored. Passed through to `PATCH /banks/{id}/config` as `entity_labels` on first bank use.                                                           |
 | `llmProvider`              | —                              | LLM provider for memory extraction (`openai`, `anthropic`, `gemini`, `groq`, `ollama`, `openai-codex`, `claude-code`). Required unless `hindsightApiUrl` is set.                                                                                                                                            |
 | `llmModel`                 | provider default               | LLM model used with `llmProvider`                                                                                                                                                                                                                                                                           |
 | `llmApiKey`                | —                              | API key for the LLM provider. **Sensitive** — set via `openclaw config set ... --ref-source env --ref-id OPENAI_API_KEY` to reference an env var (or `--ref-source file`/`exec` for mounted-secret/Vault sources).                                                                                          |
@@ -121,10 +128,38 @@ Optional settings in `~/.openclaw/openclaw.json` under `plugins.entries.hindsigh
 | `debugPerfTiming`          | `false`                        | Emit one info-level perf line per `before_prompt_build` (recall path) and `agent_end` (retain path) so you can spot whether latency is in the plugin or upstream. Off by default. Format: `perf: <hook> hook_total=Xms <hook-specific fields>`. Safe in production — uses the existing logger.              |
 | `enableKnowledgeTools`     | `false`                        | Register `agent_knowledge_*` tools for explicit agent-driven lookup, reflection, ingest, and knowledge-page management. Set automatically by the self-driving-agents CLI.                                                                                                                                   |
 
+### Per-user dynamic bank defaults
+
+When `dynamicBankId` is enabled (default), OpenClaw derives a separate Hindsight bank per context (e.g. per Slack user). New banks otherwise inherit only Hindsight server defaults (`concise` extraction, no entity labels, etc.). Set the options below in plugin config to stamp **full bank defaults on first use** — before the first retain or recall touches that bank:
+
+```json
+{
+  "dynamicBankId": true,
+  "dynamicBankGranularity": ["agent", "channel", "user"],
+  "retainExtractionMode": "verbose",
+  "enableObservations": true,
+  "enableAutoConsolidation": true,
+  "dispositionSkepticism": 3,
+  "dispositionLiteralism": 3,
+  "dispositionEmpathy": 4,
+  "entityLabels": [
+    { "name": "person", "description": "A human user or contact" },
+    { "name": "project", "description": "A software project or product" }
+  ],
+  "retainMission": "Extract durable preferences, decisions, and project context.",
+  "observationsMission": "Synthesise stable user preferences and active projects.",
+  "bankMission": "You are a helpful assistant with long-term memory across channels."
+}
+```
+
+Unset options are not sent — existing behaviour is unchanged when you only configure missions (as before). Each bank is configured at most once per gateway process.
+
 ### Manual Knowledge Tools
 
 When `enableKnowledgeTools` is enabled, the plugin registers explicit `agent_knowledge_*` tools in addition to automatic recall. Use `agent_knowledge_recall` for ordinary memory lookup. Use `agent_knowledge_reflect` only for deliberate synthesis, retrospectives, or long-term preference/pattern questions; it retrieves memories and then calls the configured Reflect LLM to generate an answer.
 
+Knowledge tools resolve the same dynamic memory bank as auto-recall and auto-retain: the plugin runs the shared identity-resolution path (`resolveAndCacheIdentity`) from the tool session context before deriving the bank ID. With user-scoped dynamic banking (`dynamicBankGranularity` includes `"user"`), tools target the per-user bank for that session; if sender identity cannot be resolved, tool execution returns a clear error instead of querying the shared `openclaw` default or an `anonymous` fallback bank. Configured bank defaults (missions, extraction mode, entity labels, etc.) are applied on first knowledge-tool use, matching `getClientForContext` behavior.
+
 `agent_knowledge_reflect` uses conservative defaults: `budget: "low"`, `max_tokens: 1024`, and `fact_types: ["world", "experience", "observation"]`. Production deployments should also set a finite bank-level `reflect_source_facts_max_tokens` value, such as `4096` or `8192`, rather than leaving reflection source facts unlimited.
 
 ### Session pattern filtering

hindsight-integrations/openclaw/openclaw.plugin.json

@@ -54,6 +54,40 @@
         "type": "string",
         "description": "Mission stamped onto the bank's observations_mission column on first use. Controls what gets synthesised into observations during consolidation."
       },
+      "retainExtractionMode": {
+        "type": "string",
+        "description": "Fact extraction mode stamped onto each bank on first use (dynamic or static). Options: concise, verbose, custom, verbatim, chunks. Leave unset to keep the Hindsight server default for new banks.",
+        "enum": ["concise", "verbose", "custom", "verbatim", "chunks"]
+      },
+      "enableObservations": {
+        "type": "boolean",
+        "description": "When set, stamped onto each bank on first use to toggle observation consolidation after retain."
+      },
+      "enableAutoConsolidation": {
+        "type": "boolean",
+        "description": "When set, stamped onto each bank on first use via PATCH /banks/{id}/config to toggle automatic consolidation scheduling."
+      },
+      "dispositionSkepticism": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 5,
+        "description": "Reflect skepticism trait (1=trusting, 5=skeptical) stamped on first bank use."
+      },
+      "dispositionLiteralism": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 5,
+        "description": "Reflect literalism trait (1=flexible, 5=literal) stamped on first bank use."
+      },
+      "dispositionEmpathy": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 5,
+        "description": "Reflect empathy trait (1=detached, 5=empathetic) stamped on first bank use."
+      },
+      "entityLabels": {
+        "description": "Controlled vocabulary for entity labels. Either a list of attribute defs (e.g. [{\"name\":\"person\",\"description\":\"Human user\"}]) or a { \"attributes\": [...] } object, passed through to PATCH /banks/{id}/config as entity_labels on first bank use. Other shapes are ignored."
+      },
       "embedVersion": {
         "type": "string",
         "description": "hindsight-embed version to use (e.g. 'latest', '0.4.2', or empty for latest)",
@@ -329,6 +363,34 @@
       "label": "Observations Mission",
       "placeholder": "Controls what gets synthesised into observations..."
     },
+    "retainExtractionMode": {
+      "label": "Retain Extraction Mode",
+      "placeholder": "verbose, concise, custom, verbatim, or chunks"
+    },
+    "enableObservations": {
+      "label": "Enable Observations",
+      "placeholder": "true or false — stamped on first bank use"
+    },
+    "enableAutoConsolidation": {
+      "label": "Enable Auto Consolidation",
+      "placeholder": "true or false — stamped on first bank use"
+    },
+    "dispositionSkepticism": {
+      "label": "Disposition Skepticism",
+      "placeholder": "1–5"
+    },
+    "dispositionLiteralism": {
+      "label": "Disposition Literalism",
+      "placeholder": "1–5"
+    },
+    "dispositionEmpathy": {
+      "label": "Disposition Empathy",
+      "placeholder": "1–5"
+    },
+    "entityLabels": {
+      "label": "Entity Labels",
+      "placeholder": "e.g. [{\"name\":\"person\",\"description\":\"Human user\"}]"
+    },
     "embedVersion": {
       "label": "Hindsight Embed Version",
       "placeholder": "latest (or pin to specific version like 0.4.2)"