V3 enhancement

README.md

@@ -33,16 +33,18 @@ It answers you on the channels you already use (WhatsApp, Telegram, Slack, Disco
 - **QVeris-first tool experience**: integrate with 500+ providers and 10,000+ APIs via a single tool-search + tool-execute workflow.
 - **China-friendly channel strategy**: stronger Feishu and regional ecosystem readiness without sacrificing global channel coverage.
 - **Faster first-run onboarding**: CLI/macOS/web wizard now includes QVeris API setup and X channel credentials in guided flow.
+- **Enhanced long-term memory**: two new bundled hooks — `context-digest` (rolling cross-session summary injected into system prompt) and `session-importance` (auto-archives important conversations to `memory/important/`) — extend memory beyond the single session.
 
 ### OpenClaw vs QVerisBot (quick comparison)
 
-| Area                 | OpenClaw (base platform)                          | QVerisBot (this repo)                                                                                             |
-| :------------------- | :------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------- |
-| Positioning          | Local-first agent gateway + multi-channel runtime | OpenClaw-based distribution focused on professional tool use and faster production onboarding                     |
-| Tool ecosystem       | Built-in tools + extension mechanism              | QVeris Universal Toolbox integration (search + execute), plus QVeris-first defaults                               |
-| Web search default   | Commonly configured with Brave/other providers    | During onboarding, defaults `web_search` to QVeris Smart Search when QVeris is enabled                            |
-| Channel focus        | Broad global channels and plugin model            | Adds stronger China-facing defaults/integration (especially Feishu), while keeping full OpenClaw channel coverage |
-| First-run onboarding | Wizard-driven baseline setup                      | Enhanced wizard flow: QVeris API key setup + X channel credential setup integrated into onboarding                |
+| Area                 | OpenClaw (base platform)                          | QVerisBot (this repo)                                                                                                         |
+| :------------------- | :------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------- |
+| Positioning          | Local-first agent gateway + multi-channel runtime | OpenClaw-based distribution focused on professional tool use and faster production onboarding                                 |
+| Tool ecosystem       | Built-in tools + extension mechanism              | QVeris Universal Toolbox integration (search + execute), plus QVeris-first defaults                                           |
+| Web search default   | Commonly configured with Brave/other providers    | During onboarding, defaults `web_search` to QVeris Smart Search when QVeris is enabled                                        |
+| Channel focus        | Broad global channels and plugin model            | Adds stronger China-facing defaults/integration (especially Feishu), while keeping full OpenClaw channel coverage             |
+| First-run onboarding | Wizard-driven baseline setup                      | Enhanced wizard flow: QVeris API key setup + X channel credential setup integrated into onboarding                            |
+| Long-term memory     | Session-scoped memory + manual memory files       | Adds `context-digest` (cross-session summary → system prompt) and `session-importance` (auto-archive important conversations) |
 
 ## Quick Start (5 minutes)
 
@@ -155,10 +157,11 @@ New install? Start here: [Getting started](https://docs.openclaw.ai/start/gettin
 
 Model note: while many providers/models are supported, for the best experience and lower prompt-injection risk use the strongest latest-generation model available to you. See [Onboarding](https://docs.openclaw.ai/start/onboarding).
 
-## Models (selection + auth)
+## Models (selection + switching)
 
 - Models config + CLI: [Models](https://docs.openclaw.ai/concepts/models)
 - Auth profile rotation (OAuth vs API keys) + fallbacks: [Model failover](https://docs.openclaw.ai/concepts/model-failover)
+- **Natural language model switching**: ask the agent to switch models in conversation (e.g. "use kimi", "switch to sonnet") — the `switch_model` tool handles alias resolution, fuzzy matching, and confirmation when ambiguous. The `/model <name>` command also works.
 
 ## Install (recommended)
 
@@ -168,6 +171,27 @@ Runtime: **Node ≥22**.
 
 </details>
 
+### How the agent uses QVeris tools
+
+QVerisBot exposes three QVeris tools to the agent, with built-in routing guidance to prevent misuse:
+
+| Tool                | When to use                                                                                                                                                                                                                                                     |
+| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `qveris_search`     | Discover tools by **capability type** — real-time data APIs (prices, weather, financials), external service capabilities (image generation, OCR, TTS, translation), geo/location APIs. **Not for** local file reads, software config, or documentation lookups. |
+| `qveris_execute`    | Execute a tool returned by `qveris_search` or verified by `qveris_get_by_ids`. Pass parameters as JSON using `sample_parameters` from the search result as a template.                                                                                          |
+| `qveris_get_by_ids` | Re-verify a **known** tool ID without a full search — use when the agent has already found a good tool in this session. Skips the search round-trip and returns the current parameter schema.                                                                   |
+
+The agent follows a routing decision tree before calling `qveris_search`:
+
+1. **Local operation?** (read files, check config, session status) → use local tools, skip QVeris
+2. **Need a web page or article?** → use `web_search` / `web_fetch` directly
+3. **Need structured real-time data?** → `qveris_search("weather forecast API")` — describe the capability, not the task
+4. **Need an external service capability?** → `qveris_search("text to image generation API")`
+5. **Already used a QVeris tool this session?** → `qveris_get_by_ids` with the known ID, then execute directly
+6. **None of the above?** → do not call QVeris; use `web_search` or report the limitation
+
+A session-scoped **Tool Rolodex** tracks successfully executed tools. After a tool is used, it is annotated as `previously_used` in future search results and listed under `session_known_tools`, so the agent reuses verified tools instead of re-discovering them from scratch.
+
 ### What can you build with QVeris?
 
 | Scenario                    | Tools Used                                    | Workflow                                                                  |
@@ -189,7 +213,7 @@ Runtime: **Node ≥22**.
 
 ## What Else Makes QVerisBot Special
 
-- **OpenClaw + QVeris optimization layer** — keeps OpenClaw's core reliability while adding QVeris-first defaults for practical business/research workflows
+- **OpenClaw + QVeris optimization layer** — keeps OpenClaw's core reliability while adding QVeris-first defaults and a structured tool-routing layer (decision tree + session rolodex) for practical business/research workflows
 - **[Feishu Native Support](docs/qverisbot-from-source.md)** — WebSocket-based deep integration, ideal for Chinese enterprise users
 - **Improved onboarding across CLI/macOS/web wizard flows** — guided QVeris API key setup, auto-default `web_search` to QVeris Xiaosu Smart Search, and built-in X (Twitter) channel credential onboarding
 - **Multi-channel inbox** — WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, **Feishu**, Microsoft Teams, Matrix, Zalo, WebChat
@@ -402,6 +426,7 @@ QVerisBot is built on OpenClaw. For deep architecture, channel internals, platfo
 - **Bot migration (cross-OS):** see [Migrating Your Bot](#migrating-your-bot) above — `qverisbot migrate export|import|doctor`
 - **QVeris AI integrations:** https://qveris.ai/integrations
 - **QVeris dashboard / API keys:** https://qveris.ai/dashboard
+- **QVeris tool routing:** see [How the agent uses QVeris tools](#how-the-agent-uses-qveris-tools) above — `qveris_search`, `qveris_execute`, `qveris_get_by_ids`
 
 ## About QVerisBot
 
@@ -494,6 +519,7 @@ WhatsApp / Telegram / Slack / Discord / Google Chat / Signal / iMessage / BlueBu
 - **[Nodes](https://docs.openclaw.ai/nodes)** — Canvas, camera snap/clip, screen record, `location.get`, notifications, plus macOS‑only `system.run`/`system.notify`.
 
 - `/status` — compact session status (model + tokens, cost when available)
+- `/model <name>` — switch model (alias, partial, or full provider/model; or ask in natural language)
 - `/new` or `/reset` — reset the session
 - `/compact` — compact session context (summary)
 - `/think <level>` — off|minimal|low|medium|high|xhigh
@@ -521,6 +547,7 @@ ClawHub is a minimal skill registry. With ClawHub enabled, the agent can search
 Send these in WhatsApp/Telegram/Slack/Google Chat/Microsoft Teams/WebChat (group commands are owner-only):
 
 - `/status` — compact session status (model + tokens, cost when available)
+- `/model <name>` — switch model (alias, partial, or full provider/model; or ask in natural language)
 - `/new` or `/reset` — reset the session
 - `/compact` — compact session context (summary)
 - `/think <level>` — off|minimal|low|medium|high|xhigh (GPT-5.2 + Codex models only)

docs/automation/hooks.md

@@ -41,9 +41,11 @@ The hooks system allows you to:
 
 ### Bundled Hooks
 
-OpenClaw ships with four bundled hooks that are automatically discovered:
+OpenClaw ships with six bundled hooks that are automatically discovered:
 
 - **💾 session-memory**: Saves session context to your agent workspace (default `~/.openclaw/workspace/memory/`) when you issue `/new`
+- **📋 context-digest**: Maintains a rolling cross-session summary at `memory/context-digest.md` and injects open items into the system prompt
+- **🏷️ session-importance**: Classifies conversations by importance and archives significant ones under `memory/important/`
 - **📎 bootstrap-extra-files**: Injects additional workspace bootstrap files from configured glob/path patterns during `agent:bootstrap`
 - **📝 command-logger**: Logs all command events to `~/.openclaw/logs/commands.log`
 - **🚀 boot-md**: Runs `BOOT.md` when the gateway starts (requires internal hooks enabled)
@@ -371,12 +373,15 @@ Compaction lifecycle hooks exposed through the plugin hook runner:
 - **`before_compaction`**: Runs before compaction with count/token metadata
 - **`after_compaction`**: Runs after compaction with compaction summary metadata
 
+### Session Lifecycle Events
+
+- **`session:end`**: Fires when a session ends due to idle timeout or daily reset. Used by `context-digest` and `session-importance` hooks as a safety net to process the session even if `/new` was not explicitly issued.
+
 ### Future Events
 
 Planned event types:
 
 - **`session:start`**: When a new session begins
-- **`session:end`**: When a session ends
 - **`agent:error`**: When an agent encounters an error
 
 ## Creating Custom Hooks
@@ -712,6 +717,112 @@ Internal hooks must be enabled for this to run.
 openclaw hooks enable boot-md
 ```
 
+### context-digest
+
+Maintains a rolling cross-session digest at `memory/context-digest.md`. The "Open Items / Action Items" section is automatically injected into the agent's system prompt so the model has subconscious awareness of pending tasks without consuming significant token budget.
+
+**Events**: `command:new`, `command:reset`, `session:end`
+
+**Requirements**: `workspace.dir` must be configured
+
+**What it does**:
+
+1. Scans `sessions.json` for sessions updated within the configured window (default: 7 days)
+2. Reads transcripts (capped per session to control token use)
+3. Calls the LLM to generate a structured digest with four sections: Topics, Key Decisions, Open Items, and Important Context (falls back to a no-LLM summary if LLM is unavailable)
+4. Writes `memory/context-digest.md` (capped at 8 KB)
+5. On the next session start, the "Open Items" section is prepended to the system prompt as a read-only context hint
+
+**Output path**: `<workspace>/memory/context-digest.md`
+
+**Config**:
+
+| Option               | Type    | Default | Description                             |
+| -------------------- | ------- | ------- | --------------------------------------- |
+| `days`               | number  | 7       | Number of days to include in the digest |
+| `maxSessionMessages` | number  | 20      | Messages to read per session            |
+| `llmDigest`          | boolean | true    | Set to `false` for no-LLM fallback mode |
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "context-digest": {
+          "enabled": true,
+          "days": 14,
+          "llmDigest": true
+        }
+      }
+    }
+  }
+}
+```
+
+**Enable**:
+
+```bash
+openclaw hooks enable context-digest
+```
+
+### session-importance
+
+Automatically identifies important conversations and archives them to `memory/important/` for permanent reference. Uses a two-stage pipeline: a fast multi-dimensional pre-filter (zero LLM cost for routine conversations) followed by LLM-based structured classification for sessions that pass the filter.
+
+**Events**: `command:new`, `command:reset`, `session:end`
+
+**Requirements**: `workspace.dir` must be configured
+
+**What it does**:
+
+1. Reads the previous session transcript
+2. **Stage 1 — Heuristic evaluation**: Scores the session across multiple signals — explicit intent keywords (`remember`, `记住`), code-block density, message depth, structured assistant replies, conversation turns, and domain keywords. Routine sessions are skipped at zero LLM cost.
+3. **Stage 2 — LLM classification**: For sessions that pass Stage 1, calls the LLM to extract category, slug, summary, key points, and action items. Falls back to keyword-only classification if LLM is unavailable.
+4. **Slug-based deduplication**: If a file with the same slug already exists, new content is appended with a timestamp divider instead of creating a duplicate.
+
+**Output path**: `<workspace>/memory/important/YYYY-MM-DD-<category>-<slug>.md`
+
+**Categories**:
+
+| Category    | When it applies                                     |
+| ----------- | --------------------------------------------------- |
+| `reference` | User explicitly asked to remember or save something |
+| `research`  | Experiments, datasets, methodology, literature      |
+| `project`   | Milestones, progress, deployments, releases         |
+| `decision`  | Architecture choices, trade-offs, comparisons       |
+| `routine`   | Everything else — silently skipped                  |
+
+**Config**:
+
+| Option           | Type     | Default | Description                                |
+| ---------------- | -------- | ------- | ------------------------------------------ |
+| `messages`       | number   | 30      | Messages to analyze per session            |
+| `llmClassify`    | boolean  | true    | Set to `false` for heuristic-only mode     |
+| `customKeywords` | string[] | `[]`    | Extra keywords that boost importance score |
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "session-importance": {
+          "enabled": true,
+          "messages": 40,
+          "llmClassify": true,
+          "customKeywords": ["sprint", "OKR", "customer"]
+        }
+      }
+    }
+  }
+}
+```
+
+**Enable**:
+
+```bash
+openclaw hooks enable session-importance
+```
+
 ## Best Practices
 
 ### Keep Handlers Fast
@@ -783,6 +894,8 @@ The gateway logs hook loading at startup:
 
 ```
 Registered hook: session-memory -> command:new
+Registered hook: context-digest -> command:new, command:reset, session:end
+Registered hook: session-importance -> command:new, command:reset, session:end
 Registered hook: bootstrap-extra-files -> agent:bootstrap
 Registered hook: command-logger -> command
 Registered hook: boot-md -> gateway:startup

docs/concepts/memory.md

@@ -89,6 +89,49 @@ Details:
 For the full compaction lifecycle, see
 [Session management + compaction](/reference/session-management-compaction).
 
+## Proactive memory hooks
+
+Two optional bundled hooks extend memory management beyond the session boundary:
+
+### context-digest
+
+Triggers on `/new`, `/reset`, and session end. Scans recent session transcripts (default: last 7 days), generates a structured digest via LLM, and writes it to `memory/context-digest.md`. The **Open Items / Action Items** section is automatically injected into the system prompt on each session start, giving the model subconscious awareness of pending tasks without consuming significant token budget.
+
+```
+memory/
+└── context-digest.md   ← rolling cross-session summary (auto-generated, 8 KB cap)
+```
+
+Enable:
+
+```bash
+openclaw hooks enable context-digest
+```
+
+### session-importance
+
+Triggers on `/new`, `/reset`, and session end. Evaluates each completed session using a two-stage pipeline:
+
+1. **Heuristic pre-filter** — scores signals like explicit-intent keywords (`remember`, `记住`), code-block density, message depth, structured replies, and domain keywords. Routine sessions are dropped at zero LLM cost.
+2. **LLM classification** — for sessions that pass Stage 1, extracts category, summary, key points, and action items. Falls back to heuristic-only mode if LLM is unavailable.
+
+Important conversations are written to `memory/important/` with slug-based deduplication (repeated discussions on the same topic are appended rather than duplicated).
+
+```
+memory/
+└── important/
+    └── 2026-03-04-project-api-v3-migration.md
+    └── 2026-03-05-decision-model-selection.md
+```
+
+Enable:
+
+```bash
+openclaw hooks enable session-importance
+```
+
+For full configuration options, see [Hooks — context-digest](/automation/hooks#context-digest) and [Hooks — session-importance](/automation/hooks#session-importance).
+
 ## Vector memory search
 
 OpenClaw can build a small vector index over `MEMORY.md` and `memory/*.md` so

docs/concepts/models.md

@@ -89,7 +89,9 @@ Example allowlist config:
 }
 ```
 
-## Switching models in chat (`/model`)
+## Switching models in chat
+
+### Slash command (`/model`)
 
 You can switch models for the current session without restarting:
 
@@ -113,6 +115,26 @@ Notes:
 
 Full command behavior/config: [Slash commands](/tools/slash-commands).
 
+### Natural language switching (`switch_model` tool)
+
+You can also ask the agent to switch models in natural language:
+
+- "use kimi" / "switch to sonnet" / "change model to gpt-4o"
+- "reset to default model"
+
+The agent calls the `switch_model` tool, which:
+
+1. Resolves aliases, partial names, and full `provider/model` refs using the same fuzzy matching as `/model`.
+2. When the query is ambiguous (multiple close matches), returns a candidate list so the agent can ask you to confirm before switching.
+3. Applies the override to the current session; takes effect from the next message.
+4. Supports `model="default"` (or `"reset"`) to revert to the configured default.
+
+The `session_status` tool remains read-only for checking current model/session info.
+
+### Silent model reset notifications
+
+If a model override becomes invalid (e.g. removed from the allowlist), the session silently resets to the default model. When this happens, a system event is emitted so the agent can inform you of the change.
+
 ## CLI commands
 
 ```bash