@memtensor/memos-local-openclaw-plugin 0.1.3 → 0.1.5

package/.env.example

@@ -1,11 +1,19 @@
-# Embedding API
-# Use any OpenAI-compatible embedding service, or leave blank for local offline model
+# ─── Embedding API ───
+# Use any OpenAI-compatible embedding service, or leave blank for local offline model (Xenova/all-MiniLM-L6-v2)
+EMBEDDING_PROVIDER=openai_compatible
 EMBEDDING_API_KEY=your-embedding-api-key
-EMBEDDING_ENDPOINT=https://api.openai.com/v1
-EMBEDDING_MODEL=text-embedding-3-small
+EMBEDDING_ENDPOINT=https://your-embedding-api.com/v1
+EMBEDDING_MODEL=bge-m3
 
-# Summarizer API (OpenAI-compatible)
+# ─── Summarizer API ───
+# OpenAI-compatible LLM for one-sentence chunk summaries
 # Leave blank to use rule-based fallback (no LLM needed)
+SUMMARIZER_PROVIDER=openai_compatible
 SUMMARIZER_API_KEY=your-summarizer-api-key
 SUMMARIZER_ENDPOINT=https://api.openai.com/v1
 SUMMARIZER_MODEL=gpt-4o-mini
+SUMMARIZER_TEMPERATURE=0
+
+# ─── Memory Viewer ───
+# Port for the web-based Memory Viewer (default: 18799)
+# VIEWER_PORT=18799

package/README.md

@@ -1,18 +1,62 @@
-# 🦞 MemOS Local — OpenClaw Memory Plugin
+# 🧠 MemOS Local — OpenClaw Memory Plugin
 
-Persistent local conversation memory for [OpenClaw](https://github.com/nicepkg/openclaw) AI Agents. Every conversation is automatically captured, semantically indexed, and instantly recallable.
+Persistent local conversation memory for [OpenClaw](https://github.com/nicepkg/openclaw) AI Agents. Every conversation is automatically captured, semantically indexed, and instantly recallable — with **smart task summarization** and **automatic skill evolution**.
 
-**Full-write | Hybrid Search (FTS5 + Vector) | RRF Fusion | MMR Diversity | Recency Decay**
+**Full-write | Hybrid Search | Task Summarization | Skill Evolution | Memory Viewer**
+
+## Why MemOS Local
+
+| Problem | Solution |
+|---------|----------|
+| Agent forgets everything between sessions | **Persistent memory** — every conversation auto-captured to local SQLite |
+| Fragmented memory chunks lack context | **Smart task summarization** — conversations organized into structured tasks with goals, steps, results |
+| Agent repeats past mistakes on similar tasks | **Skill evolution** — reusable skills auto-generated from real executions, continuously upgraded |
+| No visibility into what the agent remembers | **Memory Viewer** — full visualization of all memories, tasks, and skills |
+| Privacy concerns with cloud storage | **100% local** — zero cloud uploads, zero telemetry, password-protected |
 
 ## Features
 
-- **Auto-capture** — Stores user, assistant, and tool messages after each agent turn
-- **Semantic chunking** — Preserves complete code blocks, function bodies, and paragraph boundaries
+### Memory Engine
+- **Auto-capture** — Stores user, assistant, and tool messages after each agent turn via `agent_end` event (consecutive assistant messages merged into one)
+- **Smart deduplication** — Exact content-hash skip; then Top-5 similar chunks (threshold 0.75) with LLM judge: DUPLICATE (skip), UPDATE (merge summary + append content), or NEW (create). Evolved chunks track merge history.
+- **Semantic chunking** — Splits by code blocks, function bodies, paragraphs; never cuts mid-function
 - **Hybrid retrieval** — FTS5 keyword + vector semantic dual-channel search with RRF fusion
-- **LLM summarization** — One-sentence summary per chunk for fast browsing
-- **Multi-provider** — OpenAI, Anthropic, Gemini, Cohere, Voyage, Mistral, Bedrock, or local offline
-- **Web viewer** — Built-in dashboard at `http://127.0.0.1:18799` with CRUD, search, filters, pagination
-- **Privacy first** — All data in local SQLite, no cloud uploads, password-protected viewer
+- **MMR diversity** — Maximal Marginal Relevance reranking prevents near-duplicate results
+- **Recency decay** — Configurable time-based decay (half-life: 14 days) biases recent memories
+- **Multi-provider embedding** — OpenAI-compatible, Gemini, Cohere, Voyage, Mistral, or local offline (Xenova/all-MiniLM-L6-v2)
+
+### Task Summarization
+- **Auto task boundary detection** — LLM topic judgment + 2-hour idle timeout segments conversations into tasks
+- **Structured summaries** — LLM generates Goal, Key Steps, Result, Key Details for each completed task
+- **Key detail preservation** — Code, commands, URLs, file paths, error messages retained in summaries
+- **Quality filtering** — Tasks with too few chunks, too few turns, or trivial content are auto-skipped
+- **Task status** — `active` (in progress), `completed` (with LLM summary), `skipped` (too brief, excluded from search)
+
+### Skill Evolution
+- **Automatic evaluation** — After task completion, rule filter + LLM evaluates if the task is worth distilling into a skill
+- **Skill generation** — Multi-step LLM pipeline creates SKILL.md + scripts + references + evals from real execution records
+- **Skill upgrading** — When similar tasks appear, existing skills are auto-upgraded (refine / extend / fix)
+- **Quality scoring** — 0-10 quality assessment; scores below 6 marked as draft
+- **Version management** — Full version history with changelog, change summary, and upgrade type tracking
+- **Auto-install** — Generated skills can be auto-installed into the workspace for immediate use
+- **Dedicated model** — Optional separate LLM model for skill generation (e.g., Claude 4.6 for higher quality)
+
+### Memory Viewer
+- **6 management pages** — Memories, Tasks, Skills, Analytics, **Logs**, Settings
+- **Full CRUD** — Create, edit, delete, search memories; evolution badges and merge history on memory cards
+- **Task browser** — Status filters, chat-bubble chunk view, structured summaries, skill generation status
+- **Skill browser** — Version history, quality scores, one-click download as ZIP
+- **Analytics dashboard** — Daily read/write activity, memory breakdown charts
+- **Logs** — Tool call log (memory_search, auto_recall, memory_add, etc.) with input/output and duration; filter by tool, auto-refresh
+- **Online configuration** — Modify embedding, summarizer, skill evolution settings via web UI
+- **Security** — Password-protected, localhost-only (127.0.0.1), session cookies
+- **i18n** — Chinese / English toggle
+- **Themes** — Light / Dark mode
+
+### Privacy & Security
+- **100% on-device** — All data in local SQLite, no cloud uploads, no telemetry
+- **Viewer security** — Binds to 127.0.0.1 only, password-protected with session cookies
+- **Auto-recall + Skill** — Each turn, relevant memories are injected via `before_agent_start` hook (invisible to user). When nothing is recalled (e.g. long or unclear query), the agent is prompted to call `memory_search` with a self-generated short query. The bundled skill `memos-memory-guide` documents all tools and when to use them.
 
 ## Quick Start
 
@@ -24,9 +68,9 @@ Persistent local conversation memory for [OpenClaw](https://github.com/nicepkg/o
 openclaw plugins install @memtensor/memos-local-openclaw-plugin
 ```
 
-The plugin is installed under `~/.openclaw/extensions/` and registered as `memos-local`. No clone or build required.
+The plugin is installed under `~/.openclaw/extensions/memos-local` and registered as `memos-local`.
 
-> **Important:** Installing the plugin does **not** start the Memory Viewer. The viewer HTTP service is started only when the **OpenClaw gateway** is running. After install, you must **configure** `openclaw.json` (step 2) and **start or restart the gateway** (step 3); then the viewer will be available at `http://127.0.0.1:18799`.
+> **Important:** The Memory Viewer starts only when the **OpenClaw gateway** is running. After install, **configure** `openclaw.json` (step 2) and **start the gateway** (step 3); the viewer will then be available at `http://127.0.0.1:18799`.
 
 **From source (development):**
 
@@ -43,6 +87,14 @@ Add the plugin config to `~/.openclaw/openclaw.json`:
 
 ```jsonc
 {
+  "agents": {
+    "defaults": {
+      // IMPORTANT: Disable OpenClaw's built-in memory to avoid conflicts
+      "memorySearch": {
+        "enabled": false
+      }
+    }
+  },
   "plugins": {
     "slots": {
       "memory": "memos-local"
@@ -71,6 +123,8 @@ Add the plugin config to `~/.openclaw/openclaw.json`:
 }
 ```
 
+> **Critical:** You must set `agents.defaults.memorySearch.enabled` to `false`. Otherwise OpenClaw's built-in memory search runs alongside this plugin, causing duplicate retrieval and wasted tokens.
+
 #### Embedding Provider Options
 
 | Provider | `provider` value | Example `model` | Notes |
@@ -95,6 +149,30 @@ Add the plugin config to `~/.openclaw/openclaw.json`:
 
 > **No summarizer config?** A rule-based fallback generates summaries from the first sentence + key entities. Good enough to start.
 
+#### Skill Evolution Configuration (Optional)
+
+You can optionally configure a dedicated model for skill generation (for higher quality skills):
+
+```jsonc
+{
+  "config": {
+    "skillSummarizer": {
+      "provider": "anthropic",
+      "apiKey": "sk-ant-xxx",
+      "model": "claude-sonnet-4-20250514",
+      "temperature": 0
+    },
+    "skillEvolution": {
+      "enabled": true,
+      "autoEvaluate": true,
+      "autoInstall": false
+    }
+  }
+}
+```
+
+If `skillSummarizer` is not configured, the plugin uses the regular `summarizer` model for skill generation.
+
 #### Environment Variable Support
 
 Use `${ENV_VAR}` placeholders in config to avoid hardcoding keys:
@@ -107,8 +185,6 @@ Use `${ENV_VAR}` placeholders in config to avoid hardcoding keys:
 
 ### 3. Start or Restart the Gateway
 
-The Memory Viewer and all plugin features only run when the OpenClaw gateway is running. After installing and configuring the plugin, start (or restart) the gateway:
-
 ```bash
 openclaw gateway stop    # if already running
 openclaw gateway install # ensure LaunchAgent is installed (macOS)
@@ -120,7 +196,6 @@ Once the gateway is up, the plugin loads and starts the Memory Viewer at `http:/
 ### 4. Verify Installation
 
 ```bash
-# Check the gateway log
 tail -20 ~/.openclaw/logs/gateway.log
 ```
 
@@ -145,105 +220,146 @@ memos-local: started (embedding: openai_compatible)
 **Step C** — In a new conversation, ask the agent to recall what you discussed:
 
 ```
-You: Do you remember what we talked about?
-Agent: (calls memory_search) Yes, we discussed...
+You: 你还记得我之前让你帮我处理过什么事情吗？
+Agent: (calls memory_search) 是的，我们之前讨论过...
 ```
 
-**Step D** — Check the gateway log for ingest activity:
+## How It Works
 
-```bash
-grep -E "Stored chunk|Chunked turn|Dedup" ~/.openclaw/logs/gateway.log | tail -10
+### Three Intelligent Pipelines
+
+MemOS Local operates through three interconnected pipelines that form a continuous learning loop:
+
+```
+Conversation → Memory Write Pipeline → Task Generation Pipeline → Skill Evolution Pipeline
+                                                                          ↓
+                              Smart Retrieval Pipeline ← ← ← ← ← ← ← ← ←
 ```
 
-You should see lines like:
+### Pipeline 1: Memory Write (auto on every agent turn)
 
 ```
-Chunked turn=1772459198930-839rr3 into 3 chunks
-Stored chunk=667f289e kind=paragraph len=392 hasVec=true
-Stored chunk=107d7f32 kind=tool_result role=tool len=210 hasVec=true
+Conversation → Capture (filter roles, strip system prompts)
+→ Semantic chunking (code blocks, paragraphs, error stacks)
+→ Content hash dedup → LLM summarize each chunk
+→ Vector embedding → Store (SQLite + FTS5 + Vector)
 ```
 
-### 6. Run the Smoke Test (Optional)
+- System messages are skipped; tool results from the plugin's own tools are not re-stored
+- Evidence wrapper blocks (`[STORED_MEMORY]...[/STORED_MEMORY]`) are stripped to prevent feedback loops
+- Content hash (SHA-256, first 16 hex chars) prevents duplicate chunk ingestion within the same session+role
 
-If you have the source (e.g. cloned the repo or develop locally):
+### Pipeline 2: Task Generation (auto after memory write)
 
-```bash
-cd MemOS/apps/memos-local-openclaw   # or the path where the plugin source is
-cp .env.example .env
-# Edit .env with your actual API keys
-npx tsx scripts/smoke-test.ts
+```
+New chunks → Task boundary detection (LLM topic judge / 2h idle / session change)
+→ Boundary crossed? → Finalize previous task
+  → Chunks ≥ 4 & turns ≥ 2? → LLM structured summary → status = "completed"
+  → Otherwise → status = "skipped" (excluded from search)
 ```
 
-The smoke test writes test conversations, searches for them, verifies timeline and get operations, and checks anti-writeback protection. If you installed only from npm, you can skip this step.
+**Why Tasks matter:**
+- Raw memory chunks are fragmented — a single conversation about "deploying Nginx" might span 20 chunks
+- Task summarization organizes these fragments into a structured record: Goal → Steps → Result → Key Details
+- When the agent searches memory, it can quickly locate the complete experience via `task_summary`, not just fragments
+- Task summaries preserve code, commands, URLs, configs, and error messages
 
-### Reinstall (when install fails or you need to upgrade)
+### Pipeline 3: Skill Evolution (auto after task completion)
 
-If you see **"plugin already exists"** or **"plugin not found"** after deleting the plugin folder:
+```
+Completed task → Rule filter (min chunks, non-trivial content)
+→ Search for related existing skills
+  → Related skill found (confidence ≥ 0.7)?
+    → Evaluate upgrade (refine/extend/fix) → Merge new experience → Version bump
+  → No related skill (or confidence < 0.3)?
+    → Evaluate create → Generate SKILL.md + scripts + evals
+    → Quality score (0-10) → Install if score ≥ 6
+```
 
-1. **Option A — Use OpenClaw install (recommended when config does not reference the plugin yet)**  
-   Delete the extension folder, then run:
-   ```bash
-   rm -rf ~/.openclaw/extensions/memos-local
-   openclaw plugins install @memtensor/memos-local-openclaw-plugin
-   ```
-   If your `openclaw.json` already has `plugins.slots.memory: "memos-local"` and `plugins.entries.memos-local`, the config check may fail with "plugin not found" before install runs. In that case use Option B.
+**Why Skills matter:**
+- Without skills, agents rediscover solutions every time they encounter similar problems
+- Skills crystallize successful executions into reusable guides with steps, pitfall warnings, and verification checks
+- Skills auto-upgrade when new tasks bring improved approaches — getting faster, more accurate, and more token-efficient
+- The evolution is automatic: task completes → evaluate → create/upgrade → install
 
-2. **Option B — Manual install (when config already references memos-local)**  
-   Delete the folder, then install from npm and extract:
-   ```bash
-   rm -rf ~/.openclaw/extensions/memos-local
-   cd /tmp
-   npm pack @memtensor/memos-local-openclaw-plugin
-   tar -xzf memtensor-memos-local-openclaw-plugin-*.tgz
-   mv package ~/.openclaw/extensions/memos-local
-   ```
-   **No need to run `npm install`** — on first load the plugin will install dependencies automatically. Then restart the gateway: `openclaw gateway stop` then `openclaw gateway start`.
+### Pipeline 4: Smart Retrieval
 
-**Plugin shows as "error" in `openclaw plugins list`?** (e.g. `Cannot find module '@sinclair/typebox'`)  
-If auto-install failed (e.g. `npm` not in PATH when the gateway runs), install dependencies manually once:
+**Auto-recall (every turn):** The plugin hooks `before_agent_start`, runs a memory search with the user's message, then uses an LLM to filter which candidates are relevant and whether they are sufficient to answer. The filtered memories are injected into the agent's system context (invisible to the user). If no memories are found or the query is long/unclear, the agent is prompted to call `memory_search` with a self-generated short query.
 
-```bash
-cd ~/.openclaw/extensions/memos-local && npm install --omit=dev
+**On-demand search (`memory_search`):**
+```
+Query → FTS5 + Vector dual recall → RRF Fusion → MMR Rerank
+→ Recency Decay → Score Filter → Top-K (e.g. 20)
+→ LLM relevance filter (minimum information) → Dedup by excerpt overlap
+→ Return excerpts + chunkId / task_id (no summaries)
+  → sufficient=false → suggest task_summary(taskId), skill_get(taskId), memory_timeline(chunkId)
 ```
 
-Then restart the gateway.
+- **RRF (Reciprocal Rank Fusion):** Merges FTS5 and vector search rankings into a unified score
+- **MMR (Maximal Marginal Relevance):** Re-ranks to balance relevance with diversity
+- **Recency Decay:** Recent memories get a boost (half-life: 14 days by default)
+- **LLM filter:** Only memories that are genuinely useful for the query are returned; sufficiency determines whether follow-up tool tips are appended
+
+## Retrieval Strategy
+
+1. **Auto-recall (hook)** — On every turn, the plugin runs a memory search using the user's message and injects LLM-filtered relevant memories into the agent's context (via `before_agent_start`). The agent sees this as system context; the user does not.
+2. **When nothing is recalled** — If the user's message is long, vague, or no matches are found, the plugin injects a short hint telling the agent to call **`memory_search`** with a **self-generated short query** (e.g. key topics or a rephrased question).
+3. **Bundled skill** — The plugin installs `memos-memory-guide` into `~/.openclaw/workspace/skills/memos-memory-guide/` and `~/.openclaw/skills/memos-memory-guide/`. This skill documents all memory tools, when to call them, and how to write good search queries. Add `skills.load.extraDirs: ["~/.openclaw/skills"]` in `openclaw.json` if you want the skill to appear in the OpenClaw skills dashboard.
+4. **Search results** — `memory_search` returns **excerpts** (original content snippets) and IDs (`chunkId`, `task_id`), not summaries. The agent uses `task_summary(taskId)`, `memory_timeline(chunkId)`, and `skill_get(skillId|taskId)` to drill down when needed. There is no `memory_get`; full context is obtained via `task_summary` or `memory_timeline`.
 
 ## Agent Tools
 
-The plugin registers 4 tools that your agent can use:
+The plugin registers **6 tools** and auto-installs the **memos-memory-guide** skill:
 
-| Tool | Purpose |
-|---|---|
-| `memory_search` | Search memories by natural language query |
-| `memory_timeline` | Get surrounding context for a search hit |
-| `memory_get` | Get full original text of a memory chunk |
-| `memory_viewer` | Get the URL of the web dashboard |
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `memory_search` | Search memories; returns excerpts + `chunkId` / `task_id` | When auto-recall returned nothing or you need a different query; use a short, self-generated query if the user's message was long or unclear |
+| `task_summary` | Full structured summary of a completed task | When a hit has `task_id` and you need the full story (goal, steps, result) |
+| `memory_timeline` | Surrounding conversation around a chunk | When you need the exact dialogue before/after a hit; pass `chunkId` from the hit |
+| `skill_get` | Get skill content by `skillId` or `taskId` | When a hit has a linked task/skill and you want the reusable experience guide |
+| `skill_install` | Install a skill into the agent workspace | When the skill should be permanently available for future turns |
+| `memory_viewer` | Get the URL of the Memory Viewer web UI | When the user asks where to view or manage their memories |
+
+There is no `memory_get`; search returns excerpts and IDs; use `task_summary` or `memory_timeline` for deeper context.
 
-The agent uses these automatically via the SKILL.md prompt guide.
+### Search Parameters
+
+| Parameter | Default | Range | Description |
+|-----------|---------|-------|-------------|
+| `query` | — | — | Natural language search query (keep it short and focused) |
+| `maxResults` | 20 | 1–20 | Maximum candidates before LLM filter |
+| `minScore` | 0.45 | 0.35–1.0 | Minimum relevance score |
+| `role` | — | `user` / `assistant` / `tool` | Filter by message role (e.g. `user` to find what the user said) |
 
 ## Memory Viewer
 
-Open `http://127.0.0.1:18799` in your browser:
+Open `http://127.0.0.1:18799` in your browser after starting the gateway.
 
-**Viewer won't open or page not loading?**
+**Pages:**
 
-- The viewer is started by the plugin when the **gateway** starts. It does **not** run at install time.
-- Ensure the gateway is running: `openclaw gateway start` (or restart with `openclaw gateway stop` then `openclaw gateway start`).
-- Ensure the plugin is enabled in `~/.openclaw/openclaw.json`: `plugins.slots.memory` = `"memos-local"` and `plugins.entries.memos-local.enabled` = `true`.
-- Check the gateway log: `tail -30 ~/.openclaw/logs/gateway.log` — you should see `MemOS Memory Viewer` and `→ http://127.0.0.1:18799`. If the viewer fails to bind (e.g. port in use), the log will show a warning.
+| Page | Features |
+|------|----------|
+| **Memories** | Timeline view, pagination, session/role/kind/date filters, CRUD, semantic search; evolution badges and merge history on cards |
+| **Tasks** | Task list with status filters (active/completed/skipped), chat-bubble chunk view, structured summaries, skill generation status |
+| **Skills** | Skill list with status badges, version history with changelogs, quality scores, related tasks, one-click ZIP download |
+| **Analytics** | Daily write/read activity charts, memory/task/skill totals, role breakdown |
+| **Logs** | Tool call log (memory_search, auto_recall, memory_add, etc.) with input/output, duration, and tool filter; auto-refresh |
+| **Settings** | Online configuration for embedding model, summarizer model, skill evolution settings, viewer port |
 
-- First visit: set a password (min 4 chars)
-- Browse, search, create, edit, delete memories
-- Filter by role (user/assistant/tool), type, time range (down to seconds)
-- Pagination (30 per page)
+**Viewer won't open?**
 
-**Forgot password?** Click "Forgot password?" on the login page and use the reset token from the gateway log:
+- The viewer is started by the plugin when the **gateway** starts. It does **not** run at install time.
+- Ensure the gateway is running: `openclaw gateway start`
+- Ensure the plugin is enabled in `~/.openclaw/openclaw.json`
+- Check the log: `tail -30 ~/.openclaw/logs/gateway.log` — look for `MemOS Memory Viewer`
+
+**Forgot password?** Click "Forgot password?" on the login page and use the reset token:
 
 ```bash
-# 必须用 "password reset token:" 才能匹配到带 token 的那一行（不要用 "reset token"）
-grep "password reset token:" /tmp/openclaw/openclaw-*.log ~/.openclaw/logs/gateway.log 2>/dev/null | tail -1
+grep "password reset token:" ~/.openclaw/logs/gateway.log 2>/dev/null | tail -1
 ```
-输出可能是纯文本一行，或一段 JSON；从中复制 `password reset token:` 后面的 32 位 hex 即可。
+
+Copy the 32-character hex string after `password reset token:`.
 
 ## Advanced Configuration
 
@@ -262,41 +378,117 @@ All optional — shown with defaults:
       "recencyHalfLifeDays": 14   // Time decay half-life
     },
     "dedup": {
-      "similarityThreshold": 0.93 // Cosine similarity for dedup
+      "similarityThreshold": 0.75,  // Cosine similarity for smart-dedup candidates (Top-5)
+      "enableSmartMerge": true,     // LLM judge: DUPLICATE / UPDATE / NEW
+      "maxCandidates": 5            // Max similar chunks to send to LLM
+    },
+    "skillEvolution": {
+      "enabled": true,            // Enable skill evolution
+      "autoEvaluate": true,       // Auto-evaluate tasks for skill generation
+      "minChunksForEval": 6,      // Min chunks for a task to be evaluated
+      "minConfidence": 0.7,       // Min LLM confidence to create/upgrade skill
+      "autoInstall": false        // Auto-install generated skills
     },
     "viewerPort": 18799           // Memory Viewer port
   }
 }
 ```
 
-## How It Works
+## Reinstall / Upgrade
 
-**Write path** (automatic on every agent turn):
+If you see **"plugin already exists"** or **"plugin not found"**:
 
+**Option A — Clean reinstall via OpenClaw CLI:**
+```bash
+rm -rf ~/.openclaw/extensions/memos-local
+openclaw plugins install @memtensor/memos-local-openclaw-plugin
+cd ~/.openclaw/extensions/memos-local && npm install --omit=dev
+openclaw gateway stop && openclaw gateway start
 ```
-Conversation → Capture (filter roles) → Semantic Chunk → LLM Summarize
-→ Embed → Dedup Check → Store (SQLite + FTS5 + Vector)
+
+**Option B — Manual install (when config already references memos-local):**
+```bash
+rm -rf ~/.openclaw/extensions/memos-local
+cd /tmp
+npm pack @memtensor/memos-local-openclaw-plugin
+tar -xzf memtensor-memos-local-openclaw-plugin-*.tgz
+mv package ~/.openclaw/extensions/memos-local
+cd ~/.openclaw/extensions/memos-local && npm install --omit=dev
+openclaw gateway stop && openclaw gateway start
 ```
 
-**Read path** (when agent calls `memory_search`):
+**Plugin shows as "error" in `openclaw plugins list`?** (e.g. `Cannot find module '@sinclair/typebox'`)
 
-```
-Query → FTS5 + Vector dual recall → RRF Fusion → MMR Rerank
-→ Recency Decay → Score Filter → Top-K Results
+```bash
+cd ~/.openclaw/extensions/memos-local && npm install --omit=dev
 ```
 
-See the [full documentation](www/docs/index.html) in the repo (or open `www/docs/index.html` locally) for detailed architecture and algorithm explanations.
+Then restart the gateway.
 
-## Data Location
+## Troubleshooting
+
+### 常见问题排查
 
-Whether you install from npm or from source, the plugin stores data under your OpenClaw state directory:
+1. **确认报错内容** — 记下完整报错，例如：`plugin not found`、`Cannot find module 'xxx'`、`Invalid config` 等。
+
+2. **看插件状态**
+   ```bash
+   openclaw plugins list
+   ```
+   - Status 为 **error** → 记下错误信息
+   - 列表中没有 MemOS Local → 未安装或未放到 `~/.openclaw/extensions/memos-local`
+
+3. **看网关日志**
+   ```bash
+   tail -50 ~/.openclaw/logs/gateway.log
+   ```
+   搜索 `memos-local`、`failed to load`、`Error`、`Cannot find module`。
+
+4. **检查环境**
+   - Node 版本：`node -v`（需要 **>= 18**）
+   - 插件目录存在：`ls ~/.openclaw/extensions/memos-local/package.json`
+   - 依赖已安装：`ls ~/.openclaw/extensions/memos-local/node_modules/@sinclair/typebox`
+     若不存在：`cd ~/.openclaw/extensions/memos-local && npm install --omit=dev`
+
+5. **检查配置** — 打开 `~/.openclaw/openclaw.json`，确认：
+   - `agents.defaults.memorySearch.enabled` = `false`（关闭内置记忆）
+   - `plugins.slots.memory` = `"memos-local"`
+   - `plugins.entries.memos-local.enabled` = `true`
+
+6. **记忆和 OpenClaw 内置记忆冲突** — 如果看到 agent 同时调用了内置的 memory 搜索和插件的 `memory_search`，说明 `agents.defaults.memorySearch.enabled` 没有设为 `false`。
+
+7. **技能不生成** — 检查：
+   - `skillEvolution.enabled` 是否为 `true`
+   - 任务是否有足够内容（默认需要 ≥ 6 chunks）
+   - 查看日志中 `SkillEvolver` 相关输出
+
+## Data Location
 
 | File | Path |
 |---|---|
 | Database | `~/.openclaw/memos-local/memos.db` |
-| Viewer auth | `~/.openclaw/viewer-auth.json` |
+| Viewer auth | `~/.openclaw/memos-local/viewer-auth.json` |
 | Gateway log | `~/.openclaw/logs/gateway.log` |
-| Plugin code (npm install) | `~/.openclaw/extensions/` (managed by OpenClaw) |
+| Plugin code | `~/.openclaw/extensions/memos-local/` |
+| Memory-guide skill | `~/.openclaw/workspace/skills/memos-memory-guide/SKILL.md` (and `~/.openclaw/skills/memos-memory-guide/`) |
+| Generated skills | `~/.openclaw/memos-local/skills-store/<skill-name>/` |
+| Installed skills | `~/.openclaw/workspace/skills/<skill-name>/` |
+
+## Testing
+
+Run the test suite:
+
+```bash
+cd MemOS/apps/memos-local-openclaw
+npm test
+```
+
+Test coverage includes:
+- **Policy tests** — Verifies retrieval strategy, search filtering, evidence extraction, instruction stripping
+- **Recall tests** — RRF fusion, recency decay correctness
+- **Capture tests** — Message filtering, evidence block stripping, self-tool exclusion
+- **Storage tests** — SQLite CRUD, FTS5, vector storage, content hash dedup
+- **Task processor tests** — Task boundary detection, skip logic, summary generation
 
 ## License
 

package/dist/capture/index.d.ts

@@ -1,16 +1,14 @@
 import type { ConversationMessage, Logger } from "../types";
 /**
- * Filter and extract writable messages from a conversation turn.
+ * Extract writable messages from a conversation turn.
  *
- * - Keep user, assistant, and tool messages
- * - Skip system prompts
- * - Skip tool results from our own memory tools (prevents memory loop)
- * - Truncate long tool results to avoid storage bloat
- * - Strip injected evidence blocks wrapped in [STORED_MEMORY]...[/STORED_MEMORY]
+ * Stores the user's actual text — strips only OpenClaw's injected metadata
+ * prefixes (Sender info, conversation context, etc.) which are not user content.
+ * Only skips: system prompts and our own memory tool results (prevents loop).
  */
 export declare function captureMessages(messages: Array<{
     role: string;
     content: string;
     toolName?: string;
-}>, sessionKey: string, turnId: string, evidenceTag: string, log: Logger): ConversationMessage[];
+}>, sessionKey: string, turnId: string, _evidenceTag: string, log: Logger): ConversationMessage[];
 //# sourceMappingURL=index.d.ts.map

package/dist/capture/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capture/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAQ,MAAM,EAAE,MAAM,UAAU,CAAC;AAYlE;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EACrE,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GACV,mBAAmB,EAAE,CA+CvB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capture/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAQ,MAAM,EAAE,MAAM,UAAU,CAAC;AA0BlE;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EACrE,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,MAAM,GACV,mBAAmB,EAAE,CAgCvB"}