memory-lancedb-pro 1.1.0-beta.1 → 1.1.0-beta.3

package/CHANGELOG.md

@@ -1,17 +1,44 @@
 # Changelog
 
-## 1.1.0-beta.1 (Smart Memory Beta)
+## 1.1.0
 
-This is a **beta** release published under the npm dist-tag **`beta`** (it will not affect the stable `latest` channel).
+- Feat: add integrated self-improvement governance flow (`agent:bootstrap`, `command:new/reset`, governance tools, and `.learnings` file bootstrap).
+- Feat: add `memoryReflection` session strategy with inheritance/derived injection, reflection persistence, and dedicated reflection-agent support.
+- Fix: keep session-strategy compatibility by mapping legacy `sessionMemory.enabled` to `systemSessionMemory` / `none` and trimming reflection input toward recent conversation tail.
+- Fix: retry early transient upstream reflection failures once and broaden session recovery search paths to real OpenClaw agent session directories.
+- Docs: update README / README_CN for session strategy, self-improvement, memoryReflection, mdMirror, and reflection fallback behavior.
+- Tests: add targeted coverage for reflection retry classification and session recovery path resolution.
 
-Highlights:
-- **Smart Extraction (LLM-powered)**: 6-category extraction with L0/L1/L2 metadata (falls back to regex capture when disabled or init fails)
-- **Lifecycle scoring integrated into retrieval**: decay-based score adjustment + tier floors
-- **Tier transitions (best-effort)**: records access stats for top results and can promote/demote tiers via metadata
-- Rebases the smart-memory branch onto `main@1.0.25` (keeps multi-key rotation & other recent fixes)
+PRs: #43, #2
 
-Notes:
-- Retrieval now performs small, bounded metadata write-backs for top results (access_count / last_accessed_at / tier).
+---
+
+## 1.0.32
+
+- Fix: strip OpenClaw `Conversation info` / `Sender` metadata noise before auto-capture matching and adaptive retrieval normalization, reducing false captures and noisy retrieval triggers.
+- Fix: parse `autoRecallMinRepeated` from plugin config so repeated-memory suppression works when configured.
+
+PR: #50
+
+---
+
+
+## 1.0.31
+
+- Fix: `memory-pro import` now preserves provided IDs and is idempotent (skips if ID already exists).
+
+## 1.0.26
+
+**Access Reinforcement for Time Decay**
+
+- **Feat**: Access reinforcement — frequently *manually recalled* memories decay more slowly (spaced-repetition style)
+- **New**: `AccessTracker` with debounced metadata write-back (records accessCount / lastAccessedAt)
+- **New**: Config options under `retrieval`: `reinforcementFactor` (default: 0.5) and `maxHalfLifeMultiplier` (default: 3)
+- **New**: `MemoryStore.getById()` pure-read helper for efficient metadata lookup
+
+PR: #37
+
+Breaking changes: None. Backward compatible (set `reinforcementFactor: 0` to disable).
 
 ---
 

package/README.md

@@ -80,7 +80,7 @@ The built-in `memory-lancedb` plugin in OpenClaw provides basic vector search. *
 
 | File | Purpose |
 |------|---------|
-| `index.ts` | Plugin entry point. Registers with OpenClaw Plugin API, parses config, mounts `before_agent_start` (auto-recall), `agent_end` (auto-capture), and `command:new` (session memory) hooks |
+| `index.ts` | Plugin entry point. Registers with OpenClaw Plugin API, parses config, mounts `before_agent_start` (auto-recall), `agent_end` (auto-capture), integrated `self-improvement` (`agent:bootstrap`, `command:new/reset`) and integrated `memory-reflection` (`command:new/reset`) hooks |
 | `openclaw.plugin.json` | Plugin metadata + full JSON Schema config declaration (with `uiHints`) |
 | `package.json` | NPM package info. Depends on `@lancedb/lancedb`, `openai`, `@sinclair/typebox` |
 | `cli.ts` | CLI commands: `memory list/search/stats/delete/delete-bulk/export/import/reembed/migrate` |
@@ -88,7 +88,7 @@ The built-in `memory-lancedb` plugin in OpenClaw provides basic vector search. *
 | `src/embedder.ts` | Embedding abstraction. Compatible with any OpenAI-API provider (OpenAI, Gemini, Jina, Ollama, etc.). Supports task-aware embedding (`taskQuery`/`taskPassage`) |
 | `src/retriever.ts` | Hybrid retrieval engine. Vector + BM25 → RRF fusion → Jina Cross-Encoder Rerank → Recency Boost → Importance Weight → Length Norm → Time Decay → Hard Min Score → Noise Filter → MMR Diversity |
 | `src/scopes.ts` | Multi-scope access control. Supports `global`, `agent:<id>`, `custom:<name>`, `project:<id>`, `user:<id>` |
-| `src/tools.ts` | Agent tool definitions: `memory_recall`, `memory_store`, `memory_forget` (core) + `memory_stats`, `memory_list` (management) |
+| `src/tools.ts` | Agent tool definitions: `memory_recall`, `memory_store`, `memory_forget` (core), `self_improvement_log` (default), and governance tools `self_improvement_review` / `self_improvement_extract_skill` (management mode) |
 | `src/noise-filter.ts` | Noise filter. Filters out agent refusals, meta-questions, greetings, and low-quality content |
 | `src/adaptive-retrieval.ts` | Adaptive retrieval. Determines whether a query needs memory retrieval (skips greetings, slash commands, simple confirmations, emoji) |
 | `src/migrate.ts` | Migration tool. Migrates data from the built-in `memory-lancedb` plugin to Pro |
@@ -146,13 +146,108 @@ Filters out low-quality content at both auto-capture and tool-store stages:
 - Meta-questions ("do you remember")
 - Greetings ("hi", "hello", "HEARTBEAT")
 
-### 7. Session Memory
-
-- Triggered on `/new` command — saves previous session summary to LanceDB
-- Disabled by default (OpenClaw already has native `.jsonl` session persistence)
-- Configurable message count (default: 15)
-
-### 8. Auto-Capture & Auto-Recall
+### 7. Session Strategy
+
+- `sessionStrategy: "systemSessionMemory"` (default): disable plugin reflection hooks; use OpenClaw built-in `session-memory`
+- `sessionStrategy: "memoryReflection"`: use plugin reflection hooks (explicit opt-in)
+- `sessionStrategy: "none"`: disable plugin session strategy hooks
+- Compatibility: legacy `sessionMemory.enabled=true|false` maps to `systemSessionMemory|none`
+- Upgrade behavior note:
+  - Previous plugin-driven session-summary behavior is no longer the implicit default.
+  - After upgrading, deployments that want plugin reflection on `/new` / `/reset` must explicitly set `sessionStrategy: "memoryReflection"`.
+  - Keeping legacy `sessionMemory.enabled: true` now preserves safer compatibility through `systemSessionMemory`, instead of silently enabling the newer reflection pipeline.
+
+### 8. Self-Improvement
+
+- Hooks: `agent:bootstrap`, `command:new`, `command:reset`
+- `agent:bootstrap`: injects `SELF_IMPROVEMENT_REMINDER.md` into bootstrap context
+- `command:new` / `command:reset`: appends a short `/note self-improvement ...` reminder before reset
+- Files: ensures `.learnings/LEARNINGS.md`, `.learnings/ERRORS.md`, `.learnings/FEATURE_REQUESTS.md`
+- Behavior note:
+  - This flow is integrated into the plugin lifecycle and can coexist with `sessionStrategy=systemSessionMemory`.
+  - It is separate from `memoryReflection`: seeing self-improvement notes or `.learnings/*` activity does not by itself mean reflection storage is enabled.
+  - Governance-oriented extraction/review actions remain explicitly tool-driven rather than background-triggered.
+- Tools:
+  - `self_improvement_log`: write structured LRN/ERR/FEAT entries
+  - `self_improvement_review`: summarize governance backlog (pending/high/promoted)
+  - `self_improvement_extract_skill`: extract a reusable `SKILL.md` scaffold from a learning entry
+    - Trigger: explicit tool call by user/model (not background auto-trigger)
+    - Timing: on-demand, one-shot execution
+    - Inputs: explicit `learningId` and `skillName`
+    - Risk profile: low and controllable; fewer accidental writes
+    - Recommended mode: stabilize workflow first with human review/approval
+
+### 9. memoryReflection
+
+- Trigger conditions:
+  - `sessionStrategy` must be `memoryReflection` (explicitly configured).
+  - Trigger event is `command:new` / `command:reset`.
+  - Reflection generation is skipped when session context is incomplete (for example missing `cfg`, session file, or readable conversation content).
+- Reflection runner chain:
+  - First try embedded runner (`runEmbeddedPiAgent`).
+  - If embedded path fails, automatically fallback to `openclaw agent --local --json`.
+  - Only if both fail, write minimal fallback reflection text.
+- Reflect output:
+  - Structured output should include these sections: `## Context`, `## Decisions (durable)`, `## User model deltas (about the human)`, `## Agent model deltas (about the assistant/system)`, `## Lessons & pitfalls (symptom / cause / fix / prevention)`, `## Learning governance candidates (.learnings / promotion / skill extraction)`, `## Open loops / next actions`, `## Retrieval tags / keywords`, `## Invariants`, `## Derived`.
+  - `## Invariants` is for stable rule-like carryover; `## Derived` is for concrete next-run deltas.
+  - Markdown artifacts are written under `memory/reflections/YYYY-MM-DD/`.
+  - Filename uses high-resolution timestamp + agent/session token (with conflict-safe suffix), for example `HHMMSSmmm-agent-session[-xxxxxx].md`.
+- Store to LanceDB (optional):
+  - Controlled by `memoryReflection.storeToLanceDB` (effective only under `sessionStrategy=memoryReflection`).
+  - Only non-fallback reflections are eligible for LanceDB persistence.
+  - Additional similarity dedupe is applied before write (`> 0.97` hit skips storing).
+  - Reflections are stored with category `reflection`, and are displayed as `reflection:<scope>`.
+  - Stored metadata includes reflection execution fields such as `type`, `stage`, `sessionKey`, `sessionId`, `agentId`, `command`, `storedAt`, `invariants[]`, `derived[]`, `usedFallback`, and `errorSignals[]`.
+- Dedicated agent (optional): run reflection generation with another agent via `memoryReflection.agentId` (e.g. `memory-distiller`)
+  - If configured `memoryReflection.agentId` is not found in `cfg.agents.list`, plugin logs a clear warning and falls back to runtime agent id.
+  - For embedded runs, the plugin resolves the target agent's primary model ref (`provider/model`) and passes `provider` + `model` explicitly.
+- Inherit: `before_agent_start` injects `<inherited-rules>` from stable reflection invariants.
+- Derive: `before_prompt_build` injects `<derived-focus>` and `<error-detected>` blocks.
+  - `<derived-focus>` is sourced only from the latest recent non-fallback reflection and skips placeholder lines.
+  - Reflection-derived lines are extracted with `reflect|inherit|derive|change|apply` matching.
+- Error loop: `after_tool_call` captures and deduplicates tool error signatures for reminder/reflection context
+
+### 10. Markdown Mirror (`mdMirror`)
+
+- Purpose:
+  - Dual-write memory entries to readable Markdown files in addition to LanceDB.
+  - Useful for audit/debug/manual review.
+- Write paths:
+  - Preferred: mapped agent workspace `memory/YYYY-MM-DD.md`.
+  - Fallback: `mdMirror.dir` (default: `memory-md`) when agent workspace mapping is unavailable.
+- Trigger points:
+  - `memory_store` tool writes.
+  - Auto-capture writes from `agent_end`.
+- Compatibility:
+  - Does not replace LanceDB storage or retrieval flow.
+  - Existing retrieval remains vector/BM25/rerank based.
+- Config:
+  - `mdMirror.enabled`: enable/disable dual-write (`false` by default).
+  - `mdMirror.dir`: fallback directory for Markdown mirror files.
+
+### 11. Long Context Chunking
+
+Automatically handles documents that exceed embedding model context limits:
+
+- **Smart splitting**: Chunks at sentence boundaries with configurable overlap (default: 200 chars)
+- **Averaged embedding**: Each chunk is embedded separately, then averaged for semantic preservation
+- **Graceful error handling**: Detects "Input length exceeds context length" errors and retries with chunking
+- **Config toggle**: `embedding.chunking` — set `false` to disable (default: auto-enabled on context-length errors)
+- **Adapts to model limits**: Jina (8192 tokens), OpenAI (8191), Gemini (2048), etc.
+
+See [`docs/long-context-chunking.md`](docs/long-context-chunking.md) for implementation details.
+
+### 12. Embedding Error Diagnostics
+
+When embedding calls fail, the plugin provides **actionable error messages** instead of generic errors:
+
+- **Auth errors** (401/403): hints to check API key validity and format
+- **Network errors** (ECONNREFUSED, ETIMEDOUT): hints to verify `baseURL` and network connectivity
+- **Rate limits** (429): suggests retry or upgrading plan
+- **Model not found** (404): suggests checking model name against provider docs
+- **Context length exceeded**: automatically retries with chunking (see above)
+
+### 13. Auto-Capture & Auto-Recall
 
 - **Auto-Capture** (`agent_end` hook): Extracts preference/fact/decision/entity from conversations, deduplicates, stores up to 3 per turn
   - Skips memory-management prompts (e.g. delete/forget/cleanup memory entries) to reduce noise
@@ -337,11 +432,12 @@ openclaw config get plugins.slots.memory
   "dbPath": "~/.openclaw/memory/lancedb-pro",
   "autoCapture": true,
   "autoRecall": false,
+  "autoRecallMinLength": 8,
   "retrieval": {
     "mode": "hybrid",
     "vectorWeight": 0.7,
     "bm25Weight": 0.3,
-    "minScore": 0.3,
+    "minScore": 0.45,
     "rerank": "cross-encoder",
     "rerankApiKey": "${JINA_API_KEY}",
     "rerankModel": "jina-reranker-v3",
@@ -352,10 +448,13 @@ openclaw config get plugins.slots.memory
     "recencyWeight": 0.1,
     "filterNoise": true,
     "lengthNormAnchor": 500,
-    "hardMinScore": 0.35,
-    "timeDecayHalfLifeDays": 60
+    "hardMinScore": 0.55,
+    "timeDecayHalfLifeDays": 60,
+    "reinforcementFactor": 0.5,
+    "maxHalfLifeMultiplier": 3
   },
   "enableManagementTools": false,
+  "sessionStrategy": "systemSessionMemory",
   "scopes": {
     "default": "global",
     "definitions": {
@@ -366,15 +465,67 @@ openclaw config get plugins.slots.memory
       "discord-bot": ["global", "agent:discord-bot"]
     }
   },
-  "sessionMemory": {
+  "selfImprovement": {
+    "enabled": true,
+    "beforeResetNote": true,
+    "skipSubagentBootstrap": true,
+    "ensureLearningFiles": true
+  },
+  "memoryReflection": {
+    "storeToLanceDB": true,
+    "injectMode": "inheritance+derived",
+    "agentId": "memory-distiller",
+    "messageCount": 120,
+    "maxInputChars": 24000,
+    "timeoutMs": 20000,
+    "thinkLevel": "medium",
+    "errorReminderMaxEntries": 3,
+    "dedupeErrorSignals": true
+  },
+  "mdMirror": {
     "enabled": false,
-    "messageCount": 15
+    "dir": "memory-md"
   }
 }
 ```
 
 </details>
 
+### Parameter Mapping Notes (avoid common misconfig)
+
+`memory-lancedb-pro` does **not** support `recallTopK` / `recallThreshold`.
+
+Use these equivalents instead:
+
+- `recallTopK` → `retrieval.candidatePoolSize`
+- `recallThreshold` → combine `retrieval.minScore` + `retrieval.hardMinScore`
+
+A practical starting point for Chinese chat workloads:
+
+```json
+{
+  "autoCapture": true,
+  "autoRecall": true,
+  "autoRecallMinLength": 8,
+  "retrieval": {
+    "candidatePoolSize": 20,
+    "minScore": 0.45,
+    "hardMinScore": 0.55
+  }
+}
+```
+
+### Access Reinforcement (1.0.26)
+
+To make frequently used memories decay more slowly, the retriever can extend the effective time-decay half-life based on **manual recall frequency** (spaced-repetition style).
+
+Config keys (under `retrieval`):
+- `reinforcementFactor` (range: 0–2, default: `0.5`) — set `0` to disable
+- `maxHalfLifeMultiplier` (range: 1–10, default: `3`) — hard cap: effective half-life ≤ base × multiplier
+
+Notes:
+- Reinforcement is **whitelisted to `source: "manual"`** (i.e. user/tool initiated recall), to avoid accidental strengthening from auto-recall.
+
 ### Embedding Providers
 
 This plugin works with **any OpenAI-compatible embedding API**:
@@ -506,7 +657,7 @@ and keeps a cursor here:
 
 The script is **safe**: it never modifies session logs.
 
-By default it skips historical reset snapshots (`*.reset.*`) and excludes the distiller agent itself (`memory-distiller`) to prevent self-ingestion loops.
+By default it skips historical reset snapshots (`*.reset.*`), slash-command/control-note lines (for example `/note self-improvement ...`), and excludes the distiller agent itself (`memory-distiller`) to prevent self-ingestion loops.
 
 ### Optional: restrict distillation sources (allowlist)
 
@@ -767,29 +918,31 @@ Config-only changes do NOT need cache clearing.
 
 ## Contributors
 
-Top contributors (from GitHub’s contributors list, sorted by commit contributions; bots excluded):
+Top contributors (from GitHub's contributors list, sorted by commit contributions; bots excluded):
 
 <p>
 <a href="https://github.com/win4r"><img src="https://avatars.githubusercontent.com/u/42172631?v=4" width="48" height="48" alt="@win4r" /></a>
 <a href="https://github.com/kctony"><img src="https://avatars.githubusercontent.com/u/1731141?v=4" width="48" height="48" alt="@kctony" /></a>
 <a href="https://github.com/Akatsuki-Ryu"><img src="https://avatars.githubusercontent.com/u/8062209?v=4" width="48" height="48" alt="@Akatsuki-Ryu" /></a>
+<a href="https://github.com/AliceLJY"><img src="https://avatars.githubusercontent.com/u/136287420?v=4" width="48" height="48" alt="@AliceLJY" /></a>
 <a href="https://github.com/JasonSuz"><img src="https://avatars.githubusercontent.com/u/612256?v=4" width="48" height="48" alt="@JasonSuz" /></a>
 <a href="https://github.com/Minidoracat"><img src="https://avatars.githubusercontent.com/u/11269639?v=4" width="48" height="48" alt="@Minidoracat" /></a>
+<a href="https://github.com/rwmjhb"><img src="https://avatars.githubusercontent.com/u/91475811?v=4" width="48" height="48" alt="@rwmjhb" /></a>
 <a href="https://github.com/furedericca-lab"><img src="https://avatars.githubusercontent.com/u/263020793?v=4" width="48" height="48" alt="@furedericca-lab" /></a>
 <a href="https://github.com/joe2643"><img src="https://avatars.githubusercontent.com/u/19421931?v=4" width="48" height="48" alt="@joe2643" /></a>
-<a href="https://github.com/AliceLJY"><img src="https://avatars.githubusercontent.com/u/136287420?v=4" width="48" height="48" alt="@AliceLJY" /></a>
 <a href="https://github.com/chenjiyong"><img src="https://avatars.githubusercontent.com/u/8199522?v=4" width="48" height="48" alt="@chenjiyong" /></a>
 </p>
 
-- [@win4r](https://github.com/win4r) (3 commits)
+- [@win4r](https://github.com/win4r) (4 commits)
 - [@kctony](https://github.com/kctony) (2 commits)
 - [@Akatsuki-Ryu](https://github.com/Akatsuki-Ryu) (1 commit)
 - [@AliceLJY](https://github.com/AliceLJY) (1 commit)
-- [@chenjiyong](https://github.com/chenjiyong) (1 commit)
 - [@JasonSuz](https://github.com/JasonSuz) (1 commit)
 - [@Minidoracat](https://github.com/Minidoracat) (1 commit)
+- [@rwmjhb](https://github.com/rwmjhb) (1 commit)
 - [@furedericca-lab](https://github.com/furedericca-lab) (1 commit)
 - [@joe2643](https://github.com/joe2643) (1 commit)
+- [@chenjiyong](https://github.com/chenjiyong) (1 commit)
 
 Full list: https://github.com/win4r/memory-lancedb-pro/graphs/contributors
 

package/README_CN.md

@@ -80,7 +80,7 @@ OpenClaw 内置的 `memory-lancedb` 插件仅提供基本的向量搜索。**mem
 
 | 文件 | 用途 |
 |------|------|
-| `index.ts` | 插件入口。注册到 OpenClaw Plugin API，解析配置，挂载 `before_agent_start`（自动回忆）、`agent_end`（自动捕获）、`command:new`（Session 记忆）等钩子 |
+| `index.ts` | 插件入口。注册到 OpenClaw Plugin API，解析配置，挂载 `before_agent_start`（自动回忆）、`agent_end`（自动捕获）、集成 `self-improvement`（`agent:bootstrap`、`command:new/reset`）和集成 `memory-reflection`（`command:new/reset`）钩子 |
 | `openclaw.plugin.json` | 插件元数据 + 完整 JSON Schema 配置声明（含 `uiHints`） |
 | `package.json` | NPM 包信息，依赖 `@lancedb/lancedb`、`openai`、`@sinclair/typebox` |
 | `cli.ts` | CLI 命令实现：`memory list/search/stats/delete/delete-bulk/export/import/reembed/migrate` |
@@ -88,7 +88,7 @@ OpenClaw 内置的 `memory-lancedb` 插件仅提供基本的向量搜索。**mem
 | `src/embedder.ts` | Embedding 抽象层。兼容 OpenAI API 的任意 Provider（OpenAI、Gemini、Jina、Ollama 等），支持 task-aware embedding（`taskQuery`/`taskPassage`） |
 | `src/retriever.ts` | 混合检索引擎。Vector + BM25 → RRF 融合 → Jina Cross-Encoder Rerank → Recency Boost → Importance Weight → Length Norm → Time Decay → Hard Min Score → Noise Filter → MMR Diversity |
 | `src/scopes.ts` | 多 Scope 访问控制。支持 `global`、`agent:<id>`、`custom:<name>`、`project:<id>`、`user:<id>` 等 Scope 模式 |
-| `src/tools.ts` | Agent 工具定义：`memory_recall`、`memory_store`、`memory_forget`（核心）+ `memory_stats`、`memory_list`（管理） |
+| `src/tools.ts` | Agent 工具定义：`memory_recall`、`memory_store`、`memory_forget`（核心）、`self_improvement_log`（默认）+ `self_improvement_review`、`self_improvement_extract_skill`（管理模式） |
 | `src/noise-filter.ts` | 噪声过滤器。过滤 Agent 拒绝回复、Meta 问题、寒暄等低质量记忆 |
 | `src/adaptive-retrieval.ts` | 自适应检索。判断 query 是否需要触发记忆检索（跳过问候、命令、简单确认等） |
 | `src/migrate.ts` | 迁移工具。从旧版 `memory-lancedb` 插件迁移数据到 Pro 版 |
@@ -146,14 +146,108 @@ Query → BM25 FTS ─────┘
 - 过滤 Meta 问题（"do you remember"）
 - 过滤寒暄（"hi"、"hello"、"HEARTBEAT"）
 
-### 7. Session 记忆
-
-- `/new` 命令触发时可保存上一个 Session 的对话摘要到 LanceDB
-- 默认关闭（`enabled: false`），因为 OpenClaw 已有原生 .jsonl 会话保存
-- 开启会导致大段摘要污染检索质量，建议仅在需要语义搜索历史会话时开启
-- 可配置消息数量（默认 15 条）
-
-### 8. 自动捕获 & 自动回忆
+### 7. Session 策略
+
+- `sessionStrategy: "systemSessionMemory"`（默认）：关闭插件反思 hooks，改用 OpenClaw 内置 `session-memory`
+- `sessionStrategy: "memoryReflection"`：使用插件的 memory-reflection hooks（需显式开启）
+- `sessionStrategy: "none"`：禁用本插件的会话策略 hooks
+- 兼容说明：`sessionMemory.enabled=true|false` 映射为 `systemSessionMemory|none`
+- 升级行为说明：
+  - 旧版插件式 session summary 行为不再作为隐式默认值。
+  - 升级后，如果你希望 `/new` / `/reset` 走插件反思链路，必须显式设置 `sessionStrategy: "memoryReflection"`。
+  - 保留 `sessionMemory.enabled: true` 时，现在会走更安全的兼容路径 `systemSessionMemory`，而不是静默切到新的 reflection pipeline。
+
+### 8. Self-Improvement
+
+- 触发事件：`agent:bootstrap`、`command:new`、`command:reset`
+- `agent:bootstrap`：注入 `SELF_IMPROVEMENT_REMINDER.md` 到 bootstrap 上下文
+- `command:new` / `command:reset`：在会话重置前注入简短 `/note self-improvement ...` 提醒
+- 文件：确保 `.learnings/LEARNINGS.md`、`.learnings/ERRORS.md`、`.learnings/FEATURE_REQUESTS.md` 存在
+- 行为说明：
+  - 这条链路集成在插件生命周期内，可与 `sessionStrategy=systemSessionMemory` 共存。
+  - 它与 `memoryReflection` 是分开的：看到 self-improvement note 或 `.learnings/*` 写入，并不等于 reflection 存储已经开启。
+  - 治理类 extract/review 动作仍然是显式工具触发，不是后台自动触发。
+- 工具：
+  - `self_improvement_log`：写入结构化 LRN/ERR/FEAT 条目
+  - `self_improvement_review`：汇总治理 backlog（pending/high/promoted）
+  - `self_improvement_extract_skill`：从学习条目提炼可复用 `SKILL.md` 脚手架
+    - 触发者：由用户/模型显式调用工具触发（非后台自动触发）
+    - 时机：按需、单次执行
+    - 输入：需明确提供 `learningId` 与 `skillName`
+    - 风险画像：低风险、可控，误写概率更低
+    - 推荐方式：先稳定流程，再由人工把关质量
+
+### 9. memoryReflection
+
+- 触发条件：
+  - `sessionStrategy` 必须为 `memoryReflection`（需显式配置）。
+  - 触发事件为 `command:new` / `command:reset`。
+  - 若会话上下文不完整（例如缺少 `cfg`、session 文件、可读对话内容），会跳过反思生成。
+- 反思执行链：
+  - 先尝试 embedded runner（`runEmbeddedPiAgent`）。
+  - 若 embedded 路径失败，自动回退到 `openclaw agent --local --json`。
+  - 仅当两者都失败时，才写入最小 fallback 反思文本。
+- Reflect 产物：
+  - 结构化输出应包含这些段落：`## Context`、`## Decisions (durable)`、`## User model deltas (about the human)`、`## Agent model deltas (about the assistant/system)`、`## Lessons & pitfalls (symptom / cause / fix / prevention)`、`## Learning governance candidates (.learnings / promotion / skill extraction)`、`## Open loops / next actions`、`## Retrieval tags / keywords`、`## Invariants`、`## Derived`。
+  - `## Invariants` 用于稳定规则沉淀；`## Derived` 用于下一次执行增量。
+  - Markdown 产物写入 `memory/reflections/YYYY-MM-DD/`。
+  - 文件名为高精度时间戳 + agent/session token（带冲突后缀），例如 `HHMMSSmmm-agent-session[-xxxxxx].md`。
+- 写入 LanceDB（可选）：
+  - 由 `memoryReflection.storeToLanceDB` 控制（且仅在 `sessionStrategy=memoryReflection` 下生效）。
+  - 只有非 fallback 反思才会进入 LanceDB 持久化流程。
+  - 写入前会做相似度去重（命中 `> 0.97` 则跳过入库）。
+  - 反思记忆写入时使用分类 `reflection`，展示标签为 `reflection:<scope>`。
+  - 写入的 metadata 会包含反思执行字段，例如 `type`、`stage`、`sessionKey`、`sessionId`、`agentId`、`command`、`storedAt`、`invariants[]`、`derived[]`、`usedFallback`、`errorSignals[]`。
+- 独立代理（可选）：通过 `memoryReflection.agentId` 指定用于反思生成的代理（例如 `memory-distiller`）
+  - 若配置的 `memoryReflection.agentId` 不在 `cfg.agents.list` 中，插件会明确 `warn` 并回退到当前 runtime agent id。
+  - 对 embedded 运行，插件会解析目标代理主模型引用（`provider/model`），并显式传入 `provider` 与 `model`。
+- Inherit：`before_agent_start` 注入 `<inherited-rules>`，来源是稳定的 reflection invariants。
+- Derive：`before_prompt_build` 注入 `<derived-focus>` 与 `<error-detected>`。
+  - `<derived-focus>` 仅取最近且非 fallback 的反思，并过滤占位行。
+  - 派生行提取关键词：`reflect|inherit|derive|change|apply`。
+- 错误闭环：`after_tool_call` 捕获并去重工具错误签名，用于提醒与反思上下文
+
+### 10. Markdown 镜像（`mdMirror`）
+
+- 作用：
+  - 在写入 LanceDB 的同时，把记忆双写到可读的 Markdown 文件。
+  - 便于审计、排查和人工复核。
+- 写入路径：
+  - 优先：按 agent workspace 映射写入 `memory/YYYY-MM-DD.md`。
+  - 回退：当 agent workspace 不可解析时，写入 `mdMirror.dir`（默认 `memory-md`）。
+- 触发路径：
+  - `memory_store` 工具写入。
+  - `agent_end` 自动捕获写入。
+- 兼容性：
+  - 不替代 LanceDB 存储，不影响现有检索链路。
+  - 检索仍走 vector/BM25/rerank。
+- 配置项：
+  - `mdMirror.enabled`：是否开启双写（默认 `false`）。
+  - `mdMirror.dir`：Markdown 镜像回退目录。
+
+### 11. 长文本分块嵌入（Long Context Chunking）
+
+自动处理超出 Embedding 模型上下文限制的长文本：
+
+- **智能分割**：在句子边界分块，支持可配置重叠区（默认 200 字符）
+- **平均嵌入**：分别 embed 每个块，再取平均向量保留语义
+- **优雅降级**：检测到 "Input length exceeds context length" 时自动重试分块
+- **配置开关**：`embedding.chunking` — 设为 `false` 可关闭（默认：遇到上下文超限自动开启）
+- **适配各模型限制**：Jina（8192 tokens）、OpenAI（8191）、Gemini（2048）等
+
+详细实现参见 [`docs/long-context-chunking.md`](docs/long-context-chunking.md)。
+
+### 12. Embedding 错误诊断
+
+当 Embedding 调用失败时，插件提供**可操作的错误提示**，而非笼统的报错信息：
+
+- **认证错误**（401/403）：提示检查 API key 有效性和格式
+- **网络错误**（ECONNREFUSED、ETIMEDOUT）：提示检查 `baseURL` 和网络连通性
+- **频率限制**（429）：建议重试或升级套餐
+- **模型未找到**（404）：建议核对模型名称是否与提供商文档一致
+- **上下文超长**：自动重试分块嵌入（见上文）
+
+### 13. 自动捕获 & 自动回忆
 
 - **Auto-Capture**（`agent_end` hook）: 从对话中提取 preference/fact/decision/entity，去重后存储（每次最多 3 条）
   - 触发词支持 **简体中文 + 繁體中文**（例如：记住/記住、偏好/喜好/喜歡、决定/決定 等）
@@ -338,11 +432,12 @@ openclaw config get plugins.slots.memory
   "dbPath": "~/.openclaw/memory/lancedb-pro",
   "autoCapture": true,
   "autoRecall": false,
+  "autoRecallMinLength": 8,
   "retrieval": {
     "mode": "hybrid",
     "vectorWeight": 0.7,
     "bm25Weight": 0.3,
-    "minScore": 0.3,
+    "minScore": 0.45,
     "rerank": "cross-encoder",
     "rerankApiKey": "${JINA_API_KEY}",
     "rerankModel": "jina-reranker-v3",
@@ -352,9 +447,12 @@ openclaw config get plugins.slots.memory
     "filterNoise": true,
     "lengthNormAnchor": 500,
     "hardMinScore": 0.35,
-    "timeDecayHalfLifeDays": 60
+    "timeDecayHalfLifeDays": 60,
+    "reinforcementFactor": 0.5,
+    "maxHalfLifeMultiplier": 3
   },
   "enableManagementTools": false,
+  "sessionStrategy": "systemSessionMemory",
   "scopes": {
     "default": "global",
     "definitions": {
@@ -365,15 +463,67 @@ openclaw config get plugins.slots.memory
       "discord-bot": ["global", "agent:discord-bot"]
     }
   },
-  "sessionMemory": {
+  "selfImprovement": {
+    "enabled": true,
+    "beforeResetNote": true,
+    "skipSubagentBootstrap": true,
+    "ensureLearningFiles": true
+  },
+  "memoryReflection": {
+    "storeToLanceDB": true,
+    "injectMode": "inheritance+derived",
+    "agentId": "memory-distiller",
+    "messageCount": 120,
+    "maxInputChars": 24000,
+    "timeoutMs": 20000,
+    "thinkLevel": "medium",
+    "errorReminderMaxEntries": 3,
+    "dedupeErrorSignals": true
+  },
+  "mdMirror": {
     "enabled": false,
-    "messageCount": 15
+    "dir": "memory-md"
   }
 }
 ```
 
 </details>
 
+### 参数映射提示（避免常见误配）
+
+`memory-lancedb-pro` **不支持** `recallTopK` / `recallThreshold` 这两个字段。
+
+如果你希望达到类似效果，请使用下列等价参数：
+
+- `recallTopK` → `retrieval.candidatePoolSize`
+- `recallThreshold` → 组合使用 `retrieval.minScore` + `retrieval.hardMinScore`
+
+实战上，中文对话可先从以下配置起步（再按误召回情况微调）：
+
+```json
+{
+  "autoCapture": true,
+  "autoRecall": true,
+  "autoRecallMinLength": 8,
+  "retrieval": {
+    "candidatePoolSize": 20,
+    "minScore": 0.45,
+    "hardMinScore": 0.55
+  }
+}
+```
+
+### 访问强化（1.0.26）
+
+为了让“经常被用到的记忆”衰减得更慢，检索器可以根据 **手动 recall 的频率**（类似间隔重复/记忆强化）来延长有效的 time-decay half-life。
+
+配置项（位于 `retrieval` 下）：
+- `reinforcementFactor`（范围 0–2，默认 `0.5`）— 设为 `0` 可关闭
+- `maxHalfLifeMultiplier`（范围 1–10，默认 `3`）— 硬上限：有效 half-life ≤ 基础值 × multiplier
+
+说明：
+- 强化逻辑只对白名单 `source: "manual"` 生效（用户/工具主动 recall），避免 auto-recall 意外“强化”噪声。
+
 ### Embedding 提供商
 
 本插件支持 **任意 OpenAI 兼容的 Embedding API**：
@@ -427,7 +577,7 @@ Legacy 方案：本插件也提供一个安全的 extractor 脚本 `scripts/json
 - Cursor：`~/.openclaw/state/jsonl-distill/cursor.json`
 - Batches：`~/.openclaw/state/jsonl-distill/batches/`
 
-> 脚本只读 session JSONL，不会修改原始日志。
+> 脚本只读 session JSONL，不会修改原始日志。默认会跳过 `*.reset.*` 快照与 slash 命令/控制注记行（例如 `/note self-improvement ...`）。
 
 ### （可选）启用 Agent 来源白名单（提高信噪比）
 
@@ -647,23 +797,25 @@ Config-only changes do NOT need cache clearing.
 <a href="https://github.com/win4r"><img src="https://avatars.githubusercontent.com/u/42172631?v=4" width="48" height="48" alt="@win4r" /></a>
 <a href="https://github.com/kctony"><img src="https://avatars.githubusercontent.com/u/1731141?v=4" width="48" height="48" alt="@kctony" /></a>
 <a href="https://github.com/Akatsuki-Ryu"><img src="https://avatars.githubusercontent.com/u/8062209?v=4" width="48" height="48" alt="@Akatsuki-Ryu" /></a>
+<a href="https://github.com/AliceLJY"><img src="https://avatars.githubusercontent.com/u/136287420?v=4" width="48" height="48" alt="@AliceLJY" /></a>
 <a href="https://github.com/JasonSuz"><img src="https://avatars.githubusercontent.com/u/612256?v=4" width="48" height="48" alt="@JasonSuz" /></a>
 <a href="https://github.com/Minidoracat"><img src="https://avatars.githubusercontent.com/u/11269639?v=4" width="48" height="48" alt="@Minidoracat" /></a>
+<a href="https://github.com/rwmjhb"><img src="https://avatars.githubusercontent.com/u/91475811?v=4" width="48" height="48" alt="@rwmjhb" /></a>
 <a href="https://github.com/furedericca-lab"><img src="https://avatars.githubusercontent.com/u/263020793?v=4" width="48" height="48" alt="@furedericca-lab" /></a>
 <a href="https://github.com/joe2643"><img src="https://avatars.githubusercontent.com/u/19421931?v=4" width="48" height="48" alt="@joe2643" /></a>
-<a href="https://github.com/AliceLJY"><img src="https://avatars.githubusercontent.com/u/136287420?v=4" width="48" height="48" alt="@AliceLJY" /></a>
 <a href="https://github.com/chenjiyong"><img src="https://avatars.githubusercontent.com/u/8199522?v=4" width="48" height="48" alt="@chenjiyong" /></a>
 </p>
 
-- [@win4r](https://github.com/win4r)（3 次提交）
+- [@win4r](https://github.com/win4r)（4 次提交）
 - [@kctony](https://github.com/kctony)（2 次提交）
 - [@Akatsuki-Ryu](https://github.com/Akatsuki-Ryu)（1 次提交）
 - [@AliceLJY](https://github.com/AliceLJY)（1 次提交）
-- [@chenjiyong](https://github.com/chenjiyong)（1 次提交）
 - [@JasonSuz](https://github.com/JasonSuz)（1 次提交）
 - [@Minidoracat](https://github.com/Minidoracat)（1 次提交）
+- [@rwmjhb](https://github.com/rwmjhb)（1 次提交）
 - [@furedericca-lab](https://github.com/furedericca-lab)（1 次提交）
 - [@joe2643](https://github.com/joe2643)（1 次提交）
+- [@chenjiyong](https://github.com/chenjiyong)（1 次提交）
 
 完整列表：https://github.com/win4r/memory-lancedb-pro/graphs/contributors