+Compared to Built-in
+
+| Feature | Built-in `memory-lancedb` | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| Vector search | Yes | Yes |
+| BM25 full-text search | - | Yes |
+| Hybrid fusion (Vector + BM25) | - | Yes |
+| Cross-encoder rerank (multi-provider) | - | Yes |
+| Recency boost & time decay | - | Yes |
+| Length normalization | - | Yes |
+| MMR diversity | - | Yes |
+| Multi-scope isolation | - | Yes |
+| Noise filtering | - | Yes |
+| Adaptive retrieval | - | Yes |
+| Management CLI | - | Yes |
+| Session memory | - | Yes |
+| Task-aware embeddings | - | Yes |
+| **LLM Smart Extraction (6-category)** | - | Yes (v1.1.0) |
+| **Weibull Decay + Tier Promotion** | - | Yes (v1.1.0) |
+| Any OpenAI-compatible embedding | Limited | Yes |
+
+
---
-## ⚙️ Configuration
+## Configuration
Compared to Built-in memory-lancedb (click to expand)
+
+| Feature | Built-in `memory-lancedb` | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| Vector search | Yes | Yes |
+| BM25 full-text search | - | Yes |
+| Hybrid fusion (Vector + BM25) | - | Yes |
+| Cross-encoder rerank (multi-provider) | - | Yes |
+| Recency boost & time decay | - | Yes |
+| Length normalization | - | Yes |
+| MMR diversity | - | Yes |
+| Multi-scope isolation | - | Yes |
+| Noise filtering | - | Yes |
+| Adaptive retrieval | - | Yes |
+| Management CLI | - | Yes |
+| Session memory | - | Yes |
+| Task-aware embeddings | - | Yes |
+| **LLM Smart Extraction (6-category)** | - | Yes (v1.1.0) |
+| **Weibull Decay + Tier Promotion** | - | Yes (v1.1.0) |
+| Any OpenAI-compatible embedding | Limited | Yes |
+
+Full Configuration Example
@@ -410,26 +471,20 @@ Query → BM25 FTS ─────┘ } ``` -OpenClaw-specific defaults: - -- `autoCapture`: enabled by default -- `autoRecall`: disabled by default in the plugin schema, but for most new users this README recommends turning it on -- `embedding.chunking`: enabled by default -- `sessionMemory.enabled`: disabled by default; set to `true` explicitly if you want the `/new` session-summary hook -Embedding Providers
-This plugin works with **any OpenAI-compatible embedding API**: +Works with **any OpenAI-compatible embedding API**: | Provider | Model | Base URL | Dimensions | | --- | --- | --- | --- | | **Jina** (recommended) | `jina-embeddings-v5-text-small` | `https://api.jina.ai/v1` | 1024 | | **OpenAI** | `text-embedding-3-small` | `https://api.openai.com/v1` | 1536 | +| **Voyage** | `voyage-4-lite` / `voyage-4` | `https://api.voyageai.com/v1` | 1024 / 1024 | | **Google Gemini** | `gemini-embedding-001` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 | -| **Ollama** (local) | `nomic-embed-text` | `http://localhost:11434/v1` | _provider-specific_ | +| **Ollama** (local) | `nomic-embed-text` | `http://localhost:11434/v1` | provider-specific |
-
-
-SiliconFlow config example
- -```json -{ - "retrieval": { - "rerank": "cross-encoder", - "rerankProvider": "siliconflow", - "rerankEndpoint": "https://api.siliconflow.com/v1/rerank", - "rerankApiKey": "sk-xxx", - "rerankModel": "BAAI/bge-reranker-v2-m3" - } -} -``` - -
-
-
-Voyage config example
- -```json -{ - "retrieval": { - "rerank": "cross-encoder", - "rerankProvider": "voyage", - "rerankEndpoint": "https://api.voyageai.com/v1/rerank", - "rerankApiKey": "${VOYAGE_API_KEY}", - "rerankModel": "rerank-2.5" - } -} -``` - -
-
+| Provider | `rerankProvider` | Example Model |
+| --- | --- | --- |
+| **Jina** (default) | `jina` | `jina-reranker-v3` |
+| **SiliconFlow** (free tier available) | `siliconflow` | `BAAI/bge-reranker-v2-m3` |
+| **Voyage AI** | `voyage` | `rerank-2.5` |
+| **Pinecone** | `pinecone` | `bge-reranker-v2-m3` |
-Notes:
-- `voyage` sends `{ model, query, documents }` without `top_n`. Responses are parsed from `data[].relevance_score`.
+Any Jina-compatible rerank endpoint also works — set `rerankProvider: "jina"` and point `rerankEndpoint` to your service (e.g., Hugging Face TEI, DashScope `qwen3-rerank`).
@@ -509,259 +512,98 @@ When `smartExtraction` is enabled (default: `true`), the plugin uses an LLM to i
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `smartExtraction` | boolean | `true` | Enable/disable LLM-powered 6-category extraction |
+| `llm.auth` | string | `api-key` | `api-key` uses `llm.apiKey` / `embedding.apiKey`; `oauth` uses a plugin-scoped OAuth token file by default |
| `llm.apiKey` | string | *(falls back to `embedding.apiKey`)* | API key for the LLM provider |
| `llm.model` | string | `openai/gpt-oss-120b` | LLM model name |
| `llm.baseURL` | string | *(falls back to `embedding.baseURL`)* | LLM API endpoint |
+| `llm.oauthProvider` | string | `openai-codex` | OAuth provider id used when `llm.auth` is `oauth` |
+| `llm.oauthPath` | string | `~/.openclaw/.memory-lancedb-pro/oauth.json` | OAuth token file used when `llm.auth` is `oauth` |
+| `llm.timeoutMs` | number | `30000` | LLM request timeout in milliseconds |
| `extractMinMessages` | number | `2` | Minimum messages before extraction triggers |
| `extractMaxChars` | number | `8000` | Maximum characters sent to the LLM |
-Minimal config (reuses embedding API key):
-```json
-{
- "embedding": { "apiKey": "${OPENAI_API_KEY}", "model": "text-embedding-3-small" },
- "smartExtraction": true
-}
-```
-Full config (separate LLM endpoint):
+OAuth `llm` config (use existing Codex / ChatGPT login cache for LLM calls):
```json
{
- "embedding": { "apiKey": "${OPENAI_API_KEY}", "model": "text-embedding-3-small" },
- "smartExtraction": true,
- "llm": { "apiKey": "${OPENAI_API_KEY}", "model": "gpt-4o-mini", "baseURL": "https://api.openai.com/v1" },
- "extractMinMessages": 2,
- "extractMaxChars": 8000
+ "llm": {
+ "auth": "oauth",
+ "oauthProvider": "openai-codex",
+ "model": "gpt-5.4",
+ "oauthPath": "${HOME}/.openclaw/.memory-lancedb-pro/oauth.json",
+ "timeoutMs": 30000
+ }
}
```
-Disable: `{ "smartExtraction": false }`
+Notes for `llm.auth: "oauth"`:
+
+- `llm.oauthProvider` is currently `openai-codex`.
+- OAuth tokens default to `~/.openclaw/.memory-lancedb-pro/oauth.json`.
+- You can set `llm.oauthPath` if you want to store that file somewhere else.
+- `auth login` snapshots the previous api-key `llm` config next to the OAuth file, and `auth logout` restores that snapshot when available.
+- Switching from `api-key` to `oauth` does not automatically carry over `llm.baseURL`. Set it manually in OAuth mode only when you intentionally want a custom ChatGPT/Codex-compatible backend.
Pinecone config example
- -```json -{ - "retrieval": { - "rerank": "cross-encoder", - "rerankProvider": "pinecone", - "rerankEndpoint": "https://api.pinecone.io/rerank", - "rerankApiKey": "pcsk_xxx", - "rerankModel": "bge-reranker-v2-m3" - } -} -``` - -Lifecycle Configuration (Decay + Tier)
-These settings control freshness ranking and automatic tier transitions. - -| Field | Type | Default | Description | -|-------|------|---------|-------------| -| `decay.recencyHalfLifeDays` | number | `30` | Base half-life for Weibull recency decay | -| `decay.frequencyWeight` | number | `0.3` | Weight of access frequency in composite score | -| `decay.intrinsicWeight` | number | `0.3` | Weight of `importance × confidence` | -| `decay.betaCore` | number | `0.8` | Weibull beta for `core` memories | -| `decay.betaWorking` | number | `1.0` | Weibull beta for `working` memories | -| `decay.betaPeripheral` | number | `1.3` | Weibull beta for `peripheral` memories | -| `tier.coreAccessThreshold` | number | `10` | Min recall count before promoting to `core` | -| `tier.coreCompositeThreshold` | number | `0.7` | Min lifecycle score before promoting to `core` | -| `tier.peripheralCompositeThreshold` | number | `0.15` | Below this score, `working` may demote | -| `tier.peripheralAgeDays` | number | `60` | Age threshold for demoting stale memories | - -```json -{ - "decay": { "recencyHalfLifeDays": 21, "betaCore": 0.7, "betaPeripheral": 1.5 }, - "tier": { "coreAccessThreshold": 8, "peripheralAgeDays": 45 } -} -``` +| Field | Default | Description | +|-------|---------|-------------| +| `decay.recencyHalfLifeDays` | `30` | Base half-life for Weibull recency decay | +| `decay.frequencyWeight` | `0.3` | Weight of access frequency in composite score | +| `decay.intrinsicWeight` | `0.3` | Weight of `importance × confidence` | +| `decay.betaCore` | `0.8` | Weibull beta for `core` memories | +| `decay.betaWorking` | `1.0` | Weibull beta for `working` memories | +| `decay.betaPeripheral` | `1.3` | Weibull beta for `peripheral` memories | +| `tier.coreAccessThreshold` | `10` | Min recall count before promoting to `core` | +| `tier.peripheralAgeDays` | `60` | Age threshold for demoting stale memories |
-
---
-## 📥 Installation
-
-Access Reinforcement (1.0.26)
+Access Reinforcement
Frequently recalled memories decay more slowly (spaced-repetition style). Config keys (under `retrieval`): -- `reinforcementFactor` (0–2, default: `0.5`) — set `0` to disable -- `maxHalfLifeMultiplier` (1–10, default: `3`) — hard cap on effective half-life - -Note: reinforcement is whitelisted to `source: "manual"` only, to avoid auto-recall accidentally strengthening noise. +- `reinforcementFactor` (0-2, default: `0.5`) — set `0` to disable +- `maxHalfLifeMultiplier` (1-10, default: `3`) — hard cap on effective half-life
-
-
-Path A — New to OpenClaw (recommended)
- -1. Clone into your workspace: - -```bash -cd /path/to/your/openclaw/workspace -git clone https://github.com/CortexReach/memory-lancedb-pro.git plugins/memory-lancedb-pro -cd plugins/memory-lancedb-pro -npm install -``` - -2. Add to `openclaw.json` (relative path): - -```json -{ - "plugins": { - "load": { "paths": ["plugins/memory-lancedb-pro"] }, - "entries": { - "memory-lancedb-pro": { - "enabled": true, - "config": { - "embedding": { - "apiKey": "${JINA_API_KEY}", - "model": "jina-embeddings-v5-text-small", - "baseURL": "https://api.jina.ai/v1", - "dimensions": 1024, - "taskQuery": "retrieval.query", - "taskPassage": "retrieval.passage", - "normalized": true - } - } - } - }, - "slots": { "memory": "memory-lancedb-pro" } - } -} -``` - -3. Restart and verify: - -```bash -openclaw config validate -openclaw gateway restart -openclaw plugins info memory-lancedb-pro -openclaw hooks list --json -openclaw memory-pro stats -``` - -4. Smoke test: store one memory → search by keyword → search by natural language. - -
-
-
-Path B — Already using OpenClaw, adding this plugin
- -1. Keep your existing agents, channels, and models unchanged -2. Add the plugin with an **absolute** `plugins.load.paths` entry: - -```json -{ "plugins": { "load": { "paths": ["/absolute/path/to/memory-lancedb-pro"] } } } -``` - -3. Bind the memory slot: `plugins.slots.memory = "memory-lancedb-pro"` -4. Verify: `openclaw plugins info memory-lancedb-pro && openclaw memory-pro stats` - -
-
-
-Path C — Upgrading from older memory-lancedb-pro (pre-v1.1.0)
- -Command boundaries: -- `upgrade` — for **older `memory-lancedb-pro` data** -- `migrate` — only from built-in **`memory-lancedb`** -- `reembed` — only when rebuilding embeddings after model change - -Safe upgrade sequence: - -```bash -# 1) Backup -openclaw memory-pro export --scope global --output memories-backup.json - -# 2) Dry run -openclaw memory-pro upgrade --dry-run - -# 3) Run upgrade -openclaw memory-pro upgrade - -# 4) Verify -openclaw memory-pro stats -openclaw memory-pro search "your known keyword" --scope global --limit 5 -``` - -See `CHANGELOG-v1.1.0.md` for behavior changes and upgrade rationale. - -
-
-
-Post-install verification checklist
- -```bash -openclaw config validate -openclaw gateway restart -openclaw plugins info memory-lancedb-pro -openclaw hooks list --json -openclaw memory-pro stats -openclaw memory-pro list --scope global --limit 5 -``` - -Then validate: -- ✅ one exact-id search hit -- ✅ one natural-language search hit -- ✅ one `memory_store` → `memory_recall` round trip -- ✅ if session memory is enabled, one real `/new` test - -
-
-
-AI-safe install notes (anti-hallucination)
- -If you are following this README with an AI assistant, **do not assume defaults**. Always run: - -```bash -openclaw config get agents.defaults.workspace -openclaw config get plugins.load.paths -openclaw config get plugins.slots.memory -openclaw config get plugins.entries.memory-lancedb-pro -``` - -Tips: -- Prefer **absolute paths** in `plugins.load.paths` -- If you use `${JINA_API_KEY}` in config, ensure the **Gateway service process** has that env var -- After changing plugin config, run `openclaw gateway restart` - -
-
-
-Jina API keys (embedding + rerank)
- -- **Embedding**: set `embedding.apiKey` to your Jina key (use env var `${JINA_API_KEY}` recommended) -- **Rerank** (when `rerankProvider: "jina"`): you can use the **same** Jina key for `retrieval.rerankApiKey` -- Different rerank provider? Use that provider's key for `retrieval.rerankApiKey` - -Key storage: avoid committing secrets into git. When using `${...}` env vars, ensure the Gateway service process has them. - -
-/plugins/` (Path A).
-
-
-
----
-
-## 🔧 CLI Commands
+## CLI Commands
```bash
openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
openclaw memory-pro search "query" [--scope global] [--limit 10] [--json]
openclaw memory-pro stats [--scope global] [--json]
+openclaw memory-pro auth login [--provider openai-codex] [--model gpt-5.4] [--oauth-path /abs/path/oauth.json]
+openclaw memory-pro auth status
+openclaw memory-pro auth logout
openclaw memory-pro delete What is the "OpenClaw workspace"?
- -The **agent workspace** is the agent's working directory (default: `~/.openclaw/workspace`). Relative paths are resolved against the workspace. - -> Note: OpenClaw config typically lives at `~/.openclaw/openclaw.json` (separate from the workspace). - -**Common mistake:** cloning the plugin elsewhere while keeping a relative path in config. Use an absolute path (Path B) or clone into `If injected memories show up in replies
@@ -779,40 +621,26 @@ Sometimes the model may echo the injected `
-
Session Memory
+Auto-recall timeout tuning
-- 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) +Auto-recall has a configurable timeout (default 5s) to prevent stalling agent startup. If you're behind a proxy or using a high-latency embedding API, increase it: -See [docs/openclaw-integration-playbook.md](docs/openclaw-integration-playbook.md) for deployment modes and `/new` verification. +```json +{ "plugins": { "entries": { "memory-lancedb-pro": { "config": { "autoRecallTimeoutMs": 8000 } } } } } +``` + +If auto-recall consistently times out, check your embedding API latency first. The timeout only affects the automatic injection path — manual `memory_recall` tool calls are not affected.
-/sessions/*.jsonl`
-
-**Recommended (2026-02+)**: non-blocking `/new` pipeline:
-- Trigger: `command:new` → enqueue tiny JSON task (no LLM calls in hook)
-- Worker: systemd service runs Gemini Map-Reduce on session JSONL
-- Store: writes 0–20 high-signal lessons via `openclaw memory-pro import`
-- Keywords: each memory includes `Keywords (zh)` with entity keywords copied verbatim from transcript
-
-Example files: `examples/new-session-distill/`
-
-**Legacy option**: hourly distiller cron using `scripts/jsonl_distill.py`:
-- Incremental reads (byte-offset cursor), filters noise, uses a dedicated agent to distill
-- Stores via `memory_store` into the right scope
-- Safe: never modifies session logs
+` → `openclaw agents delete memory-distiller` → `rm -rf ~/.openclaw/state/jsonl-distill/`
+See [docs/openclaw-integration-playbook.md](docs/openclaw-integration-playbook.md) for deployment modes and `/new` verification.
@@ -834,35 +662,32 @@ When the user sends `/remember JSONL Session Distillation (auto-memories from chat logs)
- -OpenClaw persists full session transcripts as JSONL: `~/.openclaw/agents/Session Memory
-Setup: -1. Create agent: `openclaw agents add memory-distiller --non-interactive --workspace ~/.openclaw/workspace-memory-distiller --model openai-codex/gpt-5.2` -2. Init cursor: `python3 "$PLUGIN_DIR/scripts/jsonl_distill.py" init` -3. Add cron: see full command in the [legacy distillation docs](docs/openclaw-integration-playbook.md) +- 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) -Rollback: `openclaw cron disable
-
@@ -877,14 +702,16 @@ LanceDB table `memories`:
| `id` | string (UUID) | Primary key |
| `text` | string | Memory text (FTS indexed) |
| `vector` | float[] | Embedding vector |
-| `category` | string | `preference` / `fact` / `decision` / `entity` / `other` |
+| `category` | string | Storage category: `preference` / `fact` / `decision` / `entity` / `reflection` / `other` |
| `scope` | string | Scope identifier (e.g., `global`, `agent:main`) |
-| `importance` | float | Importance score 0–1 |
+| `importance` | float | Importance score 0-1 |
| `timestamp` | int64 | Creation timestamp (ms) |
| `metadata` | string (JSON) | Extended metadata |
Common `metadata` keys in v1.1.0: `l0_abstract`, `l1_overview`, `l2_content`, `memory_category`, `tier`, `access_count`, `confidence`, `last_accessed_at`
+> **Note on categories:** The top-level `category` field uses 6 storage categories. The 6-category semantic labels from Smart Extraction (`profile` / `preferences` / `entities` / `events` / `cases` / `patterns`) are stored in `metadata.memory_category`.
+
Iron Rules for AI Agents (铁律)
+Iron Rules for AI Agents
> Copy the block below into your `AGENTS.md` so your agent enforces these rules automatically. ```markdown -## Rule 1 — 双层记忆存储（铁律） +## Rule 1 — Dual-layer memory storage Every pitfall/lesson learned → IMMEDIATELY store TWO memories: -- **Technical layer**: Pitfall: [symptom]. Cause: [root cause]. Fix: [solution]. Prevention: [how to avoid] - (category: fact, importance ≥ 0.8) -- **Principle layer**: Decision principle ([tag]): [behavioral rule]. Trigger: [when]. Action: [what to do] - (category: decision, importance ≥ 0.85) -- After each store, immediately `memory_recall` to verify retrieval. +- Technical layer: Pitfall: [symptom]. Cause: [root cause]. Fix: [solution]. Prevention: [how to avoid] + (category: fact, importance >= 0.8) +- Principle layer: Decision principle ([tag]): [behavioral rule]. Trigger: [when]. Action: [what to do] + (category: decision, importance >= 0.85) -## Rule 2 — LanceDB 卫生 +## Rule 2 — LanceDB hygiene Entries must be short and atomic (< 500 chars). No raw conversation summaries or duplicates. ## Rule 3 — Recall before retry -On ANY tool failure, ALWAYS `memory_recall` with relevant keywords BEFORE retrying. +On ANY tool failure, ALWAYS memory_recall with relevant keywords BEFORE retrying. -## Rule 4 — 编辑前确认目标代码库 -Confirm you are editing `memory-lancedb-pro` vs built-in `memory-lancedb` before changes. +## Rule 4 — Confirm target codebase +Confirm you are editing memory-lancedb-pro vs built-in memory-lancedb before changes. -## Rule 5 — 插件代码变更必须清 jiti 缓存 -After modifying `.ts` files under `plugins/`, MUST run `rm -rf /tmp/jiti/` BEFORE `openclaw gateway restart`. +## Rule 5 — Clear jiti cache after plugin code changes +After modifying .ts files under plugins/, MUST run rm -rf /tmp/jiti/ BEFORE openclaw gateway restart. ```
@@ -898,31 +725,106 @@ On LanceDB 0.26+, some numeric columns may be returned as `BigInt`. Upgrade to *
---
-## 🧪 Beta: Smart Memory v1.1.0
+## Hook Adaptation (OpenClaw 2026.3+)
-> Status: Beta — available via `npm i memory-lancedb-pro@beta`. Stable users on `latest` are not affected.
+Starting with v1.1.0-beta.9, the plugin's lifecycle hooks have been updated for compatibility with the refactored OpenClaw plugin system.
-| Feature | Description |
-|---------|-------------|
-| **Smart Extraction** | LLM-powered 6-category extraction with L0/L1/L2 metadata. Falls back to regex when disabled. |
-| **Lifecycle Scoring** | Weibull decay integrated into retrieval — high-frequency and high-importance memories rank higher. |
-| **Tier Management** | Three-tier system (Core → Working → Peripheral) with automatic promotion/demotion. |
+### What changed
-Feedback: [GitHub Issues](https://github.com/CortexReach/memory-lancedb-pro/issues) · Revert: `npm i memory-lancedb-pro@latest`
+| Hook | Before | After | Why |
+|------|--------|-------|-----|
+| Auto-recall | `before_agent_start` | `before_prompt_build` (priority 10) | `before_agent_start` is deprecated; `before_prompt_build` is the recommended hook for prompt mutation |
+| Reflection invariants | `before_agent_start` | `before_prompt_build` (priority 12) | Same reason as above |
+| Reflection derived focus | `before_prompt_build` | `before_prompt_build` (priority 15) | Unchanged event, added explicit priority |
+| All other lifecycle hooks | unchanged | unchanged | `agent_end`, `after_tool_call`, `session_end`, `message_received`, `before_message_write` |
+
+### Hook API distinction
+
+OpenClaw exposes two hook registration methods. They write to **different registries**:
+
+| Method | Registry | Dispatch | Use for |
+|--------|----------|----------|---------|
+| `api.on(event, handler, opts)` | `registry.typedHooks` | Dispatched by the lifecycle hook runner | Lifecycle events: `before_prompt_build`, `agent_end`, `after_tool_call`, `session_end`, `message_received`, `before_message_write` |
+| `api.registerHook(event, handler, opts)` | `registry.hooks` | Dispatched by the internal hook system | Command/bootstrap events: `command:new`, `command:reset`, `agent:bootstrap` |
+
+Using the wrong method causes hooks to register silently without firing. This plugin uses `api.on()` for all lifecycle hooks and `api.registerHook()` for command hooks.
+
+### Verifying hooks after install
+
+```bash
+openclaw plugins info memory-lancedb-pro
+```
+
+You should see:
+
+```
+Legacy before_agent_start: no
+
+Typed hooks:
+ agent_end
+ before_message_write
+ before_prompt_build (priority 10)
+ message_received
+
+Custom hooks:
+ memory-lancedb-pro-session-memory: command:new
+```
+
+If `Legacy before_agent_start: yes` appears, you are running an older version of the plugin.
+
+### Migration from older versions
+
+If you are upgrading from v1.1.0-beta.8 or earlier:
+
+1. Replace the plugin files (copy or `openclaw plugins install`)
+2. Clear the jiti cache: `rm -rf /tmp/jiti/`
+3. Restart the gateway: `openclaw gateway restart`
+4. Verify: `openclaw plugins info memory-lancedb-pro` should show `Legacy before_agent_start: no`
+
+No config changes or data migration required. All existing memories, scopes, and settings are preserved.
+
+### OpenClaw version requirements
+
+- **Minimum:** OpenClaw 2026.3.22
+- **Recommended:** OpenClaw latest (2026.3.23+)
+
+This version uses `before_prompt_build` hooks (replacing the deprecated `before_agent_start`), which requires OpenClaw 2026.3.22 or later. Running `openclaw doctor --fix` after upgrading will automatically migrate plugin config (e.g. `minimax-portal-auth` → `minimax`, Brave search as a standalone plugin).
+
+To upgrade OpenClaw:
+
+```bash
+npm update -g openclaw
+openclaw --version # verify >= 2026.3.22
+openclaw doctor --fix # resolve any stale config after upgrade
+```
---
-## 📖 Documentation
+## Documentation
| Document | Description |
| --- | --- |
-| [OpenClaw Integration Playbook](docs/openclaw-integration-playbook.md) | Deployment modes, `/new` verification, regression matrix |
+| [OpenClaw Integration Playbook](docs/openclaw-integration-playbook.md) | Deployment modes, verification, regression matrix |
| [Memory Architecture Analysis](docs/memory_architecture_analysis.md) | Full architecture deep-dive |
| [CHANGELOG v1.1.0](docs/CHANGELOG-v1.1.0.md) | v1.1.0 behavior changes and upgrade rationale |
| [Long-Context Chunking](docs/long-context-chunking.md) | Chunking strategy for long documents |
---
+## Beta: Smart Memory v1.1.0
+
+> Status: Beta — available via `npm i memory-lancedb-pro@beta`. Stable users on `latest` are not affected.
+
+| Feature | Description |
+|---------|-------------|
+| **Smart Extraction** | LLM-powered 6-category extraction with L0/L1/L2 metadata. Falls back to regex when disabled. |
+| **Lifecycle Scoring** | Weibull decay integrated into retrieval — high-frequency and high-importance memories rank higher. |
+| **Tier Management** | Three-tier system (Core → Working → Peripheral) with automatic promotion/demotion. |
+
+Feedback: [GitHub Issues](https://github.com/CortexReach/memory-lancedb-pro/issues) · Revert: `npm i memory-lancedb-pro@latest`
+
+---
+
## Dependencies
| Package | Purpose |
@@ -933,7 +835,7 @@ Feedback: [GitHub Issues](https://github.com/CortexReach/memory-lancedb-pro/issu
---
-## 🤝 Contributors
+## Contributors
+**OpenClaw 安装：**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill
+```
---
-## 🏗️ 架构概览
+## 视频教程
+
+> 完整演示：安装、配置、混合检索内部原理。
+
+[](https://youtu.be/MtukF1C8epQ)
+**https://youtu.be/MtukF1C8epQ**
+
+[](https://www.bilibili.com/video/BV1zUf2BGEgn/)
+**https://www.bilibili.com/video/BV1zUf2BGEgn/**
+
+---
+
+## 架构
```
┌─────────────────────────────────────────────────────────┐
│ index.ts (入口) │
-│ 插件注册 · 配置解析 · 生命周期钩子 · 自动捕获/回忆 │
+│ 插件注册 · 配置解析 · 生命周期钩子 │
└────────┬──────────┬──────────┬──────────┬───────────────┘
│ │ │ │
┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
@@ -237,115 +272,130 @@ openclaw logs --follow --plain | rg "memory-lancedb-pro"
└────────────────┘
┌─────────────┐ ┌──────────┐
│ tools.ts │ │ cli.ts │
- │ (Agent API) │ │ (CLI) │
+ │ (智能体 API)│ │ (CLI) │
└─────────────┘ └──────────┘
```
-> 📖 完整架构深度解析请看 [docs/memory_architecture_analysis.md](docs/memory_architecture_analysis.md)
+> 完整架构解析见 [docs/memory_architecture_analysis.md](docs/memory_architecture_analysis.md)。
-`、`custom:`、`project:`、`user:` |
-| `src/tools.ts` | Agent 工具：`memory_recall`、`memory_store`、`memory_forget`、`memory_update` + 管理工具 |
-| `src/noise-filter.ts` | 过滤 Agent 拒绝回复、Meta 问题、寒暄等低质量记忆 |
-| `src/adaptive-retrieval.ts` | 判断 query 是否需要触发记忆检索 |
+| `index.ts` | 插件入口，注册 OpenClaw 插件 API、解析配置、挂载生命周期钩子 |
+| `openclaw.plugin.json` | 插件元数据 + 完整 JSON Schema 配置声明 |
+| `cli.ts` | CLI 命令：`memory-pro list/search/stats/delete/delete-bulk/export/import/reembed/upgrade/migrate` |
+| `src/store.ts` | LanceDB 存储层：建表 / 全文索引 / 向量搜索 / BM25 搜索 / CRUD |
+| `src/embedder.ts` | Embedding 抽象层，兼容任意 OpenAI 兼容 API |
+| `src/retriever.ts` | 混合检索引擎：向量 + BM25 → 混合融合 → 重排序 → 生命周期衰减 → 过滤 |
+| `src/scopes.ts` | 多作用域访问控制 |
+| `src/tools.ts` | 智能体工具定义：`memory_recall`、`memory_store`、`memory_forget`、`memory_update` + 管理工具 |
+| `src/noise-filter.ts` | 过滤智能体拒绝回复、元问题、打招呼等低质量内容 |
+| `src/adaptive-retrieval.ts` | 判断查询是否需要记忆检索 |
| `src/migrate.ts` | 从内置 `memory-lancedb` 迁移到 Pro |
-| `src/smart-extractor.ts` | **（v1.1.0）** LLM 6 类别提取管线，含 L0/L1/L2 分层存储和两阶段去重 |
-| `src/memory-categories.ts` | **（v1.1.0）** 6 类别分类系统：profile、preferences、entities、events、cases、patterns |
-| `src/decay-engine.ts` | **（v1.1.0）** Weibull 拉伸指数衰减模型 |
-| `src/tier-manager.ts` | **（v1.1.0）** 三层晋升/降级系统：Peripheral ⟷ Working ⟷ Core |
-| `src/memory-upgrader.ts` | **（v1.1.0）** 旧记忆批量升级为新智能格式 |
-| `src/llm-client.ts` | **（v1.1.0）** LLM 客户端，结构化 JSON 输出 |
-| `src/extraction-prompts.ts` | **（v1.1.0）** 记忆提取、去重、合并的 LLM 提示模板 |
-| `src/smart-metadata.ts` | **（v1.1.0）** Metadata 归一化，统一 L0/L1/L2、tier、confidence、access 计数 |
+| `src/smart-extractor.ts` | LLM 驱动的 6 类提取，支持 L0/L1/L2 分层存储和两阶段去重 |
+| `src/decay-engine.ts` | Weibull 拉伸指数衰减模型 |
+| `src/tier-manager.ts` | 三级晋升/降级：外围 ↔ 工作 ↔ 核心 |
---
-## 📦 核心特性
+## 核心功能
### 混合检索
```
-Query → embedQuery() ─┐
- ├─→ RRF 融合 → Rerank → 生命周期衰减加权 → 长度归一化 → 过滤
-Query → BM25 FTS ─────┘
+查询 → embedQuery() ─┐
+ ├─→ 混合融合 → 重排序 → 生命周期衰减加权 → 长度归一化 → 过滤
+查询 → BM25 全文 ─────┘
```
-- **向量搜索** — 语义相似度搜索（cosine distance via LanceDB ANN）
-- **BM25 全文搜索** — 关键词精确匹配（LanceDB FTS 索引）
-- **融合策略** — 向量分数为主，BM25 命中给予 15% 加成（非传统 RRF，经调优）
+- **向量搜索** — 基于 LanceDB ANN 的语义相似度（余弦距离）
+- **BM25 全文搜索** — 通过 LanceDB FTS 索引进行精确关键词匹配
+- **混合融合** — 以向量分数为基础，BM25 命中结果获得加权提升（非标准 RRF——针对实际召回质量调优）
- **可配置权重** — `vectorWeight`、`bm25Weight`、`minScore`
-### 跨编码器 Rerank
+### 交叉编码器重排序
-- 支持 **Jina**、**SiliconFlow**、**Voyage AI**、**Pinecone** 或任意兼容端点
-- 混合评分：60% cross-encoder + 40% 原始融合分
-- 降级策略：API 失败时回退到 cosine similarity rerank
+- 内置 **Jina**、**SiliconFlow**、**Voyage AI** 和 **Pinecone** 适配器
+- 兼容任意 Jina 兼容端点（如 Hugging Face TEI、DashScope）
+- 混合打分：60% 交叉编码器 + 40% 原始融合分数
+- 优雅降级：API 失败时回退到余弦相似度
-### 多层评分管线
+### 多阶段评分管线
| 阶段 | 效果 |
| --- | --- |
-| **RRF 融合** | 同时结合语义召回和关键词召回 |
-| **跨编码器重排** | 提升语义更准确的结果 |
-| **生命周期衰减加权** | Weibull 新鲜度 + 访问频率 + importance × confidence |
-| **长度归一化** | 防止长条目霸占查询结果（锚点 500 字符） |
-| **硬最低分** | 低于阈值直接丢弃（默认 0.35） |
-| **MMR 多样性** | cosine 相似度 > 0.85 → 降级 |
+| **混合融合** | 结合语义召回和精确匹配召回 |
+| **交叉编码器重排序** | 提升语义精确命中的排名 |
+| **生命周期衰减加权** | Weibull 时效性 + 访问频率 + 重要性 × 置信度 |
+| **长度归一化** | 防止长条目主导结果（锚点：500 字符） |
+| **硬最低分** | 移除无关结果（默认：0.35） |
+| **MMR 多样性** | 余弦相似度 > 0.85 → 降权 |
### 智能记忆提取（v1.1.0）
-- **LLM 驱动 6 类别提取**：profile、preferences、entities、events、cases、patterns
+- **LLM 驱动的 6 类提取**：用户画像、偏好、实体、事件、案例、模式
- **L0/L1/L2 分层存储**：L0（一句话索引）→ L1（结构化摘要）→ L2（完整叙述）
- **两阶段去重**：向量相似度预过滤（≥0.7）→ LLM 语义决策（CREATE/MERGE/SKIP）
-- **类别感知合并**：`profile` 始终合并，`events`/`cases` 仅新增
+- **类别感知合并**：`profile` 始终合并，`events`/`cases` 仅追加
### 记忆生命周期管理（v1.1.0）
-- **Weibull 衰减引擎**：复合分数 = 时效 + 频率 + 内在价值
-- **衰减感知检索**：召回结果按生命周期衰减重排
-- **三层晋升系统**：`Peripheral ⟷ Working ⟷ Core`，可配置阈值
+- **Weibull 衰减引擎**：综合分数 = 时效性 + 频率 + 内在价值
+- **三级晋升**：`外围 ↔ 工作 ↔ 核心`，阈值可配置
+- **访问强化**：频繁被召回的记忆衰减更慢（类似间隔重复机制）
- **重要性调制半衰期**：重要记忆衰减更慢
-### 多 Scope 隔离
+### 多作用域隔离
+
+- 内置作用域：`global`、`agent:📄 文件说明（点击展开）
+文件说明（点击展开）
| 文件 | 用途 | | --- | --- | -| `index.ts` | 插件入口。注册到 OpenClaw Plugin API，解析配置，挂载 `before_agent_start`（自动回忆）、`agent_end`（自动捕获）、`command:new`（Session 记忆）等钩子 | -| `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/upgrade/migrate` | -| `src/store.ts` | LanceDB 存储层。表创建 / FTS 索引 / Vector Search / BM25 / CRUD / 批量删除 / 统计 | -| `src/embedder.ts` | Embedding 抽象层。兼容任意 OpenAI API Provider，支持 task-aware embedding | -| `src/retriever.ts` | 混合检索引擎。Vector + BM25 → RRF 融合 → Rerank → 生命周期衰减 → Length Norm → Noise Filter → MMR | -| `src/scopes.ts` | 多 Scope 访问控制：`global`、`agent:
+与内置
-### 旧记忆一键升级（v1.1.0）
+| 功能 | 内置 `memory-lancedb` | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| 向量搜索 | 有 | 有 |
+| BM25 全文搜索 | - | 有 |
+| 混合融合（向量 + BM25） | - | 有 |
+| 交叉编码器重排序（多 Provider） | - | 有 |
+| 时效性提升和时间衰减 | - | 有 |
+| 长度归一化 | - | 有 |
+| MMR 多样性 | - | 有 |
+| 多作用域隔离 | - | 有 |
+| 噪音过滤 | - | 有 |
+| 自适应检索 | - | 有 |
+| 管理 CLI | - | 有 |
+| 会话记忆 | - | 有 |
+| 任务感知 Embedding | - | 有 |
+| **LLM 智能提取（6 类）** | - | 有（v1.1.0） |
+| **Weibull 衰减 + 层级晋升** | - | 有（v1.1.0） |
+| 任意 OpenAI 兼容 Embedding | 有限 | 有 |
-- 一条命令升级：`openclaw memory-pro upgrade`
-- LLM 或无 LLM 模式（离线可用）
-- 启动自动检测并提示升级
+
---
-## ⚙️ 配置
+## 配置
与内置 memory-lancedb 的对比（点击展开）
-### 旧记忆一键升级（v1.1.0）
+| 功能 | 内置 `memory-lancedb` | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| 向量搜索 | 有 | 有 |
+| BM25 全文搜索 | - | 有 |
+| 混合融合（向量 + BM25） | - | 有 |
+| 交叉编码器重排序（多 Provider） | - | 有 |
+| 时效性提升和时间衰减 | - | 有 |
+| 长度归一化 | - | 有 |
+| MMR 多样性 | - | 有 |
+| 多作用域隔离 | - | 有 |
+| 噪音过滤 | - | 有 |
+| 自适应检索 | - | 有 |
+| 管理 CLI | - | 有 |
+| 会话记忆 | - | 有 |
+| 任务感知 Embedding | - | 有 |
+| **LLM 智能提取（6 类）** | - | 有（v1.1.0） |
+| **Weibull 衰减 + 层级晋升** | - | 有（v1.1.0） |
+| 任意 OpenAI 兼容 Embedding | 有限 | 有 |
-- 一条命令升级：`openclaw memory-pro upgrade`
-- LLM 或无 LLM 模式（离线可用）
-- 启动自动检测并提示升级
+完整配置示例
@@ -388,8 +438,8 @@ Query → BM25 FTS ─────┘ "scopes": { "default": "global", "definitions": { - "global": { "description": "共享知识库" }, - "agent:discord-bot": { "description": "Discord 机器人私有" } + "global": { "description": "Shared knowledge" }, + "agent:discord-bot": { "description": "Discord bot private" } }, "agentAccess": { "discord-bot": ["global", "agent:discord-bot"] @@ -410,457 +460,210 @@ Query → BM25 FTS ─────┘ } ``` -OpenClaw 默认行为： - -- `autoCapture`：默认开启 -- `autoRecall`：插件 schema 默认关闭，但本 README 建议大多数新用户显式开启 -- `embedding.chunking`：默认开启 -- `sessionMemory.enabled`：默认关闭；需要显式设为 `true` 才注册 `/new` Hook -
-
-
-Embedding 提供商
+Embedding 服务商
-本插件支持 **任意 OpenAI 兼容的 Embedding API**： +兼容 **任意 OpenAI 兼容 Embedding API**： -| 提供商 | 模型 | Base URL | 维度 | +| 服务商 | 模型 | Base URL | 维度 | | --- | --- | --- | --- | | **Jina**（推荐） | `jina-embeddings-v5-text-small` | `https://api.jina.ai/v1` | 1024 | | **OpenAI** | `text-embedding-3-small` | `https://api.openai.com/v1` | 1536 | +| **Voyage** | `voyage-4-lite` / `voyage-4` | `https://api.voyageai.com/v1` | 1024 / 1024 | | **Google Gemini** | `gemini-embedding-001` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 | -| **Ollama**（本地） | `nomic-embed-text` | `http://localhost:11434/v1` | _与本地模型一致_ | - -
-
Rerank 提供商
- -通过 `rerankProvider` 配置跨编码器 Rerank： - -| 提供商 | `rerankProvider` | Endpoint | 示例模型 | -| --- | --- | --- | --- | -| **Jina**（默认） | `jina` | `https://api.jina.ai/v1/rerank` | `jina-reranker-v3` | -| **SiliconFlow**（有免费额度） | `siliconflow` | `https://api.siliconflow.com/v1/rerank` | `BAAI/bge-reranker-v2-m3` | -| **Voyage AI** | `voyage` | `https://api.voyageai.com/v1/rerank` | `rerank-2.5` | -| **Pinecone** | `pinecone` | `https://api.pinecone.io/rerank` | `bge-reranker-v2-m3` | - -
-
-
-SiliconFlow 配置示例
- -```json -{ - "retrieval": { - "rerank": "cross-encoder", - "rerankProvider": "siliconflow", - "rerankEndpoint": "https://api.siliconflow.com/v1/rerank", - "rerankApiKey": "sk-xxx", - "rerankModel": "BAAI/bge-reranker-v2-m3" - } -} -``` - -
-
Voyage 配置示例
- -```json -{ - "retrieval": { - "rerank": "cross-encoder", - "rerankProvider": "voyage", - "rerankEndpoint": "https://api.voyageai.com/v1/rerank", - "rerankApiKey": "${VOYAGE_API_KEY}", - "rerankModel": "rerank-2.5" - } -} -``` +| **Ollama**（本地） | `nomic-embed-text` | `http://localhost:11434/v1` | 取决于模型 |
-
+| 服务商 | `rerankProvider` | 示例模型 |
+| --- | --- | --- |
+| **Jina**（默认） | `jina` | `jina-reranker-v3` |
+| **SiliconFlow**（有免费额度） | `siliconflow` | `BAAI/bge-reranker-v2-m3` |
+| **Voyage AI** | `voyage` | `rerank-2.5` |
+| **Pinecone** | `pinecone` | `bge-reranker-v2-m3` |
-说明：`voyage` 发送 `{ model, query, documents }` 格式（不含 `top_n`），响应从 `data[].relevance_score` 解析。
+任何 Jina 兼容的重排序端点也可以使用——设置 `rerankProvider: "jina"` 并将 `rerankEndpoint` 指向你的服务（如 Hugging Face TEI、DashScope `qwen3-rerank`）。
Pinecone 配置示例
+重排序服务商
-```json -{ - "retrieval": { - "rerank": "cross-encoder", - "rerankProvider": "pinecone", - "rerankEndpoint": "https://api.pinecone.io/rerank", - "rerankApiKey": "pcsk_xxx", - "rerankModel": "bge-reranker-v2-m3" - } -} -``` +交叉编码器重排序通过 `rerankProvider` 支持多个服务商： -
-
-
-智能提取配置（LLM）— v1.1.0
+智能提取（LLM）— v1.1.0
-启用 `smartExtraction`（默认 `true`）后，插件用 LLM 智能提取和分类记忆，替代正则触发。 +当 `smartExtraction` 启用（默认 `true`）时，插件使用 LLM 智能提取和分类记忆，替代基于正则的触发方式。 | 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | `smartExtraction` | boolean | `true` | 是否启用 LLM 智能 6 类别提取 | +| `llm.auth` | string | `api-key` | `api-key` 使用 `llm.apiKey` / `embedding.apiKey`；`oauth` 默认使用 plugin 级 OAuth token 文件 | | `llm.apiKey` | string | *（复用 `embedding.apiKey`）* | LLM 提供商 API Key | | `llm.model` | string | `openai/gpt-oss-120b` | LLM 模型名称 | | `llm.baseURL` | string | *（复用 `embedding.baseURL`）* | LLM API 端点 | -| `extractMinMessages` | number | `2` | 触发提取所需最少消息数 | +| `llm.oauthProvider` | string | `openai-codex` | `llm.auth` 为 `oauth` 时使用的 OAuth provider id | +| `llm.oauthPath` | string | `~/.openclaw/.memory-lancedb-pro/oauth.json` | `llm.auth` 为 `oauth` 时使用的 OAuth token 文件 | +| `llm.timeoutMs` | number | `30000` | LLM 请求超时（毫秒） | +| `extractMinMessages` | number | `2` | 触发提取的最小消息数 | | `extractMaxChars` | number | `8000` | 发送给 LLM 的最大字符数 | -最简配置（复用 embedding API Key）： -```json -{ - "embedding": { "apiKey": "${OPENAI_API_KEY}", "model": "text-embedding-3-small" }, - "smartExtraction": true -} -``` - -完整配置（独立 LLM 端点）： -```json -{ - "embedding": { "apiKey": "${OPENAI_API_KEY}", "model": "text-embedding-3-small" }, - "smartExtraction": true, - "llm": { "apiKey": "${OPENAI_API_KEY}", "model": "gpt-4o-mini", "baseURL": "https://api.openai.com/v1" }, - "extractMinMessages": 2, - "extractMaxChars": 8000 -} -``` - -禁用：`{ "smartExtraction": false }` - -
-
-
-生命周期配置（Decay + Tier）
- -控制记忆新鲜度排序与自动层级迁移。 - -| 字段 | 类型 | 默认值 | 说明 | -|------|------|--------|------| -| `decay.recencyHalfLifeDays` | number | `30` | Weibull 时效衰减基础半衰期 | -| `decay.frequencyWeight` | number | `0.3` | 访问频率在复合分数中的权重 | -| `decay.intrinsicWeight` | number | `0.3` | `importance × confidence` 的权重 | -| `decay.betaCore` | number | `0.8` | `core` 记忆的 Weibull beta | -| `decay.betaWorking` | number | `1.0` | `working` 记忆的 Weibull beta | -| `decay.betaPeripheral` | number | `1.3` | `peripheral` 记忆的 Weibull beta | -| `tier.coreAccessThreshold` | number | `10` | 晋升到 `core` 所需最小 recall 次数 | -| `tier.coreCompositeThreshold` | number | `0.7` | 晋升到 `core` 所需最小生命周期分数 | -| `tier.peripheralCompositeThreshold` | number | `0.15` | 低于此分数的 `working` 可能降级 | -| `tier.peripheralAgeDays` | number | `60` | 陈旧低访问记忆降级年龄阈值 | - -```json -{ - "decay": { "recencyHalfLifeDays": 21, "betaCore": 0.7, "betaPeripheral": 1.5 }, - "tier": { "coreAccessThreshold": 8, "peripheralAgeDays": 45 } -} -``` - -
-
-
----
-
-## 📥 安装
-
-访问强化（1.0.26）
- -经常被用到的记忆衰减更慢（类似间隔重复）。 - -配置项（位于 `retrieval` 下）： -- `reinforcementFactor`（0–2，默认 `0.5`）— 设为 `0` 可关闭 -- `maxHalfLifeMultiplier`（1–10，默认 `3`）— 有效 half-life 硬上限 - -说明：强化逻辑只对 `source: "manual"` 生效，避免 auto-recall 意外"强化"噪声。 - -
-
路径 A：第一次用 OpenClaw（推荐）
- -1. 克隆到 workspace： - -```bash -cd /path/to/your/openclaw/workspace -git clone https://github.com/CortexReach/memory-lancedb-pro.git plugins/memory-lancedb-pro -cd plugins/memory-lancedb-pro -npm install -``` - -2. 添加到 `openclaw.json`（相对路径）： +OAuth `llm` 配置（使用现有 Codex / ChatGPT 登录缓存来发送 LLM 请求）： ```json { - "plugins": { - "load": { "paths": ["plugins/memory-lancedb-pro"] }, - "entries": { - "memory-lancedb-pro": { - "enabled": true, - "config": { - "embedding": { - "apiKey": "${JINA_API_KEY}", - "model": "jina-embeddings-v5-text-small", - "baseURL": "https://api.jina.ai/v1", - "dimensions": 1024, - "taskQuery": "retrieval.query", - "taskPassage": "retrieval.passage", - "normalized": true - } - } - } - }, - "slots": { "memory": "memory-lancedb-pro" } + "llm": { + "auth": "oauth", + "oauthProvider": "openai-codex", + "model": "gpt-5.4", + "oauthPath": "${HOME}/.openclaw/.memory-lancedb-pro/oauth.json", + "timeoutMs": 30000 } } ``` -3. 重启并验证： +`llm.auth: "oauth"` 说明： -```bash -openclaw config validate -openclaw gateway restart -openclaw plugins info memory-lancedb-pro -openclaw hooks list --json -openclaw memory-pro stats -``` - -4. 烟测：写入 1 条记忆 → 关键词搜索 → 自然语言搜索。 +- `llm.oauthProvider` 当前仅支持 `openai-codex`。 +- OAuth token 默认存放在 `~/.openclaw/.memory-lancedb-pro/oauth.json`。 +- 如需自定义路径，可设置 `llm.oauthPath`。 +- `auth login` 会在 OAuth 文件旁边快照原来的 `api-key` 模式 `llm` 配置；`auth logout` 在可用时会恢复这份快照。 +- 从 `api-key` 切到 `oauth` 时不会自动沿用 `llm.baseURL`；只有在你明确需要自定义 ChatGPT/Codex 兼容后端时，才应在 `oauth` 模式下手动设置。
-
路径 B：已在用 OpenClaw，现在加入插件
- -1. 保持现有 agents、channels、models 不变 -2. 用**绝对路径**把插件加到 `plugins.load.paths`： - -```json -{ "plugins": { "load": { "paths": ["/absolute/path/to/memory-lancedb-pro"] } } } -``` - -3. 绑定 memory slot：`plugins.slots.memory = "memory-lancedb-pro"` -4. 验证：`openclaw plugins info memory-lancedb-pro && openclaw memory-pro stats` +生命周期配置（衰减 + 层级）
+ +| 字段 | 默认值 | 说明 | +|------|--------|------| +| `decay.recencyHalfLifeDays` | `30` | Weibull 时效性衰减的基础半衰期 | +| `decay.frequencyWeight` | `0.3` | 访问频率在综合分数中的权重 | +| `decay.intrinsicWeight` | `0.3` | `重要性 × 置信度` 的权重 | +| `decay.betaCore` | `0.8` | `核心` 记忆的 Weibull beta | +| `decay.betaWorking` | `1.0` | `工作` 记忆的 Weibull beta | +| `decay.betaPeripheral` | `1.3` | `外围` 记忆的 Weibull beta | +| `tier.coreAccessThreshold` | `10` | 晋升到 `核心` 所需的最小召回次数 | +| `tier.peripheralAgeDays` | `60` | 降级过期记忆的天数阈值 |
-
-
-路径 C：从旧版 memory-lancedb-pro 升级（v1.1.0 之前）
+访问强化
-命令边界： -- `upgrade` — 用于**旧版 `memory-lancedb-pro` 数据升级** -- `migrate` — 只用于从内置 **`memory-lancedb`** 迁移 -- `reembed` — 只在更换 embedding 模型后重建向量时使用 +频繁被召回的记忆衰减更慢（类似间隔重复机制）。 -推荐安全顺序： - -```bash -# 1) 备份 -openclaw memory-pro export --scope global --output memories-backup.json - -# 2) 先检查 -openclaw memory-pro upgrade --dry-run - -# 3) 正式升级 -openclaw memory-pro upgrade - -# 4) 验证 -openclaw memory-pro stats -openclaw memory-pro search "your known keyword" --scope global --limit 5 -``` - -详见 `docs/CHANGELOG-v1.1.0.md`。 - -
-
-
-安装后验证清单
- -```bash -openclaw config validate -openclaw gateway restart -openclaw plugins info memory-lancedb-pro -openclaw hooks list --json -openclaw memory-pro stats -openclaw memory-pro list --scope global --limit 5 -``` - -然后验证： -- ✅ 1 个唯一标识符搜索命中 -- ✅ 1 个自然语言搜索命中 -- ✅ 1 轮 `memory_store` → `memory_recall` -- ✅ 如启用 session memory，补 1 轮真实 `/new` - -
-
-
-AI 安装指引（防幻觉版）
- -如果你是用 AI 按 README 操作，**不要假设任何默认值**。先运行： - -```bash -openclaw config get agents.defaults.workspace -openclaw config get plugins.load.paths -openclaw config get plugins.slots.memory -openclaw config get plugins.entries.memory-lancedb-pro -``` - -建议： -- `plugins.load.paths` 优先用**绝对路径** -- 如果配置里用 `${JINA_API_KEY}`，务必确保 Gateway **服务进程环境**里有该变量 -- 修改插件配置后运行 `openclaw gateway restart` - -
-
-
-Jina API Key（Embedding + Rerank）
- -- **Embedding**：`embedding.apiKey` 填 Jina key（推荐用 `${JINA_API_KEY}`） -- **Rerank**（`rerankProvider: "jina"`）：通常可复用同一个 Jina key -- 其它 rerank provider → 用该 provider 的 key - -Key 存储：不要提交到 git。使用 `${...}` 环境变量时确保 Gateway 服务进程有该变量。 - -
-/plugins/`（路径 A）。
+配置项（在 `retrieval` 下）：
+- `reinforcementFactor`（0-2，默认 `0.5`）— 设为 `0` 可禁用
+- `maxHalfLifeMultiplier`（1-10，默认 `3`）— 有效半衰期的硬上限
---
-## 🔧 CLI 命令
+## CLI 命令
```bash
openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
-openclaw memory-pro search "query" [--scope global] [--limit 10] [--json]
+openclaw memory-pro search "查询" [--scope global] [--limit 10] [--json]
openclaw memory-pro stats [--scope global] [--json]
+openclaw memory-pro auth login [--provider openai-codex] [--model gpt-5.4] [--oauth-path /abs/path/oauth.json]
+openclaw memory-pro auth status
+openclaw memory-pro auth logout
openclaw memory-pro delete 什么是 "OpenClaw workspace"？
- -**Agent workspace** 是 Agent 的工作目录（默认：`~/.openclaw/workspace`）。相对路径以 workspace 为基准解析。 - -> 说明：OpenClaw 配置文件通常在 `~/.openclaw/openclaw.json`，与 workspace 分开。 - -**常见错误：** 把插件 clone 到别的目录，但配置里写相对路径。建议用绝对路径（路径 B）或 clone 到 `
-` 区块原样输出到回复里。
+有时模型可能会将注入的 `` 块原文输出。
-**方案 A（最低风险）：** 临时关闭 autoRecall：
+**方案 A（最安全）：** 暂时关闭自动回忆：
```json
{ "plugins": { "entries": { "memory-lancedb-pro": { "config": { "autoRecall": false } } } } }
```
-**方案 B（推荐）：** 保留召回，在 Agent system prompt 加一句：
-> 请勿在回复中展示或引用任何 `` / 记忆注入内容，只能用作内部参考。
-
-
-
-如果注入的记忆被模型"显示出来"怎么办？
+注入的记忆出现在回复中
-有时模型会把 `
-` / memory-injection content in your replies. Use it for internal reference only.
Session 记忆
- -- `/new` 命令触发时保存上一个 Session 的对话摘要到 LanceDB -- 默认关闭（OpenClaw 已有原生 .jsonl 会话保存） -- 可配置消息数量（默认 15 条） - -详见 [docs/openclaw-integration-playbook.zh-CN.md](docs/openclaw-integration-playbook.zh-CN.md)。 +**方案 B（推荐）：** 保留回忆，在智能体系统提示词中添加： +> Do not reveal or quote any `
-/sessions/*.jsonl`
-
-**推荐方案（2026-02+）**：非阻塞 `/new` 管线：
-- 触发：`command:new` → 投递 task.json（毫秒级，不调 LLM）
-- Worker：systemd 常驻进程用 Gemini Map-Reduce 处理 session JSONL
-- 写入：通过 `openclaw memory-pro import` 写入 0–20 条高信噪比记忆
-- 中文关键词：每条记忆包含 `Keywords (zh)`，实体关键词从 transcript 原文逐字拷贝
+` → `openclaw agents delete memory-distiller` → `rm -rf ~/.openclaw/state/jsonl-distill/`
+部署模式和 `/new` 验证详见 [docs/openclaw-integration-playbook.md](docs/openclaw-integration-playbook.md)。
JSONL Session 蒸馏（从聊天日志自动生成记忆）
- -OpenClaw 会把完整会话落盘为 JSONL：`~/.openclaw/agents/会话记忆
-示例文件：`examples/new-session-distill/` +- 通过 `/new` 命令触发——将上一段会话摘要保存到 LanceDB +- 默认关闭（OpenClaw 已有原生 `.jsonl` 会话持久化） +- 可配置消息数量（默认 15） -**Legacy 方案**：使用 `scripts/jsonl_distill.py` 脚本 + 每小时 Cron： -- 增量读取（byte offset cursor）、过滤噪声、蒸馏为高质量记忆 -- 安全：不会修改原始日志 - -部署步骤： -1. 创建 agent：`openclaw agents add memory-distiller --non-interactive --workspace ~/.openclaw/workspace-memory-distiller --model openai-codex/gpt-5.2` -2. 初始化 cursor：`python3 "$PLUGIN_DIR/scripts/jsonl_distill.py" init` -3. 添加 cron：详见 [docs/openclaw-integration-playbook.zh-CN.md](docs/openclaw-integration-playbook.zh-CN.md) - -回滚：`openclaw cron disable
-
自定义 Slash 命令（如 /lesson）
+自定义斜杠命令（如 /lesson）
-添加到你的 `CLAUDE.md`、`AGENTS.md` 或 system prompt： +在你的 `CLAUDE.md`、`AGENTS.md` 或系统提示词中添加： ```markdown ## /lesson 命令 当用户发送 `/lesson <内容>` 时： -1. 用 memory_store 存为 category=fact（原始知识） -2. 用 memory_store 存为 category=decision（可操作的结论） +1. 用 memory_store 保存为 category=fact（原始知识） +2. 用 memory_store 保存为 category=decision（可执行的结论） 3. 确认已保存的内容 ## /remember 命令 当用户发送 `/remember <内容>` 时： -1. 用 memory_store 存储，自动选择合适的 category 和 importance -2. 返回存储的 memory ID +1. 用 memory_store 以合适的 category 和 importance 保存 +2. 返回已存储的记忆 ID 确认 ``` -内置工具：`memory_store`、`memory_recall`、`memory_forget`、`memory_update` — 插件加载时自动注册。 -
-
@@ -873,51 +676,53 @@ LanceDB 表 `memories`：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string (UUID) | 主键 |
-| `text` | string | 记忆文本（FTS 索引） |
+| `text` | string | 记忆文本（全文索引） |
| `vector` | float[] | Embedding 向量 |
-| `category` | string | `preference` / `fact` / `decision` / `entity` / `other` |
-| `scope` | string | Scope 标识（如 `global`、`agent:main`） |
-| `importance` | float | 重要性分数 0–1 |
-| `timestamp` | int64 | 创建时间戳 (ms) |
+| `category` | string | 存储类别：`preference` / `fact` / `decision` / `entity` / `reflection` / `other` |
+| `scope` | string | 作用域标识（如 `global`、`agent:main`） |
+| `importance` | float | 重要性分数 0-1 |
+| `timestamp` | int64 | 创建时间戳（毫秒） |
| `metadata` | string (JSON) | 扩展元数据 |
-v1.1.0 常见 `metadata` 字段：`l0_abstract`、`l1_overview`、`l2_content`、`memory_category`、`tier`、`access_count`、`confidence`、`last_accessed_at`
+v1.1.0 常用 `metadata` 字段：`l0_abstract`、`l1_overview`、`l2_content`、`memory_category`、`tier`、`access_count`、`confidence`、`last_accessed_at`
+
+> **关于分类的说明：** 顶层 `category` 字段使用 6 个存储类别。智能提取的 6 类语义标签（`profile` / `preferences` / `entities` / `events` / `cases` / `patterns`）存储在 `metadata.memory_category` 中。
AI Agent 铁律（Iron Rules）
+AI 智能体铁律
-> 将下方代码块复制到你的 `AGENTS.md` 中，让 Agent 自动遵守。 +> 将以下内容复制到你的 `AGENTS.md`，让智能体自动遵守这些规则。 ```markdown -## Rule 1 — 双层记忆存储（铁律） -Every pitfall/lesson learned → IMMEDIATELY store TWO memories: -- **Technical layer**: Pitfall: [symptom]. Cause: [root cause]. Fix: [solution]. Prevention: [how to avoid] - (category: fact, importance ≥ 0.8) -- **Principle layer**: Decision principle ([tag]): [behavioral rule]. Trigger: [when]. Action: [what to do] - (category: decision, importance ≥ 0.85) -- After each store, immediately `memory_recall` to verify retrieval. +## 规则 1 — 双层记忆存储 +每个踩坑/经验教训 → 立即存储两条记忆： +- 技术层：踩坑：[现象]。原因：[根因]。修复：[方案]。预防：[如何避免] + (category: fact, importance >= 0.8) +- 原则层：决策原则 ([标签])：[行为规则]。触发：[何时]。动作：[做什么] + (category: decision, importance >= 0.85) -## Rule 2 — LanceDB 卫生 -Entries must be short and atomic (< 500 chars). No raw conversation summaries or duplicates. +## 规则 2 — LanceDB 数据质量 +条目必须简短且原子化（< 500 字符）。不存储原始对话摘要或重复内容。 -## Rule 3 — Recall before retry -On ANY tool failure, ALWAYS `memory_recall` with relevant keywords BEFORE retrying. +## 规则 3 — 重试前先回忆 +任何工具调用失败时，必须先用 memory_recall 搜索相关关键词，再重试。 -## Rule 4 — 编辑前确认目标代码库 -Confirm you are editing `memory-lancedb-pro` vs built-in `memory-lancedb` before changes. +## 规则 4 — 确认目标代码库 +修改前确认你操作的是 memory-lancedb-pro 还是内置 memory-lancedb。 -## Rule 5 — 插件代码变更必须清 jiti 缓存 -After modifying `.ts` files under `plugins/`, MUST run `rm -rf /tmp/jiti/` BEFORE `openclaw gateway restart`. +## 规则 5 — 修改插件代码后清除 jiti 缓存 +修改 plugins/ 下的 .ts 文件后，必须先执行 rm -rf /tmp/jiti/ 再重启 openclaw gateway。 ```
-
---
-## 🧪 Beta：智能记忆 v1.1.0
+## 文档
-> 状态：Beta 版 — 通过 `npm i memory-lancedb-pro@beta` 安装。`latest` 稳定通道不受影响。
+| 文档 | 说明 |
+| --- | --- |
+| [OpenClaw 集成手册](docs/openclaw-integration-playbook.md) | 部署模式、验证、回归矩阵 |
+| [记忆架构分析](docs/memory_architecture_analysis.md) | 完整架构深度解析 |
+| [CHANGELOG v1.1.0](docs/CHANGELOG-v1.1.0.md) | v1.1.0 行为变更和升级说明 |
+| [长上下文分块](docs/long-context-chunking.md) | 长文档分块策略 |
-| 功能 | 说明 |
-|------|------|
-| **智能提取** | LLM 驱动的 6 类别提取，含 L0/L1/L2 metadata。禁用时回退到正则。 |
-| **生命周期评分** | Weibull 衰减集成到检索中——高频、高重要性的记忆排名更靠前。 |
-| **分层管理** | 三层系统（Core → Working → Peripheral），根据访问频率和分数自动晋升/降级。 |
+---
-反馈：[GitHub Issues](https://github.com/CortexReach/memory-lancedb-pro/issues) · 回退：`npm i memory-lancedb-pro@latest`
+## Beta：智能记忆 v1.1.0
----
+> 状态：Beta——通过 `npm i memory-lancedb-pro@beta` 安装。使用 `latest` 的稳定版用户不受影响。
-## 📖 文档
+| 功能 | 说明 |
+|------|------|
+| **智能提取** | LLM 驱动的 6 类提取，支持 L0/L1/L2 元数据。禁用时回退到正则模式。 |
+| **生命周期评分** | Weibull 衰减集成到检索中——高频和高重要性记忆排名更高。 |
+| **层级管理** | 三级系统（核心 → 工作 → 外围），自动晋升/降级。 |
-| 文档 | 说明 |
-| --- | --- |
-| [OpenClaw 集成操作手册](docs/openclaw-integration-playbook.zh-CN.md) | 部署模式、`/new` 验证、回归矩阵 |
-| [记忆架构分析](docs/memory_architecture_analysis.md) | 完整架构深度解析 |
-| [CHANGELOG v1.1.0](docs/CHANGELOG-v1.1.0.md) | v1.1.0 行为变化和升级背景 |
-| [长上下文分块](docs/long-context-chunking.md) | 长文档分块策略 |
+反馈：[GitHub Issues](https://github.com/CortexReach/memory-lancedb-pro/issues) · 回退：`npm i memory-lancedb-pro@latest`
---
@@ -931,7 +736,7 @@ v1.1.0 常见 `metadata` 字段：`l0_abstract`、`l1_overview`、`l2_content`
---
-## 🤝 主要贡献者
+## 贡献者
常见问题 / 排错
+故障排除
### "Cannot mix BigInt and other types"（LanceDB / Apache Arrow） -在 LanceDB 0.26+ 中，部分数值列可能以 `BigInt` 返回。请升级到 **memory-lancedb-pro >= 1.0.14** — 插件已统一做 `Number(...)` 转换。 +在 LanceDB 0.26+ 上，某些数值列可能以 `BigInt` 形式返回。升级到 **memory-lancedb-pro >= 1.0.14**——插件现在会在运算前使用 `Number(...)` 进行类型转换。
diff --git a/README_DE.md b/README_DE.md
new file mode 100644
index 00000000..104c259b
--- /dev/null
+++ b/README_DE.md
@@ -0,0 +1,773 @@
+
+
+# 🧠 memory-lancedb-pro · 🦞OpenClaw Plugin
+
+**KI-Gedächtnisassistent für [OpenClaw](https://github.com/openclaw/openclaw)-Agenten**
+
+*Geben Sie Ihrem KI-Agenten ein Gehirn, das sich wirklich erinnert — über Sitzungen, Agenten und Zeit hinweg.*
+
+Ein LanceDB-basiertes OpenClaw-Langzeitgedächtnis-Plugin, das Präferenzen, Entscheidungen und Projektkontext speichert und in zukünftigen Sitzungen automatisch abruft.
+
+[](https://github.com/openclaw/openclaw)
+[](https://www.npmjs.com/package/memory-lancedb-pro)
+[](https://lancedb.com)
+[](LICENSE)
+
+[English](README.md) | [简体中文](README_CN.md) | [繁體中文](README_TW.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | [Español](README_ES.md) | [Deutsch](README_DE.md) | [Italiano](README_IT.md) | [Русский](README_RU.md) | [Português (Brasil)](README_PT-BR.md)
+
+
+
+---
+
+## Warum memory-lancedb-pro?
+
+Die meisten KI-Agenten leiden unter Amnesie. Sie vergessen alles, sobald Sie einen neuen Chat starten.
+
+**memory-lancedb-pro** ist ein produktionsreifes Langzeitgedächtnis-Plugin für OpenClaw, das Ihren Agenten in einen echten **KI-Gedächtnisassistenten** verwandelt — es erfasst automatisch, was wichtig ist, lässt Rauschen natürlich verblassen und ruft die richtige Erinnerung zum richtigen Zeitpunkt ab. Kein manuelles Taggen, keine Konfigurationsprobleme.
+
+### Ihr KI-Gedächtnisassistent in Aktion
+
+**Ohne Gedächtnis — jede Sitzung beginnt bei null:**
+
+> **Sie:** „Verwende Tabs für die Einrückung, füge immer Fehlerbehandlung hinzu."
+> *(nächste Sitzung)*
+> **Sie:** „Ich habe es dir schon gesagt — Tabs, nicht Leerzeichen!" 😤
+> *(nächste Sitzung)*
+> **Sie:** „…ernsthaft, Tabs. Und Fehlerbehandlung. Schon wieder."
+
+**Mit memory-lancedb-pro — Ihr Agent lernt und erinnert sich:**
+
+> **Sie:** „Verwende Tabs für die Einrückung, füge immer Fehlerbehandlung hinzu."
+> *(nächste Sitzung — Agent ruft automatisch Ihre Präferenzen ab)*
+> **Agent:** *(wendet still Tabs + Fehlerbehandlung an)* ✅
+> **Sie:** „Warum haben wir letzten Monat PostgreSQL statt MongoDB gewählt?"
+> **Agent:** „Basierend auf unserer Diskussion am 12. Februar waren die Hauptgründe…" ✅
+
+Das ist der Unterschied, den ein **KI-Gedächtnisassistent** macht — er lernt Ihren Stil, erinnert sich an vergangene Entscheidungen und liefert personalisierte Antworten, ohne dass Sie sich wiederholen müssen.
+
+### Was kann es noch?
+
+| | Was Sie bekommen |
+|---|---|
+| **Auto-Capture** | Ihr Agent lernt aus jeder Unterhaltung — kein manuelles `memory_store` nötig |
+| **Intelligente Extraktion** | LLM-gestützte 6-Kategorien-Klassifikation: Profile, Präferenzen, Entitäten, Ereignisse, Fälle, Muster |
+| **Intelligentes Vergessen** | Weibull-Zerfallsmodell — wichtige Erinnerungen bleiben, Rauschen verblasst natürlich |
+| **Hybride Suche** | Vektor + BM25 Volltextsuche, fusioniert mit Cross-Encoder-Reranking |
+| **Kontextinjektion** | Relevante Erinnerungen tauchen automatisch vor jeder Antwort auf |
+| **Multi-Scope-Isolation** | Gedächtnisgrenzen pro Agent, pro Benutzer, pro Projekt |
+| **Jeder Anbieter** | OpenAI, Jina, Gemini, Ollama oder jede OpenAI-kompatible API |
+| **Vollständiges Toolkit** | CLI, Backup, Migration, Upgrade, Export/Import — produktionsbereit |
+
+---
+
+## Schnellstart
+
+### Option A: Ein-Klick-Installationsskript (empfohlen)
+
+Das community-gepflegte **[Setup-Skript](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)** erledigt Installation, Upgrade und Reparatur in einem Befehl:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
+bash setup-memory.sh
+```
+
+> Siehe [Ökosystem](#ökosystem) unten für die vollständige Liste der abgedeckten Szenarien und andere Community-Tools.
+
+### Option B: Manuelle Installation
+
+**Über OpenClaw CLI (empfohlen):**
+```bash
+openclaw plugins install memory-lancedb-pro@beta
+```
+
+**Oder über npm:**
+```bash
+npm i memory-lancedb-pro@beta
+```
+> Bei npm-Installation müssen Sie auch das Plugin-Installationsverzeichnis als **absoluten** Pfad in `plugins.load.paths` Ihrer `openclaw.json` hinzufügen. Dies ist das häufigste Einrichtungsproblem.
+
+Fügen Sie zu Ihrer `openclaw.json` hinzu:
+
+```json
+{
+ "plugins": {
+ "slots": { "memory": "memory-lancedb-pro" },
+ "entries": {
+ "memory-lancedb-pro": {
+ "enabled": true,
+ "config": {
+ "embedding": {
+ "provider": "openai-compatible",
+ "apiKey": "${OPENAI_API_KEY}",
+ "model": "text-embedding-3-small"
+ },
+ "autoCapture": true,
+ "autoRecall": true,
+ "smartExtraction": true,
+ "extractMinMessages": 2,
+ "extractMaxChars": 8000,
+ "sessionMemory": { "enabled": false }
+ }
+ }
+ }
+ }
+}
+```
+
+**Warum diese Standardwerte?**
+- `autoCapture` + `smartExtraction` → Ihr Agent lernt automatisch aus jeder Unterhaltung
+- `autoRecall` → relevante Erinnerungen werden vor jeder Antwort injiziert
+- `extractMinMessages: 2` → Extraktion wird bei normalen Zwei-Runden-Chats ausgelöst
+- `sessionMemory.enabled: false` → vermeidet Verschmutzung der Suche durch Sitzungszusammenfassungen am Anfang
+
+Validieren und neu starten:
+
+```bash
+openclaw config validate
+openclaw gateway restart
+openclaw logs --follow --plain | grep "memory-lancedb-pro"
+```
+
+Sie sollten sehen:
+- `memory-lancedb-pro: smart extraction enabled`
+- `memory-lancedb-pro@...: plugin registered`
+
+Fertig! Ihr Agent verfügt jetzt über Langzeitgedächtnis.
+
+
+
+
+Weitere Installationswege (bestehende Benutzer, Upgrades)
+ +**Bereits OpenClaw-Benutzer?** + +1. Fügen Sie das Plugin mit einem **absoluten** `plugins.load.paths`-Eintrag hinzu +2. Binden Sie den Memory-Slot: `plugins.slots.memory = "memory-lancedb-pro"` +3. Überprüfen: `openclaw plugins info memory-lancedb-pro && openclaw memory-pro stats` + +**Upgrade von vor v1.1.0?** + +```bash +# 1) Backup +openclaw memory-pro export --scope global --output memories-backup.json +# 2) Testlauf +openclaw memory-pro upgrade --dry-run +# 3) Upgrade ausführen +openclaw memory-pro upgrade +# 4) Überprüfen +openclaw memory-pro stats +``` + +Siehe `CHANGELOG-v1.1.0.md` für Verhaltensänderungen und Upgrade-Begründung. + +
+
+
+---
+
+## Ökosystem
+
+memory-lancedb-pro ist das Kern-Plugin. Die Community hat Tools darum herum gebaut, um Einrichtung und tägliche Nutzung noch reibungsloser zu machen:
+
+### Setup-Skript — Ein-Klick-Installation, Upgrade und Reparatur
+
+> **[CortexReach/toolbox/memory-lancedb-pro-setup](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)**
+
+Nicht nur ein einfacher Installer — das Skript behandelt intelligent eine Vielzahl realer Szenarien:
+
+| Ihre Situation | Was das Skript macht |
+|---|---|
+| Nie installiert | Frischer Download → Abhängigkeiten installieren → Konfiguration wählen → in openclaw.json schreiben → Neustart |
+| Per `git clone` installiert, auf altem Commit hängen geblieben | Automatisches `git fetch` + `checkout` auf neueste Version → Abhängigkeiten neu installieren → Verifizieren |
+| Konfiguration hat ungültige Felder | Automatische Erkennung per Schema-Filter, nicht unterstützte Felder entfernen |
+| Per `npm` installiert | Überspringt Git-Update, erinnert Sie daran, `npm update` selbst auszuführen |
+| `openclaw` CLI durch ungültige Konfiguration defekt | Fallback: Workspace-Pfad direkt aus der `openclaw.json`-Datei lesen |
+| `extensions/` statt `plugins/` | Automatische Erkennung des Plugin-Standorts aus Konfiguration oder Dateisystem |
+| Bereits aktuell | Nur Gesundheitschecks ausführen, keine Änderungen |
+
+```bash
+bash setup-memory.sh # Installieren oder upgraden
+bash setup-memory.sh --dry-run # Nur Vorschau
+bash setup-memory.sh --beta # Pre-Release-Versionen einschließen
+bash setup-memory.sh --uninstall # Konfiguration zurücksetzen und Plugin entfernen
+```
+
+Eingebaute Anbieter-Presets: **Jina / DashScope / SiliconFlow / OpenAI / Ollama**, oder bringen Sie Ihre eigene OpenAI-kompatible API mit. Für die vollständige Nutzung (einschließlich `--ref`, `--selfcheck-only` und mehr) siehe das [Setup-Skript README](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup).
+
+### Claude Code / OpenClaw Skill — KI-geführte Konfiguration
+
+> **[CortexReach/memory-lancedb-pro-skill](https://github.com/CortexReach/memory-lancedb-pro-skill)**
+
+Installieren Sie diesen Skill und Ihr KI-Agent (Claude Code oder OpenClaw) erhält tiefgreifendes Wissen über alle Funktionen von memory-lancedb-pro. Sagen Sie einfach **„hilf mir die beste Konfiguration zu aktivieren"** und erhalten Sie:
+
+- **Geführter 7-Schritte-Konfigurationsworkflow** mit 4 Bereitstellungsplänen:
+ - Full Power (Jina + OpenAI) / Budget (kostenloser SiliconFlow Reranker) / Simple (nur OpenAI) / Vollständig lokal (Ollama, null API-Kosten)
+- **Alle 9 MCP-Tools** korrekt verwendet: `memory_recall`, `memory_store`, `memory_forget`, `memory_update`, `memory_stats`, `memory_list`, `self_improvement_log`, `self_improvement_extract_skill`, `self_improvement_review` *(vollständiges Toolset erfordert `enableManagementTools: true` — die Standard-Schnellstart-Konfiguration stellt nur die 4 Kern-Tools bereit)*
+- **Vermeidung häufiger Fallstricke**: Workspace-Plugin-Aktivierung, `autoRecall` standardmäßig false, jiti-Cache, Umgebungsvariablen, Scope-Isolation und mehr
+
+**Installation für Claude Code:**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro
+```
+
+**Installation für OpenClaw:**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill
+```
+
+---
+
+## Video-Tutorial
+
+> Vollständige Anleitung: Installation, Konfiguration und Funktionsweise der hybriden Suche.
+
+[](https://youtu.be/MtukF1C8epQ)
+**https://youtu.be/MtukF1C8epQ**
+
+[](https://www.bilibili.com/video/BV1zUf2BGEgn/)
+**https://www.bilibili.com/video/BV1zUf2BGEgn/**
+
+---
+
+## Architektur
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ index.ts (Einstiegspunkt) │
+│ Plugin-Registrierung · Config-Parsing · Lifecycle-Hooks│
+└────────┬──────────┬──────────┬──────────┬───────────────┘
+ │ │ │ │
+ ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
+ │ store │ │embedder│ │retriever│ │ scopes │
+ │ .ts │ │ .ts │ │ .ts │ │ .ts │
+ └────────┘ └────────┘ └────────┘ └─────────────┘
+ │ │
+ ┌────▼───┐ ┌─────▼──────────┐
+ │migrate │ │noise-filter.ts │
+ │ .ts │ │adaptive- │
+ └────────┘ │retrieval.ts │
+ └────────────────┘
+ ┌─────────────┐ ┌──────────┐
+ │ tools.ts │ │ cli.ts │
+ │ (Agent-API) │ │ (CLI) │
+ └─────────────┘ └──────────┘
+```
+
+> Für eine detaillierte Analyse der vollständigen Architektur siehe [docs/memory_architecture_analysis.md](docs/memory_architecture_analysis.md).
+
+Telegram-Bot-Schnellimport (zum Aufklappen klicken)
+ +Wenn Sie die Telegram-Integration von OpenClaw verwenden, ist es am einfachsten, einen Importbefehl direkt an den Hauptbot zu senden, anstatt die Konfiguration manuell zu bearbeiten. + +Senden Sie diese Nachricht: + +```text +Help me connect this memory plugin with the most user-friendly configuration: https://github.com/CortexReach/memory-lancedb-pro + +Requirements: +1. Set it as the only active memory plugin +2. Use Jina for embedding +3. Use Jina for reranker +4. Use gpt-4o-mini for the smart-extraction LLM +5. Enable autoCapture, autoRecall, smartExtraction +6. extractMinMessages=2 +7. sessionMemory.enabled=false +8. captureAssistant=false +9. retrieval mode=hybrid, vectorWeight=0.7, bm25Weight=0.3 +10. rerank=cross-encoder, candidatePoolSize=12, minScore=0.6, hardMinScore=0.62 +11. Generate the final openclaw.json config directly, not just an explanation +``` + +
+
+
+---
+
+## Kernfunktionen
+
+### Hybride Suche
+
+```
+Query → embedQuery() ─┐
+ ├─→ Hybride Fusion → Rerank → Lifecycle-Zerfall-Boost → Längennorm → Filter
+Query → BM25 FTS ─────┘
+```
+
+- **Vektorsuche** — semantische Ähnlichkeit über LanceDB ANN (Kosinus-Distanz)
+- **BM25 Volltextsuche** — exakte Schlüsselwortübereinstimmung über LanceDB FTS-Index
+- **Hybride Fusion** — Vektorscore als Basis, BM25-Treffer erhalten gewichteten Boost (kein Standard-RRF — optimiert für reale Abrufqualität)
+- **Konfigurierbare Gewichte** — `vectorWeight`, `bm25Weight`, `minScore`
+
+### Cross-Encoder Reranking
+
+- Eingebaute Adapter für **Jina**, **SiliconFlow**, **Voyage AI** und **Pinecone**
+- Kompatibel mit jedem Jina-kompatiblen Endpunkt (z.B. Hugging Face TEI, DashScope)
+- Hybrid-Scoring: 60% Cross-Encoder + 40% ursprünglicher fusionierter Score
+- Graceful Degradation: Rückfall auf Kosinus-Ähnlichkeit bei API-Ausfall
+
+### Mehrstufige Scoring-Pipeline
+
+| Stufe | Effekt |
+| --- | --- |
+| **Hybride Fusion** | Kombiniert semantische und exakte Suche |
+| **Cross-Encoder Rerank** | Fördert semantisch präzise Treffer |
+| **Lifecycle-Zerfall-Boost** | Weibull-Aktualität + Zugriffshäufigkeit + Wichtigkeit × Konfidenz |
+| **Längennormalisierung** | Verhindert, dass lange Einträge dominieren (Anker: 500 Zeichen) |
+| **Harter Mindestscore** | Entfernt irrelevante Ergebnisse (Standard: 0.35) |
+| **MMR-Diversität** | Kosinus-Ähnlichkeit > 0.85 → herabgestuft |
+
+### Intelligente Gedächtnisextraktion (v1.1.0)
+
+- **LLM-gestützte 6-Kategorien-Extraktion**: Profil, Präferenzen, Entitäten, Ereignisse, Fälle, Muster
+- **L0/L1/L2 Schichtspeicherung**: L0 (Einzeiler-Index) → L1 (strukturierte Zusammenfassung) → L2 (vollständige Erzählung)
+- **Zweistufige Deduplizierung**: Vektor-Ähnlichkeits-Vorfilter (≥0.7) → LLM semantische Entscheidung (CREATE/MERGE/SKIP)
+- **Kategoriebasierte Zusammenführung**: `profile` wird immer zusammengeführt, `events`/`cases` sind nur anfügbar
+
+### Gedächtnis-Lebenszyklusverwaltung (v1.1.0)
+
+- **Weibull-Zerfallsmotor**: Gesamtscore = Aktualität + Häufigkeit + intrinsischer Wert
+- **Dreistufige Beförderung**: `Peripheral ↔ Working ↔ Core` mit konfigurierbaren Schwellenwerten
+- **Zugriffsverstärkung**: Häufig abgerufene Erinnerungen zerfallen langsamer (Spaced-Repetition-Stil)
+- **Wichtigkeitsmodulierte Halbwertszeit**: Wichtige Erinnerungen zerfallen langsamer
+
+### Multi-Scope-Isolation
+
+- Eingebaute Scopes: `global`, `agent:Dateireferenz (zum Aufklappen klicken)
+ +| Datei | Zweck | +| --- | --- | +| `index.ts` | Plugin-Einstiegspunkt. Registriert sich bei der OpenClaw Plugin API, parst Konfiguration, bindet Lifecycle-Hooks ein | +| `openclaw.plugin.json` | Plugin-Metadaten + vollständige JSON-Schema-Konfigurationsdeklaration | +| `cli.ts` | CLI-Befehle: `memory-pro list/search/stats/delete/delete-bulk/export/import/reembed/upgrade/migrate` | +| `src/store.ts` | LanceDB-Speicherschicht. Tabellenerstellung / FTS-Indexierung / Vektorsuche / BM25-Suche / CRUD | +| `src/embedder.ts` | Embedding-Abstraktion. Kompatibel mit jedem OpenAI-kompatiblen API-Anbieter | +| `src/retriever.ts` | Hybride Suchmaschine. Vektor + BM25 → Hybride Fusion → Rerank → Lifecycle-Zerfall → Filter | +| `src/scopes.ts` | Multi-Scope-Zugriffskontrolle | +| `src/tools.ts` | Agent-Tool-Definitionen: `memory_recall`, `memory_store`, `memory_forget`, `memory_update` + Verwaltungstools | +| `src/noise-filter.ts` | Filtert Agent-Ablehnungen, Meta-Fragen, Begrüßungen und minderwertige Inhalte | +| `src/adaptive-retrieval.ts` | Bestimmt, ob eine Abfrage Gedächtnisabruf benötigt | +| `src/migrate.ts` | Migration vom eingebauten `memory-lancedb` zu Pro | +| `src/smart-extractor.ts` | LLM-gestützte 6-Kategorien-Extraktion mit L0/L1/L2 Schichtspeicherung und zweistufiger Deduplizierung | +| `src/decay-engine.ts` | Weibull Stretched-Exponential-Zerfallsmodell | +| `src/tier-manager.ts` | Dreistufige Beförderung/Herabstufung: Peripheral ↔ Working ↔ Core | + +
+Vergleich mit dem eingebauten
+
+| Funktion | Eingebautes `memory-lancedb` | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| Vektorsuche | Ja | Ja |
+| BM25 Volltextsuche | - | Ja |
+| Hybride Fusion (Vektor + BM25) | - | Ja |
+| Cross-Encoder Rerank (Multi-Anbieter) | - | Ja |
+| Aktualitäts-Boost und Zeitzerfall | - | Ja |
+| Längennormalisierung | - | Ja |
+| MMR-Diversität | - | Ja |
+| Multi-Scope-Isolation | - | Ja |
+| Rauschfilterung | - | Ja |
+| Adaptive Suche | - | Ja |
+| Verwaltungs-CLI | - | Ja |
+| Sitzungsgedächtnis | - | Ja |
+| Aufgabenbezogene Embeddings | - | Ja |
+| **LLM Intelligente Extraktion (6 Kategorien)** | - | Ja (v1.1.0) |
+| **Weibull-Zerfall + Stufenbeförderung** | - | Ja (v1.1.0) |
+| Beliebiges OpenAI-kompatibles Embedding | Eingeschränkt | Ja |
+
+
+
+---
+
+## Konfiguration
+
+Vergleich mit dem eingebauten memory-lancedb (zum Aufklappen klicken)
+
+| Funktion | Eingebautes `memory-lancedb` | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| Vektorsuche | Ja | Ja |
+| BM25 Volltextsuche | - | Ja |
+| Hybride Fusion (Vektor + BM25) | - | Ja |
+| Cross-Encoder Rerank (Multi-Anbieter) | - | Ja |
+| Aktualitäts-Boost und Zeitzerfall | - | Ja |
+| Längennormalisierung | - | Ja |
+| MMR-Diversität | - | Ja |
+| Multi-Scope-Isolation | - | Ja |
+| Rauschfilterung | - | Ja |
+| Adaptive Suche | - | Ja |
+| Verwaltungs-CLI | - | Ja |
+| Sitzungsgedächtnis | - | Ja |
+| Aufgabenbezogene Embeddings | - | Ja |
+| **LLM Intelligente Extraktion (6 Kategorien)** | - | Ja (v1.1.0) |
+| **Weibull-Zerfall + Stufenbeförderung** | - | Ja (v1.1.0) |
+| Beliebiges OpenAI-kompatibles Embedding | Eingeschränkt | Ja |
+
+
+
+
+Vollständiges Konfigurationsbeispiel
+ +```json +{ + "embedding": { + "apiKey": "${JINA_API_KEY}", + "model": "jina-embeddings-v5-text-small", + "baseURL": "https://api.jina.ai/v1", + "dimensions": 1024, + "taskQuery": "retrieval.query", + "taskPassage": "retrieval.passage", + "normalized": true + }, + "dbPath": "~/.openclaw/memory/lancedb-pro", + "autoCapture": true, + "autoRecall": true, + "retrieval": { + "mode": "hybrid", + "vectorWeight": 0.7, + "bm25Weight": 0.3, + "minScore": 0.3, + "rerank": "cross-encoder", + "rerankApiKey": "${JINA_API_KEY}", + "rerankModel": "jina-reranker-v3", + "rerankEndpoint": "https://api.jina.ai/v1/rerank", + "rerankProvider": "jina", + "candidatePoolSize": 20, + "recencyHalfLifeDays": 14, + "recencyWeight": 0.1, + "filterNoise": true, + "lengthNormAnchor": 500, + "hardMinScore": 0.35, + "timeDecayHalfLifeDays": 60, + "reinforcementFactor": 0.5, + "maxHalfLifeMultiplier": 3 + }, + "enableManagementTools": false, + "scopes": { + "default": "global", + "definitions": { + "global": { "description": "Shared knowledge" }, + "agent:discord-bot": { "description": "Discord bot private" } + }, + "agentAccess": { + "discord-bot": ["global", "agent:discord-bot"] + } + }, + "sessionMemory": { + "enabled": false, + "messageCount": 15 + }, + "smartExtraction": true, + "llm": { + "apiKey": "${OPENAI_API_KEY}", + "model": "gpt-4o-mini", + "baseURL": "https://api.openai.com/v1" + }, + "extractMinMessages": 2, + "extractMaxChars": 8000 +} +``` + +
+
+
+Embedding-Anbieter
+ +Funktioniert mit **jeder OpenAI-kompatiblen Embedding-API**: + +| Anbieter | Modell | Basis-URL | Dimensionen | +| --- | --- | --- | --- | +| **Jina** (empfohlen) | `jina-embeddings-v5-text-small` | `https://api.jina.ai/v1` | 1024 | +| **OpenAI** | `text-embedding-3-small` | `https://api.openai.com/v1` | 1536 | +| **Voyage** | `voyage-4-lite` / `voyage-4` | `https://api.voyageai.com/v1` | 1024 / 1024 | +| **Google Gemini** | `gemini-embedding-001` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 | +| **Ollama** (lokal) | `nomic-embed-text` | `http://localhost:11434/v1` | anbieterspezifisch | + +
+
+
+Rerank-Anbieter
+ +Cross-Encoder Reranking unterstützt mehrere Anbieter über `rerankProvider`: + +| Anbieter | `rerankProvider` | Beispielmodell | +| --- | --- | --- | +| **Jina** (Standard) | `jina` | `jina-reranker-v3` | +| **SiliconFlow** (kostenlose Stufe verfügbar) | `siliconflow` | `BAAI/bge-reranker-v2-m3` | +| **Voyage AI** | `voyage` | `rerank-2.5` | +| **Pinecone** | `pinecone` | `bge-reranker-v2-m3` | + +Jeder Jina-kompatible Rerank-Endpunkt funktioniert ebenfalls — setzen Sie `rerankProvider: "jina"` und verweisen Sie `rerankEndpoint` auf Ihren Dienst (z.B. Hugging Face TEI, DashScope `qwen3-rerank`). + +
+
+
+Intelligente Extraktion (LLM) — v1.1.0
+ +Wenn `smartExtraction` aktiviert ist (Standard: `true`), verwendet das Plugin ein LLM, um Erinnerungen intelligent zu extrahieren und zu klassifizieren, anstatt regex-basierte Auslöser zu verwenden. + +| Feld | Typ | Standard | Beschreibung | +|-------|------|---------|-------------| +| `smartExtraction` | boolean | `true` | LLM-gestützte 6-Kategorien-Extraktion aktivieren/deaktivieren | +| `llm.auth` | string | `api-key` | `api-key` verwendet `llm.apiKey` / `embedding.apiKey`; `oauth` verwendet standardmäßig eine plugin-spezifische OAuth-Token-Datei | +| `llm.apiKey` | string | *(Rückfall auf `embedding.apiKey`)* | API-Schlüssel für den LLM-Anbieter | +| `llm.model` | string | `openai/gpt-oss-120b` | LLM-Modellname | +| `llm.baseURL` | string | *(Rückfall auf `embedding.baseURL`)* | LLM-API-Endpunkt | +| `llm.oauthProvider` | string | `openai-codex` | OAuth-Anbieter-ID bei `llm.auth` = `oauth` | +| `llm.oauthPath` | string | `~/.openclaw/.memory-lancedb-pro/oauth.json` | OAuth-Token-Datei bei `llm.auth` = `oauth` | +| `llm.timeoutMs` | number | `30000` | LLM-Anfrage-Timeout in Millisekunden | +| `extractMinMessages` | number | `2` | Mindestanzahl an Nachrichten bevor Extraktion ausgelöst wird | +| `extractMaxChars` | number | `8000` | Maximale Zeichenanzahl, die an das LLM gesendet wird | + + +OAuth `llm`-Konfiguration (vorhandenen Codex / ChatGPT Login-Cache für LLM-Aufrufe verwenden): +```json +{ + "llm": { + "auth": "oauth", + "oauthProvider": "openai-codex", + "model": "gpt-5.4", + "oauthPath": "${HOME}/.openclaw/.memory-lancedb-pro/oauth.json", + "timeoutMs": 30000 + } +} +``` + +Hinweise zu `llm.auth: "oauth"`: + +- `llm.oauthProvider` ist derzeit `openai-codex`. +- OAuth-Tokens werden standardmäßig unter `~/.openclaw/.memory-lancedb-pro/oauth.json` gespeichert. +- Sie können `llm.oauthPath` setzen, wenn Sie die Datei an einem anderen Ort speichern möchten. +- `auth login` erstellt eine Sicherung der vorherigen api-key `llm`-Konfiguration neben der OAuth-Datei, und `auth logout` stellt diese Sicherung bei Verfügbarkeit wieder her. +- Der Wechsel von `api-key` zu `oauth` überträgt `llm.baseURL` nicht automatisch. Setzen Sie es im OAuth-Modus nur manuell, wenn Sie absichtlich ein benutzerdefiniertes ChatGPT/Codex-kompatibles Backend verwenden möchten. + +
+
+
+Lebenszyklus-Konfiguration (Zerfall + Stufen)
+ +| Feld | Standard | Beschreibung | +|-------|---------|-------------| +| `decay.recencyHalfLifeDays` | `30` | Basis-Halbwertszeit für Weibull-Aktualitätszerfall | +| `decay.frequencyWeight` | `0.3` | Gewichtung der Zugriffshäufigkeit im Gesamtscore | +| `decay.intrinsicWeight` | `0.3` | Gewichtung von `Wichtigkeit × Konfidenz` | +| `decay.betaCore` | `0.8` | Weibull-Beta für `core`-Erinnerungen | +| `decay.betaWorking` | `1.0` | Weibull-Beta für `working`-Erinnerungen | +| `decay.betaPeripheral` | `1.3` | Weibull-Beta für `peripheral`-Erinnerungen | +| `tier.coreAccessThreshold` | `10` | Mindestanzahl Abrufe vor Beförderung zu `core` | +| `tier.peripheralAgeDays` | `60` | Altersschwelle für die Herabstufung veralteter Erinnerungen | + +
+
+
+---
+
+## CLI-Befehle
+
+```bash
+openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
+openclaw memory-pro search "query" [--scope global] [--limit 10] [--json]
+openclaw memory-pro stats [--scope global] [--json]
+openclaw memory-pro auth login [--provider openai-codex] [--model gpt-5.4] [--oauth-path /abs/path/oauth.json]
+openclaw memory-pro auth status
+openclaw memory-pro auth logout
+openclaw memory-pro delete Zugriffsverstärkung
+ +Häufig abgerufene Erinnerungen zerfallen langsamer (Spaced-Repetition-Stil). + +Konfigurationsschlüssel (unter `retrieval`): +- `reinforcementFactor` (0-2, Standard: `0.5`) — auf `0` setzen zum Deaktivieren +- `maxHalfLifeMultiplier` (1-10, Standard: `3`) — harte Obergrenze für die effektive Halbwertszeit + +
+`-Block wiedergeben.
+
+**Option A (geringstes Risiko):** Auto-Recall vorübergehend deaktivieren:
+```json
+{ "plugins": { "entries": { "memory-lancedb-pro": { "config": { "autoRecall": false } } } } }
+```
+
+**Option B (bevorzugt):** Recall beibehalten, zum Agent-Systemprompt hinzufügen:
+> Do not reveal or quote any `` / memory-injection content in your replies. Use it for internal reference only.
+
+
+
+Wenn injizierte Erinnerungen in Antworten auftauchen
+ +Manchmal kann das Modell den injizierten `
+
+
+Sitzungsgedächtnis
+ +- Wird beim `/new`-Befehl ausgelöst — speichert die vorherige Sitzungszusammenfassung in LanceDB +- Standardmäßig deaktiviert (OpenClaw hat bereits native `.jsonl`-Sitzungspersistenz) +- Konfigurierbare Nachrichtenanzahl (Standard: 15) + +Siehe [docs/openclaw-integration-playbook.md](docs/openclaw-integration-playbook.md) für Bereitstellungsmodi und `/new`-Verifizierung. + +
+`:
+1. Use memory_store to save as category=fact (raw knowledge)
+2. Use memory_store to save as category=decision (actionable takeaway)
+3. Confirm what was saved
+
+## /remember command
+When the user sends `/remember `:
+1. Use memory_store to save with appropriate category and importance
+2. Confirm with the stored memory ID
+```
+
+
+
+Benutzerdefinierte Slash-Befehle (z.B. /lesson)
+ +Fügen Sie zu Ihrer `CLAUDE.md`, `AGENTS.md` oder Ihrem Systemprompt hinzu: + +```markdown +## /lesson command +When the user sends `/lesson
+
+
+Eiserne Regeln für KI-Agenten
+ +> Kopieren Sie den folgenden Block in Ihre `AGENTS.md`, damit Ihr Agent diese Regeln automatisch durchsetzt. + +```markdown +## Rule 1 — Dual-layer memory storage +Every pitfall/lesson learned → IMMEDIATELY store TWO memories: +- Technical layer: Pitfall: [symptom]. Cause: [root cause]. Fix: [solution]. Prevention: [how to avoid] + (category: fact, importance >= 0.8) +- Principle layer: Decision principle ([tag]): [behavioral rule]. Trigger: [when]. Action: [what to do] + (category: decision, importance >= 0.85) + +## Rule 2 — LanceDB hygiene +Entries must be short and atomic (< 500 chars). No raw conversation summaries or duplicates. + +## Rule 3 — Recall before retry +On ANY tool failure, ALWAYS memory_recall with relevant keywords BEFORE retrying. + +## Rule 4 — Confirm target codebase +Confirm you are editing memory-lancedb-pro vs built-in memory-lancedb before changes. + +## Rule 5 — Clear jiti cache after plugin code changes +After modifying .ts files under plugins/, MUST run rm -rf /tmp/jiti/ BEFORE openclaw gateway restart. +``` + +
+
+
+Datenbankschema
+ +LanceDB-Tabelle `memories`: + +| Feld | Typ | Beschreibung | +| --- | --- | --- | +| `id` | string (UUID) | Primärschlüssel | +| `text` | string | Gedächtnistext (FTS-indiziert) | +| `vector` | float[] | Embedding-Vektor | +| `category` | string | Speicherkategorie: `preference` / `fact` / `decision` / `entity` / `reflection` / `other` | +| `scope` | string | Scope-Bezeichner (z.B. `global`, `agent:main`) | +| `importance` | float | Wichtigkeitsscore 0-1 | +| `timestamp` | int64 | Erstellungszeitstempel (ms) | +| `metadata` | string (JSON) | Erweiterte Metadaten | + +Häufige `metadata`-Schlüssel in v1.1.0: `l0_abstract`, `l1_overview`, `l2_content`, `memory_category`, `tier`, `access_count`, `confidence`, `last_accessed_at` + +> **Hinweis zu Kategorien:** Das Top-Level-Feld `category` verwendet 6 Speicherkategorien. Die 6-Kategorien-semantischen Labels der intelligenten Extraktion (`profile` / `preferences` / `entities` / `events` / `cases` / `patterns`) werden in `metadata.memory_category` gespeichert. + +
+
+
+---
+
+## Dokumentation
+
+| Dokument | Beschreibung |
+| --- | --- |
+| [OpenClaw Integrations-Playbook](docs/openclaw-integration-playbook.md) | Bereitstellungsmodi, Verifizierung, Regressionsmatrix |
+| [Gedächtnisarchitektur-Analyse](docs/memory_architecture_analysis.md) | Vollständige Architektur-Tiefenanalyse |
+| [CHANGELOG v1.1.0](docs/CHANGELOG-v1.1.0.md) | Verhaltensänderungen v1.1.0 und Upgrade-Begründung |
+| [Langkontext-Chunking](docs/long-context-chunking.md) | Chunking-Strategie für lange Dokumente |
+
+---
+
+## Beta: Smart Memory v1.1.0
+
+> Status: Beta — verfügbar über `npm i memory-lancedb-pro@beta`. Stabile Benutzer auf `latest` sind nicht betroffen.
+
+| Funktion | Beschreibung |
+|---------|-------------|
+| **Intelligente Extraktion** | LLM-gestützte 6-Kategorien-Extraktion mit L0/L1/L2 Metadaten. Rückfall auf Regex wenn deaktiviert. |
+| **Lebenszyklus-Scoring** | Weibull-Zerfall in die Suche integriert — häufige und wichtige Erinnerungen ranken höher. |
+| **Stufenverwaltung** | Dreistufiges System (Core → Working → Peripheral) mit automatischer Beförderung/Herabstufung. |
+
+Feedback: [GitHub Issues](https://github.com/CortexReach/memory-lancedb-pro/issues) · Zurücksetzen: `npm i memory-lancedb-pro@latest`
+
+---
+
+## Abhängigkeiten
+
+| Paket | Zweck |
+| --- | --- |
+| `@lancedb/lancedb` ≥0.26.2 | Vektordatenbank (ANN + FTS) |
+| `openai` ≥6.21.0 | OpenAI-kompatibler Embedding-API-Client |
+| `@sinclair/typebox` 0.34.48 | JSON-Schema-Typdefinitionen |
+
+---
+
+## Contributors
+
+Fehlerbehebung
+ +### "Cannot mix BigInt and other types" (LanceDB / Apache Arrow) + +Bei LanceDB 0.26+ können einige numerische Spalten als `BigInt` zurückgegeben werden. Aktualisieren Sie auf **memory-lancedb-pro >= 1.0.14** — dieses Plugin konvertiert Werte nun mit `Number(...)` vor arithmetischen Operationen. + +
+
+
+# 🧠 memory-lancedb-pro · 🦞OpenClaw Plugin
+
+**Asistente de Memoria IA para Agentes [OpenClaw](https://github.com/openclaw/openclaw)**
+
+*Dale a tu agente de IA un cerebro que realmente recuerda — entre sesiones, entre agentes, a lo largo del tiempo.*
+
+Un plugin de memoria para OpenClaw respaldado por LanceDB que almacena preferencias, decisiones y contexto de proyectos, y los recupera automáticamente en sesiones futuras.
+
+[](https://github.com/openclaw/openclaw)
+[](https://www.npmjs.com/package/memory-lancedb-pro)
+[](https://lancedb.com)
+[](LICENSE)
+
+[English](README.md) | [简体中文](README_CN.md) | [繁體中文](README_TW.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | [Español](README_ES.md) | [Deutsch](README_DE.md) | [Italiano](README_IT.md) | [Русский](README_RU.md) | [Português (Brasil)](README_PT-BR.md)
+
+
+
+---
+
+## ¿Por qué memory-lancedb-pro?
+
+La mayoría de los agentes de IA tienen amnesia. Olvidan todo en el momento en que inicias un nuevo chat.
+
+**memory-lancedb-pro** es un plugin de memoria a largo plazo de nivel productivo para OpenClaw que convierte a tu agente en un **Asistente de Memoria IA** — captura automáticamente lo que importa, deja que el ruido se desvanezca naturalmente y recupera el recuerdo correcto en el momento adecuado. Sin etiquetado manual, sin complicaciones de configuración.
+
+### Tu Asistente de Memoria IA en acción
+
+**Sin memoria — cada sesión comienza desde cero:**
+
+> **Tú:** "Usa tabulaciones para la indentación, siempre agrega manejo de errores."
+> *(siguiente sesión)*
+> **Tú:** "¡Ya te lo dije — tabulaciones, no espacios!" 😤
+> *(siguiente sesión)*
+> **Tú:** "...en serio, tabulaciones. Y manejo de errores. Otra vez."
+
+**Con memory-lancedb-pro — tu agente aprende y recuerda:**
+
+> **Tú:** "Usa tabulaciones para la indentación, siempre agrega manejo de errores."
+> *(siguiente sesión — el agente recupera automáticamente tus preferencias)*
+> **Agente:** *(aplica silenciosamente tabulaciones + manejo de errores)* ✅
+> **Tú:** "¿Por qué elegimos PostgreSQL en lugar de MongoDB el mes pasado?"
+> **Agente:** "Basándome en nuestra discusión del 12 de febrero, las razones principales fueron..." ✅
+
+Esa es la diferencia que hace un **Asistente de Memoria IA** — aprende tu estilo, recuerda decisiones pasadas y entrega respuestas personalizadas sin que tengas que repetirte.
+
+### ¿Qué más puede hacer?
+
+| | Lo que obtienes |
+|---|---|
+| **Auto-Capture** | Tu agente aprende de cada conversación — sin necesidad de `memory_store` manual |
+| **Smart Extraction** | Clasificación de 6 categorías impulsada por LLM: perfiles, preferencias, entidades, eventos, casos, patrones |
+| **Olvido Inteligente** | Modelo de decaimiento Weibull — los recuerdos importantes permanecen, el ruido se desvanece naturalmente |
+| **Recuperación Híbrida** | Búsqueda vectorial + BM25 de texto completo, fusionada con reranking por cross-encoder |
+| **Inyección de Contexto** | Los recuerdos relevantes aparecen automáticamente antes de cada respuesta |
+| **Aislamiento Multi-Scope** | Límites de memoria por agente, por usuario, por proyecto |
+| **Cualquier Proveedor** | OpenAI, Jina, Gemini, Ollama, o cualquier API compatible con OpenAI |
+| **Kit Completo de Herramientas** | CLI, respaldo, migración, actualización, exportar/importar — listo para producción |
+
+---
+
+## Inicio Rápido
+
+### Opción A: Script de instalación con un clic (Recomendado)
+
+El **[script de instalación](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)** mantenido por la comunidad gestiona la instalación, actualización y reparación en un solo comando:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
+bash setup-memory.sh
+```
+
+> Consulta [Ecosistema](#ecosistema) más abajo para ver la lista completa de escenarios que cubre el script y otras herramientas de la comunidad.
+
+### Opción B: Instalación Manual
+
+**Mediante la CLI de OpenClaw (recomendado):**
+```bash
+openclaw plugins install memory-lancedb-pro@beta
+```
+
+**O mediante npm:**
+```bash
+npm i memory-lancedb-pro@beta
+```
+> Si usas npm, también necesitarás agregar el directorio de instalación del plugin como una ruta **absoluta** en `plugins.load.paths` en tu `openclaw.json`. Este es el problema de configuración más común.
+
+Agrega a tu `openclaw.json`:
+
+```json
+{
+ "plugins": {
+ "slots": { "memory": "memory-lancedb-pro" },
+ "entries": {
+ "memory-lancedb-pro": {
+ "enabled": true,
+ "config": {
+ "embedding": {
+ "provider": "openai-compatible",
+ "apiKey": "${OPENAI_API_KEY}",
+ "model": "text-embedding-3-small"
+ },
+ "autoCapture": true,
+ "autoRecall": true,
+ "smartExtraction": true,
+ "extractMinMessages": 2,
+ "extractMaxChars": 8000,
+ "sessionMemory": { "enabled": false }
+ }
+ }
+ }
+ }
+}
+```
+
+**¿Por qué estos valores predeterminados?**
+- `autoCapture` + `smartExtraction` → tu agente aprende de cada conversación automáticamente
+- `autoRecall` → los recuerdos relevantes se inyectan antes de cada respuesta
+- `extractMinMessages: 2` → la extracción se activa en chats normales de dos turnos
+- `sessionMemory.enabled: false` → evita contaminar la recuperación con resúmenes de sesión desde el primer día
+
+Valida y reinicia:
+
+```bash
+openclaw config validate
+openclaw gateway restart
+openclaw logs --follow --plain | grep "memory-lancedb-pro"
+```
+
+Deberías ver:
+- `memory-lancedb-pro: smart extraction enabled`
+- `memory-lancedb-pro@...: plugin registered`
+
+¡Listo! Tu agente ahora tiene memoria a largo plazo.
+
+
+
+
+Más rutas de instalación (usuarios existentes, actualizaciones)
+ +**¿Ya usas OpenClaw?** + +1. Agrega el plugin con una entrada **absoluta** en `plugins.load.paths` +2. Vincula el slot de memoria: `plugins.slots.memory = "memory-lancedb-pro"` +3. Verifica: `openclaw plugins info memory-lancedb-pro && openclaw memory-pro stats` + +**¿Actualizando desde una versión anterior a v1.1.0?** + +```bash +# 1) Respaldo +openclaw memory-pro export --scope global --output memories-backup.json +# 2) Ejecución de prueba +openclaw memory-pro upgrade --dry-run +# 3) Ejecutar actualización +openclaw memory-pro upgrade +# 4) Verificar +openclaw memory-pro stats +``` + +Consulta `CHANGELOG-v1.1.0.md` para los cambios de comportamiento y la justificación de la actualización. + +
+
+
+---
+
+## Ecosistema
+
+memory-lancedb-pro es el plugin principal. La comunidad ha desarrollado herramientas a su alrededor para hacer que la configuración y el uso diario sean aún más sencillos:
+
+### Script de Instalación — Instala, actualiza y repara con un solo clic
+
+> **[CortexReach/toolbox/memory-lancedb-pro-setup](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)**
+
+Mucho más que un simple instalador — el script gestiona de forma inteligente una amplia variedad de escenarios reales:
+
+| Tu situación | Lo que hace el script |
+|---|---|
+| Nunca instalado | Descarga nueva → instala dependencias → elige configuración → escribe en openclaw.json → reinicia |
+| Instalado vía `git clone`, atascado en un commit antiguo | `git fetch` + `checkout` automático a la última versión → reinstala dependencias → verifica |
+| La configuración tiene campos inválidos | Auto-detección mediante filtro de esquema, elimina campos no soportados |
+| Instalado vía `npm` | Omite la actualización de git, te recuerda ejecutar `npm update` por tu cuenta |
+| CLI de `openclaw` rota por configuración inválida | Alternativa: lee la ruta del workspace directamente del archivo `openclaw.json` |
+| `extensions/` en lugar de `plugins/` | Auto-detección de la ubicación del plugin desde la configuración o el sistema de archivos |
+| Ya está actualizado | Solo ejecuta verificaciones de salud, sin cambios |
+
+```bash
+bash setup-memory.sh # Instalar o actualizar
+bash setup-memory.sh --dry-run # Solo previsualización
+bash setup-memory.sh --beta # Incluir versiones preliminares
+bash setup-memory.sh --uninstall # Revertir configuración y eliminar plugin
+```
+
+Configuraciones preestablecidas de proveedores: **Jina / DashScope / SiliconFlow / OpenAI / Ollama**, o usa tu propia API compatible con OpenAI. Para la referencia completa (incluyendo `--ref`, `--selfcheck-only` y más), consulta el [README del script de instalación](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup).
+
+### Skill para Claude Code / OpenClaw — Configuración Guiada por IA
+
+> **[CortexReach/memory-lancedb-pro-skill](https://github.com/CortexReach/memory-lancedb-pro-skill)**
+
+Instala este skill y tu agente de IA (Claude Code u OpenClaw) obtiene un conocimiento profundo de cada característica de memory-lancedb-pro. Solo di **"ayúdame a habilitar la mejor configuración"** y obtén:
+
+- **Flujo de configuración guiado en 7 pasos** con 4 planes de despliegue:
+ - Potencia Total (Jina + OpenAI) / Económico (reranker gratuito de SiliconFlow) / Simple (solo OpenAI) / Totalmente Local (Ollama, sin costo de API)
+- **Las 9 herramientas MCP** usadas correctamente: `memory_recall`, `memory_store`, `memory_forget`, `memory_update`, `memory_stats`, `memory_list`, `self_improvement_log`, `self_improvement_extract_skill`, `self_improvement_review` *(el conjunto completo de herramientas requiere `enableManagementTools: true` — la configuración de Inicio Rápido predeterminada expone las 4 herramientas principales)*
+- **Prevención de errores comunes**: habilitación del plugin en el workspace, `autoRecall` desactivado por defecto, caché de jiti, variables de entorno, aislamiento de scope, y más
+
+**Instalar para Claude Code:**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro
+```
+
+**Instalar para OpenClaw:**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill
+```
+
+---
+
+## Tutorial en Video
+
+> Recorrido completo: instalación, configuración y funcionamiento interno de la recuperación híbrida.
+
+[](https://youtu.be/MtukF1C8epQ)
+**https://youtu.be/MtukF1C8epQ**
+
+[](https://www.bilibili.com/video/BV1zUf2BGEgn/)
+**https://www.bilibili.com/video/BV1zUf2BGEgn/**
+
+---
+
+## Arquitectura
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ index.ts (Entry Point) │
+│ Plugin Registration · Config Parsing · Lifecycle Hooks │
+└────────┬──────────┬──────────┬──────────┬───────────────┘
+ │ │ │ │
+ ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
+ │ store │ │embedder│ │retriever│ │ scopes │
+ │ .ts │ │ .ts │ │ .ts │ │ .ts │
+ └────────┘ └────────┘ └────────┘ └─────────────┘
+ │ │
+ ┌────▼───┐ ┌─────▼──────────┐
+ │migrate │ │noise-filter.ts │
+ │ .ts │ │adaptive- │
+ └────────┘ │retrieval.ts │
+ └────────────────┘
+ ┌─────────────┐ ┌──────────┐
+ │ tools.ts │ │ cli.ts │
+ │ (Agent API) │ │ (CLI) │
+ └─────────────┘ └──────────┘
+```
+
+> Para un análisis detallado de la arquitectura completa, consulta [docs/memory_architecture_analysis.md](docs/memory_architecture_analysis.md).
+
+Importación rápida para Bot de Telegram (clic para expandir)
+ +Si usas la integración de Telegram de OpenClaw, la forma más fácil es enviar un comando de importación directamente al Bot principal en lugar de editar la configuración manualmente. + +Envía este mensaje (en inglés, ya que es un prompt para el bot): + +```text +Help me connect this memory plugin with the most user-friendly configuration: https://github.com/CortexReach/memory-lancedb-pro + +Requirements: +1. Set it as the only active memory plugin +2. Use Jina for embedding +3. Use Jina for reranker +4. Use gpt-4o-mini for the smart-extraction LLM +5. Enable autoCapture, autoRecall, smartExtraction +6. extractMinMessages=2 +7. sessionMemory.enabled=false +8. captureAssistant=false +9. retrieval mode=hybrid, vectorWeight=0.7, bm25Weight=0.3 +10. rerank=cross-encoder, candidatePoolSize=12, minScore=0.6, hardMinScore=0.62 +11. Generate the final openclaw.json config directly, not just an explanation +``` + +
+
+
+---
+
+## Características Principales
+
+### Recuperación Híbrida
+
+```
+Query → embedQuery() ─┐
+ ├─→ Hybrid Fusion → Rerank → Lifecycle Decay Boost → Length Norm → Filter
+Query → BM25 FTS ─────┘
+```
+
+- **Búsqueda Vectorial** — similitud semántica mediante LanceDB ANN (distancia coseno)
+- **Búsqueda de Texto Completo BM25** — coincidencia exacta de palabras clave mediante índice FTS de LanceDB
+- **Fusión Híbrida** — puntuación vectorial como base, los resultados de BM25 reciben un impulso ponderado (no es RRF estándar — ajustado para calidad de recuperación en el mundo real)
+- **Pesos Configurables** — `vectorWeight`, `bm25Weight`, `minScore`
+
+### Reranking con Cross-Encoder
+
+- Adaptadores integrados para **Jina**, **SiliconFlow**, **Voyage AI** y **Pinecone**
+- Compatible con cualquier endpoint compatible con Jina (por ejemplo, Hugging Face TEI, DashScope)
+- Puntuación híbrida: 60% cross-encoder + 40% puntuación fusionada original
+- Degradación elegante: recurre a similitud coseno en caso de fallo de la API
+
+### Pipeline de Puntuación Multi-Etapa
+
+| Etapa | Efecto |
+| --- | --- |
+| **Fusión Híbrida** | Combina recuperación semántica y de coincidencia exacta |
+| **Rerank con Cross-Encoder** | Promueve resultados semánticamente precisos |
+| **Impulso por Decaimiento de Ciclo de Vida** | Frescura Weibull + frecuencia de acceso + importancia × confianza |
+| **Normalización de Longitud** | Evita que entradas largas dominen (ancla: 500 caracteres) |
+| **Puntuación Mínima Estricta** | Elimina resultados irrelevantes (predeterminado: 0.35) |
+| **Diversidad MMR** | Similitud coseno > 0.85 → degradado |
+
+### Extracción Inteligente de Memoria (v1.1.0)
+
+- **Extracción de 6 Categorías con LLM**: perfil, preferencias, entidades, eventos, casos, patrones
+- **Almacenamiento en Capas L0/L1/L2**: L0 (índice de una oración) → L1 (resumen estructurado) → L2 (narrativa completa)
+- **Deduplicación en Dos Etapas**: pre-filtro de similitud vectorial (≥0.7) → decisión semántica por LLM (CREATE/MERGE/SKIP)
+- **Fusión por Categoría**: `profile` siempre se fusiona, `events`/`cases` son solo de adición
+
+### Gestión del Ciclo de Vida de la Memoria (v1.1.0)
+
+- **Motor de Decaimiento Weibull**: puntuación compuesta = recencia + frecuencia + valor intrínseco
+- **Promoción en Tres Niveles**: `Peripheral ↔ Working ↔ Core` con umbrales configurables
+- **Refuerzo por Acceso**: los recuerdos frecuentemente recuperados decaen más lentamente (estilo repetición espaciada)
+- **Vida Media Modulada por Importancia**: los recuerdos importantes decaen más lentamente
+
+### Aislamiento Multi-Scope
+
+- Scopes integrados: `global`, `agent:Referencia de Archivos (clic para expandir)
+ +| Archivo | Propósito | +| --- | --- | +| `index.ts` | Punto de entrada del plugin. Se registra con la API de Plugins de OpenClaw, analiza la configuración, monta hooks de ciclo de vida | +| `openclaw.plugin.json` | Metadatos del plugin + declaración completa de configuración con JSON Schema | +| `cli.ts` | Comandos CLI: `memory-pro list/search/stats/delete/delete-bulk/export/import/reembed/upgrade/migrate` | +| `src/store.ts` | Capa de almacenamiento LanceDB. Creación de tablas / Indexación FTS / Búsqueda vectorial / Búsqueda BM25 / CRUD | +| `src/embedder.ts` | Abstracción de embeddings. Compatible con cualquier proveedor de API compatible con OpenAI | +| `src/retriever.ts` | Motor de recuperación híbrida. Vector + BM25 → Fusión Híbrida → Rerank → Decaimiento de Ciclo de Vida → Filtro | +| `src/scopes.ts` | Control de acceso multi-scope | +| `src/tools.ts` | Definiciones de herramientas del agente: `memory_recall`, `memory_store`, `memory_forget`, `memory_update` + herramientas de gestión | +| `src/noise-filter.ts` | Filtra rechazos del agente, meta-preguntas, saludos y contenido de baja calidad | +| `src/adaptive-retrieval.ts` | Determina si una consulta necesita recuperación de memoria | +| `src/migrate.ts` | Migración desde `memory-lancedb` integrado a Pro | +| `src/smart-extractor.ts` | Extracción de 6 categorías impulsada por LLM con almacenamiento en capas L0/L1/L2 y deduplicación en dos etapas | +| `src/decay-engine.ts` | Modelo de decaimiento exponencial estirado de Weibull | +| `src/tier-manager.ts` | Promoción/degradación en tres niveles: Peripheral ↔ Working ↔ Core | + +
+Comparación con
+
+| Característica | `memory-lancedb` integrado | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| Búsqueda vectorial | Sí | Sí |
+| Búsqueda de texto completo BM25 | - | Sí |
+| Fusión híbrida (Vector + BM25) | - | Sí |
+| Rerank con cross-encoder (multi-proveedor) | - | Sí |
+| Impulso por recencia y decaimiento temporal | - | Sí |
+| Normalización de longitud | - | Sí |
+| Diversidad MMR | - | Sí |
+| Aislamiento multi-scope | - | Sí |
+| Filtrado de ruido | - | Sí |
+| Recuperación adaptativa | - | Sí |
+| CLI de gestión | - | Sí |
+| Memoria de sesión | - | Sí |
+| Embeddings adaptados a la tarea | - | Sí |
+| **Extracción Inteligente con LLM (6 categorías)** | - | Sí (v1.1.0) |
+| **Decaimiento Weibull + Promoción por Niveles** | - | Sí (v1.1.0) |
+| Cualquier embedding compatible con OpenAI | Limitado | Sí |
+
+
+
+---
+
+## Configuración
+
+Comparación con memory-lancedb integrado (clic para expandir)
+
+| Característica | `memory-lancedb` integrado | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| Búsqueda vectorial | Sí | Sí |
+| Búsqueda de texto completo BM25 | - | Sí |
+| Fusión híbrida (Vector + BM25) | - | Sí |
+| Rerank con cross-encoder (multi-proveedor) | - | Sí |
+| Impulso por recencia y decaimiento temporal | - | Sí |
+| Normalización de longitud | - | Sí |
+| Diversidad MMR | - | Sí |
+| Aislamiento multi-scope | - | Sí |
+| Filtrado de ruido | - | Sí |
+| Recuperación adaptativa | - | Sí |
+| CLI de gestión | - | Sí |
+| Memoria de sesión | - | Sí |
+| Embeddings adaptados a la tarea | - | Sí |
+| **Extracción Inteligente con LLM (6 categorías)** | - | Sí (v1.1.0) |
+| **Decaimiento Weibull + Promoción por Niveles** | - | Sí (v1.1.0) |
+| Cualquier embedding compatible con OpenAI | Limitado | Sí |
+
+
+
+
+Ejemplo de Configuración Completa
+ +```json +{ + "embedding": { + "apiKey": "${JINA_API_KEY}", + "model": "jina-embeddings-v5-text-small", + "baseURL": "https://api.jina.ai/v1", + "dimensions": 1024, + "taskQuery": "retrieval.query", + "taskPassage": "retrieval.passage", + "normalized": true + }, + "dbPath": "~/.openclaw/memory/lancedb-pro", + "autoCapture": true, + "autoRecall": true, + "retrieval": { + "mode": "hybrid", + "vectorWeight": 0.7, + "bm25Weight": 0.3, + "minScore": 0.3, + "rerank": "cross-encoder", + "rerankApiKey": "${JINA_API_KEY}", + "rerankModel": "jina-reranker-v3", + "rerankEndpoint": "https://api.jina.ai/v1/rerank", + "rerankProvider": "jina", + "candidatePoolSize": 20, + "recencyHalfLifeDays": 14, + "recencyWeight": 0.1, + "filterNoise": true, + "lengthNormAnchor": 500, + "hardMinScore": 0.35, + "timeDecayHalfLifeDays": 60, + "reinforcementFactor": 0.5, + "maxHalfLifeMultiplier": 3 + }, + "enableManagementTools": false, + "scopes": { + "default": "global", + "definitions": { + "global": { "description": "Shared knowledge" }, + "agent:discord-bot": { "description": "Discord bot private" } + }, + "agentAccess": { + "discord-bot": ["global", "agent:discord-bot"] + } + }, + "sessionMemory": { + "enabled": false, + "messageCount": 15 + }, + "smartExtraction": true, + "llm": { + "apiKey": "${OPENAI_API_KEY}", + "model": "gpt-4o-mini", + "baseURL": "https://api.openai.com/v1" + }, + "extractMinMessages": 2, + "extractMaxChars": 8000 +} +``` + +
+
+
+Proveedores de Embedding
+ +Funciona con **cualquier API de embedding compatible con OpenAI**: + +| Proveedor | Modelo | URL Base | Dimensiones | +| --- | --- | --- | --- | +| **Jina** (recomendado) | `jina-embeddings-v5-text-small` | `https://api.jina.ai/v1` | 1024 | +| **OpenAI** | `text-embedding-3-small` | `https://api.openai.com/v1` | 1536 | +| **Voyage** | `voyage-4-lite` / `voyage-4` | `https://api.voyageai.com/v1` | 1024 / 1024 | +| **Google Gemini** | `gemini-embedding-001` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 | +| **Ollama** (local) | `nomic-embed-text` | `http://localhost:11434/v1` | específico del proveedor | + +
+
+
+Proveedores de Rerank
+ +El reranking con cross-encoder admite múltiples proveedores mediante `rerankProvider`: + +| Proveedor | `rerankProvider` | Modelo de Ejemplo | +| --- | --- | --- | +| **Jina** (predeterminado) | `jina` | `jina-reranker-v3` | +| **SiliconFlow** (nivel gratuito disponible) | `siliconflow` | `BAAI/bge-reranker-v2-m3` | +| **Voyage AI** | `voyage` | `rerank-2.5` | +| **Pinecone** | `pinecone` | `bge-reranker-v2-m3` | + +Cualquier endpoint de rerank compatible con Jina también funciona — configura `rerankProvider: "jina"` y apunta `rerankEndpoint` a tu servicio (por ejemplo, Hugging Face TEI, DashScope `qwen3-rerank`). + +
+
+
+Smart Extraction (LLM) — v1.1.0
+ +Cuando `smartExtraction` está habilitado (predeterminado: `true`), el plugin utiliza un LLM para extraer y clasificar recuerdos de forma inteligente en lugar de disparadores basados en regex. + +| Campo | Tipo | Predeterminado | Descripción | +|-------|------|----------------|-------------| +| `smartExtraction` | boolean | `true` | Habilitar/deshabilitar la extracción de 6 categorías impulsada por LLM | +| `llm.auth` | string | `api-key` | `api-key` usa `llm.apiKey` / `embedding.apiKey`; `oauth` usa un archivo de token OAuth con alcance de plugin por defecto | +| `llm.apiKey` | string | *(recurre a `embedding.apiKey`)* | Clave API para el proveedor de LLM | +| `llm.model` | string | `openai/gpt-oss-120b` | Nombre del modelo LLM | +| `llm.baseURL` | string | *(recurre a `embedding.baseURL`)* | Endpoint de la API del LLM | +| `llm.oauthProvider` | string | `openai-codex` | ID del proveedor OAuth usado cuando `llm.auth` es `oauth` | +| `llm.oauthPath` | string | `~/.openclaw/.memory-lancedb-pro/oauth.json` | Archivo de token OAuth usado cuando `llm.auth` es `oauth` | +| `llm.timeoutMs` | number | `30000` | Tiempo de espera de solicitud LLM en milisegundos | +| `extractMinMessages` | number | `2` | Mensajes mínimos antes de que se active la extracción | +| `extractMaxChars` | number | `8000` | Máximo de caracteres enviados al LLM | + + +Configuración de `llm` con OAuth (usa la caché de inicio de sesión existente de Codex / ChatGPT para llamadas al LLM): +```json +{ + "llm": { + "auth": "oauth", + "oauthProvider": "openai-codex", + "model": "gpt-5.4", + "oauthPath": "${HOME}/.openclaw/.memory-lancedb-pro/oauth.json", + "timeoutMs": 30000 + } +} +``` + +Notas para `llm.auth: "oauth"`: + +- `llm.oauthProvider` es actualmente `openai-codex`. +- Los tokens OAuth se almacenan por defecto en `~/.openclaw/.memory-lancedb-pro/oauth.json`. +- Puedes configurar `llm.oauthPath` si deseas almacenar ese archivo en otra ubicación. +- `auth login` guarda una copia de la configuración anterior de `llm` con api-key junto al archivo OAuth, y `auth logout` restaura esa copia cuando está disponible. +- Cambiar de `api-key` a `oauth` no transfiere automáticamente `llm.baseURL`. Configúralo manualmente en modo OAuth solo cuando intencionalmente quieras un backend personalizado compatible con ChatGPT/Codex. + +
+
+
+Configuración del Ciclo de Vida (Decaimiento + Nivel)
+ +| Campo | Predeterminado | Descripción | +|-------|----------------|-------------| +| `decay.recencyHalfLifeDays` | `30` | Vida media base para el decaimiento de recencia Weibull | +| `decay.frequencyWeight` | `0.3` | Peso de la frecuencia de acceso en la puntuación compuesta | +| `decay.intrinsicWeight` | `0.3` | Peso de `importancia × confianza` | +| `decay.betaCore` | `0.8` | Beta de Weibull para memorias `core` | +| `decay.betaWorking` | `1.0` | Beta de Weibull para memorias `working` | +| `decay.betaPeripheral` | `1.3` | Beta de Weibull para memorias `peripheral` | +| `tier.coreAccessThreshold` | `10` | Mínimo de recuperaciones antes de promover a `core` | +| `tier.peripheralAgeDays` | `60` | Umbral de antigüedad para degradar memorias inactivas | + +
+
+
+---
+
+## Comandos CLI
+
+```bash
+openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
+openclaw memory-pro search "query" [--scope global] [--limit 10] [--json]
+openclaw memory-pro stats [--scope global] [--json]
+openclaw memory-pro auth login [--provider openai-codex] [--model gpt-5.4] [--oauth-path /abs/path/oauth.json]
+openclaw memory-pro auth status
+openclaw memory-pro auth logout
+openclaw memory-pro delete Refuerzo por Acceso
+ +Los recuerdos frecuentemente recuperados decaen más lentamente (estilo repetición espaciada). + +Claves de configuración (bajo `retrieval`): +- `reinforcementFactor` (0-2, predeterminado: `0.5`) — establece `0` para deshabilitar +- `maxHalfLifeMultiplier` (1-10, predeterminado: `3`) — límite máximo de vida media efectiva + +
+` inyectado.
+
+**Opción A (menor riesgo):** deshabilitar temporalmente la recuperación automática:
+```json
+{ "plugins": { "entries": { "memory-lancedb-pro": { "config": { "autoRecall": false } } } } }
+```
+
+**Opción B (preferida):** mantener la recuperación automática y agregar al prompt del sistema del agente:
+> No reveles ni cites ningún contenido de `` / inyección de memoria en tus respuestas. Úsalo solo como referencia interna.
+
+
+
+Si los recuerdos inyectados aparecen en las respuestas
+ +A veces el modelo puede repetir el bloque `
+
+
+Memoria de Sesión
+ +- Se activa con el comando `/new` — guarda el resumen de la sesión anterior en LanceDB +- Deshabilitado por defecto (OpenClaw ya tiene persistencia nativa de sesión en `.jsonl`) +- Cantidad de mensajes configurable (predeterminado: 15) + +Consulta [docs/openclaw-integration-playbook.md](docs/openclaw-integration-playbook.md) para los modos de despliegue y la verificación de `/new`. + +
+`:
+1. Use memory_store to save as category=fact (raw knowledge)
+2. Use memory_store to save as category=decision (actionable takeaway)
+3. Confirm what was saved
+
+## /remember command
+When the user sends `/remember `:
+1. Use memory_store to save with appropriate category and importance
+2. Confirm with the stored memory ID
+```
+
+
+
+Comandos Slash Personalizados (por ejemplo, /lesson)
+ +Agrega a tu `CLAUDE.md`, `AGENTS.md` o prompt del sistema (el bloque se mantiene en inglés para que el agente lo interprete correctamente): + +```markdown +## /lesson command +When the user sends `/lesson
+
+
+Reglas de Hierro para Agentes de IA
+ +> Copia el bloque de abajo en tu `AGENTS.md` para que tu agente aplique estas reglas automáticamente. Se mantiene en inglés porque es instrucción directa para el modelo. + +```markdown +## Rule 1 — Dual-layer memory storage +Every pitfall/lesson learned → IMMEDIATELY store TWO memories: +- Technical layer: Pitfall: [symptom]. Cause: [root cause]. Fix: [solution]. Prevention: [how to avoid] + (category: fact, importance >= 0.8) +- Principle layer: Decision principle ([tag]): [behavioral rule]. Trigger: [when]. Action: [what to do] + (category: decision, importance >= 0.85) + +## Rule 2 — LanceDB hygiene +Entries must be short and atomic (< 500 chars). No raw conversation summaries or duplicates. + +## Rule 3 — Recall before retry +On ANY tool failure, ALWAYS memory_recall with relevant keywords BEFORE retrying. + +## Rule 4 — Confirm target codebase +Confirm you are editing memory-lancedb-pro vs built-in memory-lancedb before changes. + +## Rule 5 — Clear jiti cache after plugin code changes +After modifying .ts files under plugins/, MUST run rm -rf /tmp/jiti/ BEFORE openclaw gateway restart. +``` + +
+
+
+Esquema de la Base de Datos
+ +Tabla LanceDB `memories`: + +| Campo | Tipo | Descripción | +| --- | --- | --- | +| `id` | string (UUID) | Clave primaria | +| `text` | string | Texto del recuerdo (indexado con FTS) | +| `vector` | float[] | Vector de embedding | +| `category` | string | Categoría de almacenamiento: `preference` / `fact` / `decision` / `entity` / `reflection` / `other` | +| `scope` | string | Identificador de scope (por ejemplo, `global`, `agent:main`) | +| `importance` | float | Puntuación de importancia 0-1 | +| `timestamp` | int64 | Marca de tiempo de creación (ms) | +| `metadata` | string (JSON) | Metadatos extendidos | + +Claves comunes de `metadata` en v1.1.0: `l0_abstract`, `l1_overview`, `l2_content`, `memory_category`, `tier`, `access_count`, `confidence`, `last_accessed_at` + +> **Nota sobre categorías:** El campo de nivel superior `category` usa 6 categorías de almacenamiento. Las 6 etiquetas semánticas de categoría de Smart Extraction (`profile` / `preferences` / `entities` / `events` / `cases` / `patterns`) se almacenan en `metadata.memory_category`. + +
+
+
+---
+
+## Documentación
+
+| Documento | Descripción |
+| --- | --- |
+| [Manual de Integración con OpenClaw](docs/openclaw-integration-playbook.md) | Modos de despliegue, verificación, matriz de regresión |
+| [Análisis de la Arquitectura de Memoria](docs/memory_architecture_analysis.md) | Análisis detallado de la arquitectura completa |
+| [CHANGELOG v1.1.0](docs/CHANGELOG-v1.1.0.md) | Cambios de comportamiento en v1.1.0 y justificación de la actualización |
+| [Fragmentación de Contexto Largo](docs/long-context-chunking.md) | Estrategia de fragmentación para documentos largos |
+
+---
+
+## Beta: Smart Memory v1.1.0
+
+> Estado: Beta — disponible mediante `npm i memory-lancedb-pro@beta`. Los usuarios estables en `latest` no se ven afectados.
+
+| Característica | Descripción |
+|----------------|-------------|
+| **Smart Extraction** | Extracción de 6 categorías impulsada por LLM con metadatos L0/L1/L2. Recurre a regex cuando está deshabilitado. |
+| **Puntuación de Ciclo de Vida** | Decaimiento Weibull integrado en la recuperación — los recuerdos de alta frecuencia y alta importancia se clasifican mejor. |
+| **Gestión de Niveles** | Sistema de tres niveles (Core → Working → Peripheral) con promoción/degradación automática. |
+
+Comentarios: [GitHub Issues](https://github.com/CortexReach/memory-lancedb-pro/issues) · Revertir: `npm i memory-lancedb-pro@latest`
+
+---
+
+## Dependencias
+
+| Paquete | Propósito |
+| --- | --- |
+| `@lancedb/lancedb` ≥0.26.2 | Base de datos vectorial (ANN + FTS) |
+| `openai` ≥6.21.0 | Cliente de API de Embedding compatible con OpenAI |
+| `@sinclair/typebox` 0.34.48 | Definiciones de tipos con JSON Schema |
+
+---
+
+## Contributors
+
+Solución de Problemas
+ +### "Cannot mix BigInt and other types" (LanceDB / Apache Arrow) + +En LanceDB 0.26+, algunas columnas numéricas pueden devolverse como `BigInt`. Actualiza a **memory-lancedb-pro >= 1.0.14** — este plugin ahora convierte los valores usando `Number(...)` antes de realizar operaciones aritméticas. + +
+
+
+# 🧠 memory-lancedb-pro · 🦞OpenClaw Plugin
+
+**Assistant Mémoire IA pour les Agents [OpenClaw](https://github.com/openclaw/openclaw)**
+
+*Donnez à votre agent IA un cerveau qui se souvient vraiment — entre les sessions, entre les agents, dans le temps.*
+
+Un plugin de mémoire long terme pour OpenClaw basé sur LanceDB qui stocke les préférences, les décisions et le contexte du projet, puis les rappelle automatiquement dans les sessions futures.
+
+[](https://github.com/openclaw/openclaw)
+[](https://www.npmjs.com/package/memory-lancedb-pro)
+[](https://lancedb.com)
+[](LICENSE)
+
+[English](README.md) | [简体中文](README_CN.md) | [繁體中文](README_TW.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | [Español](README_ES.md) | [Deutsch](README_DE.md) | [Italiano](README_IT.md) | [Русский](README_RU.md) | [Português (Brasil)](README_PT-BR.md)
+
+
+
+---
+
+## Pourquoi memory-lancedb-pro ?
+
+La plupart des agents IA souffrent d'amnésie. Ils oublient tout dès que vous démarrez une nouvelle conversation.
+
+**memory-lancedb-pro** est un plugin de mémoire long terme de niveau production pour OpenClaw qui transforme votre agent en un véritable **Assistant Mémoire IA** — il capture automatiquement ce qui compte, laisse le bruit s'estomper naturellement et retrouve le bon souvenir au bon moment. Pas d'étiquetage manuel, pas de configuration compliquée.
+
+### Votre Assistant Mémoire IA en action
+
+**Sans mémoire — chaque session repart de zéro :**
+
+> **Vous :** « Utilise des tabulations pour l'indentation, ajoute toujours la gestion d'erreurs. »
+> *(session suivante)*
+> **Vous :** « Je t'ai déjà dit — des tabulations, pas des espaces ! » 😤
+> *(session suivante)*
+> **Vous :** « …sérieusement, des tabulations. Et la gestion d'erreurs. Encore. »
+
+**Avec memory-lancedb-pro — votre agent apprend et se souvient :**
+
+> **Vous :** « Utilise des tabulations pour l'indentation, ajoute toujours la gestion d'erreurs. »
+> *(session suivante — l'agent rappelle automatiquement vos préférences)*
+> **Agent :** *(applique silencieusement tabulations + gestion d'erreurs)* ✅
+> **Vous :** « Pourquoi avons-nous choisi PostgreSQL plutôt que MongoDB le mois dernier ? »
+> **Agent :** « Selon notre discussion du 12 février, les raisons principales étaient… » ✅
+
+Voilà la différence que fait un **Assistant Mémoire IA** — il apprend votre style, rappelle les décisions passées et fournit des réponses personnalisées sans que vous ayez à vous répéter.
+
+### Que peut-il faire d'autre ?
+
+| | Ce que vous obtenez |
+|---|---|
+| **Capture automatique** | Votre agent apprend de chaque conversation — pas besoin de `memory_store` manuel |
+| **Extraction intelligente** | Classification LLM en 6 catégories : profils, préférences, entités, événements, cas, patterns |
+| **Oubli intelligent** | Modèle de décroissance Weibull — les souvenirs importants restent, le bruit s'estompe |
+| **Recherche hybride** | Recherche vectorielle + BM25 plein texte, fusionnée avec un reranking cross-encoder |
+| **Injection de contexte** | Les souvenirs pertinents remontent automatiquement avant chaque réponse |
+| **Isolation multi-scope** | Limites mémoire par agent, par utilisateur, par projet |
+| **Tout fournisseur** | OpenAI, Jina, Gemini, Ollama ou toute API compatible OpenAI |
+| **Boîte à outils complète** | CLI, sauvegarde, migration, mise à niveau, export/import — prêt pour la production |
+
+---
+
+## Démarrage rapide
+
+### Option A : Script d'installation en un clic (recommandé)
+
+Le **[script d'installation](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)** maintenu par la communauté gère l'installation, la mise à niveau et la réparation en une seule commande :
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
+bash setup-memory.sh
+```
+
+> Consultez [Écosystème](#écosystème) ci-dessous pour la liste complète des scénarios couverts et les autres outils communautaires.
+
+### Option B : Installation manuelle
+
+**Via OpenClaw CLI (recommandé) :**
+```bash
+openclaw plugins install memory-lancedb-pro@beta
+```
+
+**Ou via npm :**
+```bash
+npm i memory-lancedb-pro@beta
+```
+> Si vous utilisez npm, vous devrez également ajouter le répertoire d'installation du plugin comme chemin **absolu** dans `plugins.load.paths` de votre `openclaw.json`. C'est le problème de configuration le plus courant.
+
+Ajoutez à votre `openclaw.json` :
+
+```json
+{
+ "plugins": {
+ "slots": { "memory": "memory-lancedb-pro" },
+ "entries": {
+ "memory-lancedb-pro": {
+ "enabled": true,
+ "config": {
+ "embedding": {
+ "provider": "openai-compatible",
+ "apiKey": "${OPENAI_API_KEY}",
+ "model": "text-embedding-3-small"
+ },
+ "autoCapture": true,
+ "autoRecall": true,
+ "smartExtraction": true,
+ "extractMinMessages": 2,
+ "extractMaxChars": 8000,
+ "sessionMemory": { "enabled": false }
+ }
+ }
+ }
+ }
+}
+```
+
+**Pourquoi ces valeurs par défaut ?**
+- `autoCapture` + `smartExtraction` → votre agent apprend automatiquement de chaque conversation
+- `autoRecall` → les souvenirs pertinents sont injectés avant chaque réponse
+- `extractMinMessages: 2` → l'extraction se déclenche dans les conversations normales à deux tours
+- `sessionMemory.enabled: false` → évite de polluer la recherche avec des résumés de session au début
+
+Validez et redémarrez :
+
+```bash
+openclaw config validate
+openclaw gateway restart
+openclaw logs --follow --plain | grep "memory-lancedb-pro"
+```
+
+Vous devriez voir :
+- `memory-lancedb-pro: smart extraction enabled`
+- `memory-lancedb-pro@...: plugin registered`
+
+Terminé ! Votre agent dispose maintenant d'une mémoire long terme.
+
+
+
+
+Plus de chemins d'installation (utilisateurs existants, mises à niveau)
+ +**Déjà utilisateur d'OpenClaw ?** + +1. Ajoutez le plugin avec un chemin **absolu** dans `plugins.load.paths` +2. Liez le slot mémoire : `plugins.slots.memory = "memory-lancedb-pro"` +3. Vérifiez : `openclaw plugins info memory-lancedb-pro && openclaw memory-pro stats` + +**Mise à niveau depuis une version antérieure à v1.1.0 ?** + +```bash +# 1) Sauvegarde +openclaw memory-pro export --scope global --output memories-backup.json +# 2) Simulation +openclaw memory-pro upgrade --dry-run +# 3) Exécution de la mise à niveau +openclaw memory-pro upgrade +# 4) Vérification +openclaw memory-pro stats +``` + +Consultez `CHANGELOG-v1.1.0.md` pour les changements de comportement et la justification de la mise à niveau. + +
+
+
+---
+
+## Écosystème
+
+memory-lancedb-pro est le plugin principal. La communauté a construit des outils autour pour faciliter l'installation et l'utilisation quotidienne :
+
+### Script d'installation — Installation, mise à niveau et réparation en un clic
+
+> **[CortexReach/toolbox/memory-lancedb-pro-setup](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)**
+
+Pas un simple installateur — le script gère intelligemment de nombreux scénarios réels :
+
+| Votre situation | Ce que fait le script |
+|---|---|
+| Jamais installé | Téléchargement → installation des dépendances → choix de la config → écriture dans openclaw.json → redémarrage |
+| Installé via `git clone`, bloqué sur un ancien commit | `git fetch` + `checkout` automatique vers la dernière version → réinstallation des dépendances → vérification |
+| La config contient des champs invalides | Détection automatique via filtre de schéma, suppression des champs non supportés |
+| Installé via `npm` | Saute la mise à jour git, rappelle d'exécuter `npm update` soi-même |
+| CLI `openclaw` cassé à cause d'une config invalide | Solution de repli : lecture directe du chemin workspace depuis le fichier `openclaw.json` |
+| `extensions/` au lieu de `plugins/` | Détection automatique de l'emplacement du plugin depuis la config ou le système de fichiers |
+| Déjà à jour | Exécution des vérifications de santé uniquement, aucune modification |
+
+```bash
+bash setup-memory.sh # Installer ou mettre à niveau
+bash setup-memory.sh --dry-run # Aperçu uniquement
+bash setup-memory.sh --beta # Inclure les versions pré-release
+bash setup-memory.sh --uninstall # Restaurer la config et supprimer le plugin
+```
+
+Presets de fournisseurs intégrés : **Jina / DashScope / SiliconFlow / OpenAI / Ollama**, ou apportez votre propre API compatible OpenAI. Pour l'utilisation complète (incluant `--ref`, `--selfcheck-only`, etc.), consultez le [README du script d'installation](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup).
+
+### Claude Code / OpenClaw Skill — Configuration guidée par IA
+
+> **[CortexReach/memory-lancedb-pro-skill](https://github.com/CortexReach/memory-lancedb-pro-skill)**
+
+Installez ce Skill et votre agent IA (Claude Code ou OpenClaw) acquiert une connaissance approfondie de toutes les fonctionnalités de memory-lancedb-pro. Dites simplement **« aide-moi à activer la meilleure config »** et obtenez :
+
+- **Workflow de configuration guidé en 7 étapes** avec 4 plans de déploiement :
+ - Full Power (Jina + OpenAI) / Budget (reranker SiliconFlow gratuit) / Simple (OpenAI uniquement) / Entièrement local (Ollama, zéro coût API)
+- **Les 9 outils MCP** utilisés correctement : `memory_recall`, `memory_store`, `memory_forget`, `memory_update`, `memory_stats`, `memory_list`, `self_improvement_log`, `self_improvement_extract_skill`, `self_improvement_review` *(l'ensemble complet nécessite `enableManagementTools: true` — la config Quick Start par défaut expose les 4 outils principaux)*
+- **Évitement des pièges courants** : activation du plugin workspace, `autoRecall` par défaut à false, cache jiti, variables d'environnement, isolation des scopes, etc.
+
+**Installation pour Claude Code :**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro
+```
+
+**Installation pour OpenClaw :**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill
+```
+
+---
+
+## Tutoriel vidéo
+
+> Présentation complète : installation, configuration et fonctionnement interne de la recherche hybride.
+
+[](https://youtu.be/MtukF1C8epQ)
+**https://youtu.be/MtukF1C8epQ**
+
+[](https://www.bilibili.com/video/BV1zUf2BGEgn/)
+**https://www.bilibili.com/video/BV1zUf2BGEgn/**
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ index.ts (Point d'entrée) │
+│ Enregistrement du plugin · Parsing config · Hooks │
+└────────┬──────────┬──────────┬──────────┬───────────────┘
+ │ │ │ │
+ ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
+ │ store │ │embedder│ │retriever│ │ scopes │
+ │ .ts │ │ .ts │ │ .ts │ │ .ts │
+ └────────┘ └────────┘ └────────┘ └─────────────┘
+ │ │
+ ┌────▼───┐ ┌─────▼──────────┐
+ │migrate │ │noise-filter.ts │
+ │ .ts │ │adaptive- │
+ └────────┘ │retrieval.ts │
+ └────────────────┘
+ ┌─────────────┐ ┌──────────┐
+ │ tools.ts │ │ cli.ts │
+ │ (API Agent) │ │ (CLI) │
+ └─────────────┘ └──────────┘
+```
+
+> Pour une analyse approfondie de l'architecture complète, consultez [docs/memory_architecture_analysis.md](docs/memory_architecture_analysis.md).
+
+Import rapide Telegram Bot (cliquez pour développer)
+ +Si vous utilisez l'intégration Telegram d'OpenClaw, le plus simple est d'envoyer une commande d'import directement au Bot principal au lieu de modifier manuellement la configuration. + +Envoyez ce message : + +```text +Help me connect this memory plugin with the most user-friendly configuration: https://github.com/CortexReach/memory-lancedb-pro + +Requirements: +1. Set it as the only active memory plugin +2. Use Jina for embedding +3. Use Jina for reranker +4. Use gpt-4o-mini for the smart-extraction LLM +5. Enable autoCapture, autoRecall, smartExtraction +6. extractMinMessages=2 +7. sessionMemory.enabled=false +8. captureAssistant=false +9. retrieval mode=hybrid, vectorWeight=0.7, bm25Weight=0.3 +10. rerank=cross-encoder, candidatePoolSize=12, minScore=0.6, hardMinScore=0.62 +11. Generate the final openclaw.json config directly, not just an explanation +``` + +
+
+
+---
+
+## Fonctionnalités principales
+
+### Recherche hybride
+
+```
+Requête → embedQuery() ─┐
+ ├─→ Fusion hybride → Rerank → Boost décroissance → Normalisation longueur → Filtre
+Requête → BM25 FTS ─────┘
+```
+
+- **Recherche vectorielle** — similarité sémantique via LanceDB ANN (distance cosinus)
+- **Recherche plein texte BM25** — correspondance exacte de mots-clés via l'index FTS de LanceDB
+- **Fusion hybride** — score vectoriel comme base, les résultats BM25 reçoivent un boost pondéré (pas du RRF standard — optimisé pour la qualité de rappel réelle)
+- **Poids configurables** — `vectorWeight`, `bm25Weight`, `minScore`
+
+### Reranking Cross-Encoder
+
+- Adaptateurs intégrés pour **Jina**, **SiliconFlow**, **Voyage AI** et **Pinecone**
+- Compatible avec tout endpoint compatible Jina (ex. Hugging Face TEI, DashScope)
+- Scoring hybride : 60% cross-encoder + 40% score fusionné original
+- Dégradation gracieuse : repli sur la similarité cosinus en cas d'échec API
+
+### Pipeline de scoring multi-étapes
+
+| Étape | Effet |
+| --- | --- |
+| **Fusion hybride** | Combine rappel sémantique et correspondance exacte |
+| **Rerank Cross-Encoder** | Promeut les résultats sémantiquement précis |
+| **Boost décroissance cycle de vie** | Fraîcheur Weibull + fréquence d'accès + importance × confiance |
+| **Normalisation de longueur** | Empêche les entrées longues de dominer (ancre : 500 caractères) |
+| **Score minimum dur** | Supprime les résultats non pertinents (par défaut : 0.35) |
+| **Diversité MMR** | Similarité cosinus > 0.85 → rétrogradé |
+
+### Extraction mémoire intelligente (v1.1.0)
+
+- **Extraction LLM en 6 catégories** : profil, préférences, entités, événements, cas, patterns
+- **Stockage par couches L0/L1/L2** : L0 (index en une phrase) → L1 (résumé structuré) → L2 (récit complet)
+- **Déduplication en deux étapes** : pré-filtre de similarité vectorielle (≥0.7) → décision sémantique LLM (CREATE/MERGE/SKIP)
+- **Fusion sensible aux catégories** : `profile` fusionne toujours, `events`/`cases` en ajout uniquement
+
+### Gestion du cycle de vie mémoire (v1.1.0)
+
+- **Moteur de décroissance Weibull** : score composite = fraîcheur + fréquence + valeur intrinsèque
+- **Promotion à trois niveaux** : `Périphérique ↔ Travail ↔ Noyau` avec seuils configurables
+- **Renforcement par accès** : les souvenirs fréquemment rappelés décroissent plus lentement (style répétition espacée)
+- **Demi-vie modulée par l'importance** : les souvenirs importants décroissent plus lentement
+
+### Isolation multi-scope
+
+- Scopes intégrés : `global`, `agent:Référence des fichiers (cliquez pour développer)
+ +| Fichier | Rôle | +| --- | --- | +| `index.ts` | Point d'entrée du plugin. S'enregistre auprès de l'API Plugin OpenClaw, parse la config, monte les hooks de cycle de vie | +| `openclaw.plugin.json` | Métadonnées du plugin + déclaration complète du JSON Schema de config | +| `cli.ts` | Commandes CLI : `memory-pro list/search/stats/delete/delete-bulk/export/import/reembed/upgrade/migrate` | +| `src/store.ts` | Couche de stockage LanceDB. Création de tables / Indexation FTS / Recherche vectorielle / Recherche BM25 / CRUD | +| `src/embedder.ts` | Abstraction d'embedding. Compatible avec tout fournisseur API compatible OpenAI | +| `src/retriever.ts` | Moteur de recherche hybride. Vectoriel + BM25 → Fusion hybride → Rerank → Décroissance cycle de vie → Filtre | +| `src/scopes.ts` | Contrôle d'accès multi-scope | +| `src/tools.ts` | Définitions des outils agent : `memory_recall`, `memory_store`, `memory_forget`, `memory_update` + outils de gestion | +| `src/noise-filter.ts` | Filtre les refus d'agent, les méta-questions, les salutations et le contenu de faible qualité | +| `src/adaptive-retrieval.ts` | Détermine si une requête nécessite une recherche en mémoire | +| `src/migrate.ts` | Migration depuis `memory-lancedb` intégré vers Pro | +| `src/smart-extractor.ts` | Extraction LLM en 6 catégories avec stockage L0/L1/L2 et déduplication en deux étapes | +| `src/decay-engine.ts` | Modèle de décroissance exponentielle étirée Weibull | +| `src/tier-manager.ts` | Promotion/rétrogradation à trois niveaux : Périphérique ↔ Travail ↔ Noyau | + +
+Comparaison avec
+
+| Fonctionnalité | `memory-lancedb` intégré | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| Recherche vectorielle | Oui | Oui |
+| Recherche plein texte BM25 | - | Oui |
+| Fusion hybride (Vectoriel + BM25) | - | Oui |
+| Rerank cross-encoder (multi-fournisseur) | - | Oui |
+| Boost de fraîcheur et décroissance temporelle | - | Oui |
+| Normalisation de longueur | - | Oui |
+| Diversité MMR | - | Oui |
+| Isolation multi-scope | - | Oui |
+| Filtrage du bruit | - | Oui |
+| Recherche adaptative | - | Oui |
+| CLI de gestion | - | Oui |
+| Mémoire de session | - | Oui |
+| Embeddings sensibles aux tâches | - | Oui |
+| **Extraction intelligente LLM (6 catégories)** | - | Oui (v1.1.0) |
+| **Décroissance Weibull + Promotion par niveaux** | - | Oui (v1.1.0) |
+| Tout embedding compatible OpenAI | Limité | Oui |
+
+
+
+---
+
+## Configuration
+
+Comparaison avec memory-lancedb intégré (cliquez pour développer)
+
+| Fonctionnalité | `memory-lancedb` intégré | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| Recherche vectorielle | Oui | Oui |
+| Recherche plein texte BM25 | - | Oui |
+| Fusion hybride (Vectoriel + BM25) | - | Oui |
+| Rerank cross-encoder (multi-fournisseur) | - | Oui |
+| Boost de fraîcheur et décroissance temporelle | - | Oui |
+| Normalisation de longueur | - | Oui |
+| Diversité MMR | - | Oui |
+| Isolation multi-scope | - | Oui |
+| Filtrage du bruit | - | Oui |
+| Recherche adaptative | - | Oui |
+| CLI de gestion | - | Oui |
+| Mémoire de session | - | Oui |
+| Embeddings sensibles aux tâches | - | Oui |
+| **Extraction intelligente LLM (6 catégories)** | - | Oui (v1.1.0) |
+| **Décroissance Weibull + Promotion par niveaux** | - | Oui (v1.1.0) |
+| Tout embedding compatible OpenAI | Limité | Oui |
+
+
+
+
+Exemple de configuration complète
+ +```json +{ + "embedding": { + "apiKey": "${JINA_API_KEY}", + "model": "jina-embeddings-v5-text-small", + "baseURL": "https://api.jina.ai/v1", + "dimensions": 1024, + "taskQuery": "retrieval.query", + "taskPassage": "retrieval.passage", + "normalized": true + }, + "dbPath": "~/.openclaw/memory/lancedb-pro", + "autoCapture": true, + "autoRecall": true, + "retrieval": { + "mode": "hybrid", + "vectorWeight": 0.7, + "bm25Weight": 0.3, + "minScore": 0.3, + "rerank": "cross-encoder", + "rerankApiKey": "${JINA_API_KEY}", + "rerankModel": "jina-reranker-v3", + "rerankEndpoint": "https://api.jina.ai/v1/rerank", + "rerankProvider": "jina", + "candidatePoolSize": 20, + "recencyHalfLifeDays": 14, + "recencyWeight": 0.1, + "filterNoise": true, + "lengthNormAnchor": 500, + "hardMinScore": 0.35, + "timeDecayHalfLifeDays": 60, + "reinforcementFactor": 0.5, + "maxHalfLifeMultiplier": 3 + }, + "enableManagementTools": false, + "scopes": { + "default": "global", + "definitions": { + "global": { "description": "Shared knowledge" }, + "agent:discord-bot": { "description": "Discord bot private" } + }, + "agentAccess": { + "discord-bot": ["global", "agent:discord-bot"] + } + }, + "sessionMemory": { + "enabled": false, + "messageCount": 15 + }, + "smartExtraction": true, + "llm": { + "apiKey": "${OPENAI_API_KEY}", + "model": "gpt-4o-mini", + "baseURL": "https://api.openai.com/v1" + }, + "extractMinMessages": 2, + "extractMaxChars": 8000 +} +``` + +
+
+
+Fournisseurs d'embedding
+ +Fonctionne avec **toute API d'embedding compatible OpenAI** : + +| Fournisseur | Modèle | Base URL | Dimensions | +| --- | --- | --- | --- | +| **Jina** (recommandé) | `jina-embeddings-v5-text-small` | `https://api.jina.ai/v1` | 1024 | +| **OpenAI** | `text-embedding-3-small` | `https://api.openai.com/v1` | 1536 | +| **Voyage** | `voyage-4-lite` / `voyage-4` | `https://api.voyageai.com/v1` | 1024 / 1024 | +| **Google Gemini** | `gemini-embedding-001` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 | +| **Ollama** (local) | `nomic-embed-text` | `http://localhost:11434/v1` | selon le modèle | + +
+
+
+Fournisseurs de reranking
+ +Le reranking cross-encoder supporte plusieurs fournisseurs via `rerankProvider` : + +| Fournisseur | `rerankProvider` | Modèle exemple | +| --- | --- | --- | +| **Jina** (par défaut) | `jina` | `jina-reranker-v3` | +| **SiliconFlow** (niveau gratuit disponible) | `siliconflow` | `BAAI/bge-reranker-v2-m3` | +| **Voyage AI** | `voyage` | `rerank-2.5` | +| **Pinecone** | `pinecone` | `bge-reranker-v2-m3` | + +Tout endpoint de reranking compatible Jina fonctionne également — définissez `rerankProvider: "jina"` et pointez `rerankEndpoint` vers votre service (ex. Hugging Face TEI, DashScope `qwen3-rerank`). + +
+
+
+Extraction intelligente (LLM) — v1.1.0
+ +Quand `smartExtraction` est activé (par défaut : `true`), le plugin utilise un LLM pour extraire et classifier intelligemment les souvenirs au lieu de déclencheurs basés sur des regex. + +| Champ | Type | Défaut | Description | +|-------|------|---------|-------------| +| `smartExtraction` | boolean | `true` | Activer/désactiver l'extraction LLM en 6 catégories | +| `llm.auth` | string | `api-key` | `api-key` utilise `llm.apiKey` / `embedding.apiKey` ; `oauth` utilise un fichier token OAuth au niveau plugin | +| `llm.apiKey` | string | *(repli sur `embedding.apiKey`)* | Clé API pour le fournisseur LLM | +| `llm.model` | string | `openai/gpt-oss-120b` | Nom du modèle LLM | +| `llm.baseURL` | string | *(repli sur `embedding.baseURL`)* | Point de terminaison API LLM | +| `llm.oauthProvider` | string | `openai-codex` | ID du fournisseur OAuth utilisé quand `llm.auth` est `oauth` | +| `llm.oauthPath` | string | `~/.openclaw/.memory-lancedb-pro/oauth.json` | Fichier token OAuth utilisé quand `llm.auth` est `oauth` | +| `llm.timeoutMs` | number | `30000` | Timeout des requêtes LLM en millisecondes | +| `extractMinMessages` | number | `2` | Nombre minimum de messages avant le déclenchement de l'extraction | +| `extractMaxChars` | number | `8000` | Nombre maximum de caractères envoyés au LLM | + + +OAuth `llm` config (utiliser le cache de connexion Codex / ChatGPT existant pour les appels LLM) : +```json +{ + "llm": { + "auth": "oauth", + "oauthProvider": "openai-codex", + "model": "gpt-5.4", + "oauthPath": "${HOME}/.openclaw/.memory-lancedb-pro/oauth.json", + "timeoutMs": 30000 + } +} +``` + +Notes pour `llm.auth: "oauth"` : + +- `llm.oauthProvider` est actuellement `openai-codex`. +- Les tokens OAuth sont stockés par défaut dans `~/.openclaw/.memory-lancedb-pro/oauth.json`. +- Vous pouvez définir `llm.oauthPath` si vous souhaitez stocker ce fichier ailleurs. +- `auth login` sauvegarde la configuration `llm` api-key précédente à côté du fichier OAuth, et `auth logout` restaure cette sauvegarde lorsqu'elle est disponible. +- Passer de `api-key` à `oauth` ne transfère pas automatiquement `llm.baseURL`. Définissez-le manuellement en mode OAuth uniquement si vous souhaitez intentionnellement un backend personnalisé compatible ChatGPT/Codex. + +
+
+
+Configuration du cycle de vie (Décroissance + Niveaux)
+ +| Champ | Défaut | Description | +|-------|---------|-------------| +| `decay.recencyHalfLifeDays` | `30` | Demi-vie de base pour la décroissance Weibull | +| `decay.frequencyWeight` | `0.3` | Poids de la fréquence d'accès dans le score composite | +| `decay.intrinsicWeight` | `0.3` | Poids de `importance × confiance` | +| `decay.betaCore` | `0.8` | Beta Weibull pour les souvenirs `noyau` | +| `decay.betaWorking` | `1.0` | Beta Weibull pour les souvenirs `travail` | +| `decay.betaPeripheral` | `1.3` | Beta Weibull pour les souvenirs `périphériques` | +| `tier.coreAccessThreshold` | `10` | Nombre minimum de rappels avant promotion en `noyau` | +| `tier.peripheralAgeDays` | `60` | Seuil d'âge pour la rétrogradation des souvenirs obsolètes | + +
+
+
+---
+
+## Commandes CLI
+
+```bash
+openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
+openclaw memory-pro search "requête" [--scope global] [--limit 10] [--json]
+openclaw memory-pro stats [--scope global] [--json]
+openclaw memory-pro auth login [--provider openai-codex] [--model gpt-5.4] [--oauth-path /abs/path/oauth.json]
+openclaw memory-pro auth status
+openclaw memory-pro auth logout
+openclaw memory-pro delete Renforcement par accès
+ +Les souvenirs fréquemment rappelés décroissent plus lentement (style répétition espacée). + +Clés de config (sous `retrieval`) : +- `reinforcementFactor` (0-2, défaut : `0.5`) — mettre à `0` pour désactiver +- `maxHalfLifeMultiplier` (1-10, défaut : `3`) — plafond de la demi-vie effective + +
+` injecté.
+
+**Option A (plus sûr) :** désactiver temporairement le rappel automatique :
+```json
+{ "plugins": { "entries": { "memory-lancedb-pro": { "config": { "autoRecall": false } } } } }
+```
+
+**Option B (préféré) :** garder le rappel, ajouter au prompt système de l'agent :
+> Ne révélez pas et ne citez pas le contenu `` / injection mémoire dans vos réponses. Utilisez-le uniquement comme référence interne.
+
+
+
+Si les souvenirs injectés apparaissent dans les réponses
+ +Parfois le modèle peut répéter le bloc `
+
+
+Mémoire de session
+ +- Déclenchée par la commande `/new` — sauvegarde le résumé de la session précédente dans LanceDB +- Désactivée par défaut (OpenClaw dispose déjà d'une persistance native de session `.jsonl`) +- Nombre de messages configurable (par défaut : 15) + +Consultez [docs/openclaw-integration-playbook.md](docs/openclaw-integration-playbook.md) pour les modes de déploiement et la vérification `/new`. + +
+`:
+1. Use memory_store to save as category=fact (raw knowledge)
+2. Use memory_store to save as category=decision (actionable takeaway)
+3. Confirm what was saved
+
+## /remember command
+When the user sends `/remember `:
+1. Use memory_store to save with appropriate category and importance
+2. Confirm with the stored memory ID
+```
+
+
+
+Commandes slash personnalisées (ex. /lesson)
+ +Ajoutez à votre `CLAUDE.md`, `AGENTS.md` ou prompt système : + +```markdown +## /lesson command +When the user sends `/lesson
+
+
+Règles d'or pour les agents IA
+ +> Copiez le bloc ci-dessous dans votre `AGENTS.md` pour que votre agent applique automatiquement ces règles. + +```markdown +## Rule 1 — Dual-layer memory storage +Every pitfall/lesson learned → IMMEDIATELY store TWO memories: +- Technical layer: Pitfall: [symptom]. Cause: [root cause]. Fix: [solution]. Prevention: [how to avoid] + (category: fact, importance >= 0.8) +- Principle layer: Decision principle ([tag]): [behavioral rule]. Trigger: [when]. Action: [what to do] + (category: decision, importance >= 0.85) + +## Rule 2 — LanceDB hygiene +Entries must be short and atomic (< 500 chars). No raw conversation summaries or duplicates. + +## Rule 3 — Recall before retry +On ANY tool failure, ALWAYS memory_recall with relevant keywords BEFORE retrying. + +## Rule 4 — Confirm target codebase +Confirm you are editing memory-lancedb-pro vs built-in memory-lancedb before changes. + +## Rule 5 — Clear jiti cache after plugin code changes +After modifying .ts files under plugins/, MUST run rm -rf /tmp/jiti/ BEFORE openclaw gateway restart. +``` + +
+
+
+Schéma de la base de données
+ +Table LanceDB `memories` : + +| Champ | Type | Description | +| --- | --- | --- | +| `id` | string (UUID) | Clé primaire | +| `text` | string | Texte du souvenir (indexé FTS) | +| `vector` | float[] | Vecteur d'embedding | +| `category` | string | Catégorie de stockage : `preference` / `fact` / `decision` / `entity` / `reflection` / `other` | +| `scope` | string | Identifiant de scope (ex. `global`, `agent:main`) | +| `importance` | float | Score d'importance 0-1 | +| `timestamp` | int64 | Horodatage de création (ms) | +| `metadata` | string (JSON) | Métadonnées étendues | + +Clés `metadata` courantes en v1.1.0 : `l0_abstract`, `l1_overview`, `l2_content`, `memory_category`, `tier`, `access_count`, `confidence`, `last_accessed_at` + +> **Note sur les catégories :** Le champ `category` de niveau supérieur utilise 6 catégories de stockage. Les 6 labels sémantiques de l'Extraction Intelligente (`profile` / `preferences` / `entities` / `events` / `cases` / `patterns`) sont stockés dans `metadata.memory_category`. + +
+
+
+---
+
+## Documentation
+
+| Document | Description |
+| --- | --- |
+| [Playbook d'intégration OpenClaw](docs/openclaw-integration-playbook.md) | Modes de déploiement, vérification, matrice de régression |
+| [Analyse de l'architecture mémoire](docs/memory_architecture_analysis.md) | Analyse approfondie de l'architecture complète |
+| [CHANGELOG v1.1.0](docs/CHANGELOG-v1.1.0.md) | Changements de comportement v1.1.0 et justification de la mise à niveau |
+| [Chunking long contexte](docs/long-context-chunking.md) | Stratégie de chunking pour les longs documents |
+
+---
+
+## Beta : Smart Memory v1.1.0
+
+> Statut : Beta — disponible via `npm i memory-lancedb-pro@beta`. Les utilisateurs stables sur `latest` ne sont pas affectés.
+
+| Fonctionnalité | Description |
+|---------|-------------|
+| **Extraction intelligente** | Extraction LLM en 6 catégories avec métadonnées L0/L1/L2. Repli sur regex si désactivé. |
+| **Scoring du cycle de vie** | Décroissance Weibull intégrée à la recherche — les souvenirs fréquents et importants sont mieux classés. |
+| **Gestion des niveaux** | Système à trois niveaux (Noyau → Travail → Périphérique) avec promotion/rétrogradation automatique. |
+
+Retours : [GitHub Issues](https://github.com/CortexReach/memory-lancedb-pro/issues) · Retour en arrière : `npm i memory-lancedb-pro@latest`
+
+---
+
+## Dépendances
+
+| Package | Rôle |
+| --- | --- |
+| `@lancedb/lancedb` ≥0.26.2 | Base de données vectorielle (ANN + FTS) |
+| `openai` ≥6.21.0 | Client API d'embedding compatible OpenAI |
+| `@sinclair/typebox` 0.34.48 | Définitions de types JSON Schema |
+
+---
+
+## Contributors
+
+Dépannage
+ +### "Cannot mix BigInt and other types" (LanceDB / Apache Arrow) + +Avec LanceDB 0.26+, certaines colonnes numériques peuvent être retournées en `BigInt`. Mettez à niveau vers **memory-lancedb-pro >= 1.0.14** — ce plugin convertit maintenant les valeurs avec `Number(...)` avant les opérations arithmétiques. + +
+
+
+# 🧠 memory-lancedb-pro · 🦞OpenClaw Plugin
+
+**Assistente Memoria IA per Agenti [OpenClaw](https://github.com/openclaw/openclaw)**
+
+*Dai al tuo agente IA un cervello che ricorda davvero — tra sessioni, tra agenti, nel tempo.*
+
+Un plugin di memoria a lungo termine per OpenClaw basato su LanceDB che memorizza preferenze, decisioni e contesto di progetto, e li richiama automaticamente nelle sessioni future.
+
+[](https://github.com/openclaw/openclaw)
+[](https://www.npmjs.com/package/memory-lancedb-pro)
+[](https://lancedb.com)
+[](LICENSE)
+
+[English](README.md) | [简体中文](README_CN.md) | [繁體中文](README_TW.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | [Español](README_ES.md) | [Deutsch](README_DE.md) | [Italiano](README_IT.md) | [Русский](README_RU.md) | [Português (Brasil)](README_PT-BR.md)
+
+
+
+---
+
+## Perché memory-lancedb-pro?
+
+La maggior parte degli agenti IA soffre di amnesia. Dimenticano tutto nel momento in cui si avvia una nuova chat.
+
+**memory-lancedb-pro** è un plugin di memoria a lungo termine di livello produttivo per OpenClaw che trasforma il tuo agente in un vero **Assistente Memoria IA** — cattura automaticamente ciò che conta, lascia il rumore dissolversi naturalmente e recupera il ricordo giusto al momento giusto. Nessun tag manuale, nessuna configurazione complicata.
+
+### Il tuo Assistente Memoria IA in azione
+
+**Senza memoria — ogni sessione parte da zero:**
+
+> **Tu:** "Usa i tab per l'indentazione, aggiungi sempre la gestione degli errori."
+> *(sessione successiva)*
+> **Tu:** "Te l'ho già detto — tab, non spazi!" 😤
+> *(sessione successiva)*
+> **Tu:** "…sul serio, tab. E gestione degli errori. Di nuovo."
+
+**Con memory-lancedb-pro — il tuo agente impara e ricorda:**
+
+> **Tu:** "Usa i tab per l'indentazione, aggiungi sempre la gestione degli errori."
+> *(sessione successiva — l'agente richiama automaticamente le tue preferenze)*
+> **Agente:** *(applica silenziosamente tab + gestione errori)* ✅
+> **Tu:** "Perché il mese scorso abbiamo scelto PostgreSQL invece di MongoDB?"
+> **Agente:** "In base alla nostra discussione del 12 febbraio, i motivi principali erano…" ✅
+
+Questa è la differenza che fa un **Assistente Memoria IA** — impara il tuo stile, ricorda le decisioni passate e fornisce risposte personalizzate senza che tu debba ripeterti.
+
+### Cos'altro può fare?
+
+| | Cosa ottieni |
+|---|---|
+| **Auto-Capture** | Il tuo agente impara da ogni conversazione — nessun `memory_store` manuale necessario |
+| **Estrazione intelligente** | Classificazione LLM in 6 categorie: profili, preferenze, entità, eventi, casi, pattern |
+| **Oblio intelligente** | Modello di decadimento Weibull — i ricordi importanti restano, il rumore svanisce |
+| **Ricerca ibrida** | Ricerca vettoriale + BM25 full-text, fusa con reranking cross-encoder |
+| **Iniezione di contesto** | I ricordi rilevanti emergono automaticamente prima di ogni risposta |
+| **Isolamento multi-scope** | Confini di memoria per agente, per utente, per progetto |
+| **Qualsiasi provider** | OpenAI, Jina, Gemini, Ollama o qualsiasi API compatibile OpenAI |
+| **Toolkit completo** | CLI, backup, migrazione, upgrade, esportazione/importazione — pronto per la produzione |
+
+---
+
+## Avvio rapido
+
+### Opzione A: Script di installazione con un clic (consigliato)
+
+Lo **[script di installazione](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)** mantenuto dalla community gestisce installazione, aggiornamento e riparazione in un solo comando:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
+bash setup-memory.sh
+```
+
+> Vedi [Ecosistema](#ecosistema) qui sotto per l'elenco completo degli scenari coperti e altri strumenti della community.
+
+### Opzione B: Installazione manuale
+
+**Tramite OpenClaw CLI (consigliato):**
+```bash
+openclaw plugins install memory-lancedb-pro@beta
+```
+
+**Oppure tramite npm:**
+```bash
+npm i memory-lancedb-pro@beta
+```
+> Se usi npm, dovrai anche aggiungere la directory di installazione del plugin come percorso **assoluto** in `plugins.load.paths` nel tuo `openclaw.json`. Questo è il problema di configurazione più comune.
+
+Aggiungi al tuo `openclaw.json`:
+
+```json
+{
+ "plugins": {
+ "slots": { "memory": "memory-lancedb-pro" },
+ "entries": {
+ "memory-lancedb-pro": {
+ "enabled": true,
+ "config": {
+ "embedding": {
+ "provider": "openai-compatible",
+ "apiKey": "${OPENAI_API_KEY}",
+ "model": "text-embedding-3-small"
+ },
+ "autoCapture": true,
+ "autoRecall": true,
+ "smartExtraction": true,
+ "extractMinMessages": 2,
+ "extractMaxChars": 8000,
+ "sessionMemory": { "enabled": false }
+ }
+ }
+ }
+ }
+}
+```
+
+**Perché questi valori predefiniti?**
+- `autoCapture` + `smartExtraction` → il tuo agente impara automaticamente da ogni conversazione
+- `autoRecall` → i ricordi rilevanti vengono iniettati prima di ogni risposta
+- `extractMinMessages: 2` → l'estrazione si attiva nelle normali chat a due turni
+- `sessionMemory.enabled: false` → evita di inquinare la ricerca con riassunti di sessione all'inizio
+
+Valida e riavvia:
+
+```bash
+openclaw config validate
+openclaw gateway restart
+openclaw logs --follow --plain | grep "memory-lancedb-pro"
+```
+
+Dovresti vedere:
+- `memory-lancedb-pro: smart extraction enabled`
+- `memory-lancedb-pro@...: plugin registered`
+
+Fatto! Il tuo agente ora ha una memoria a lungo termine.
+
+
+
+
+Ulteriori percorsi di installazione (utenti esistenti, aggiornamenti)
+ +**Usi già OpenClaw?** + +1. Aggiungi il plugin con un percorso **assoluto** in `plugins.load.paths` +2. Associa lo slot di memoria: `plugins.slots.memory = "memory-lancedb-pro"` +3. Verifica: `openclaw plugins info memory-lancedb-pro && openclaw memory-pro stats` + +**Aggiornamento da versioni precedenti alla v1.1.0?** + +```bash +# 1) Backup +openclaw memory-pro export --scope global --output memories-backup.json +# 2) Dry run +openclaw memory-pro upgrade --dry-run +# 3) Run upgrade +openclaw memory-pro upgrade +# 4) Verify +openclaw memory-pro stats +``` + +Vedi `CHANGELOG-v1.1.0.md` per le modifiche comportamentali e le motivazioni dell'aggiornamento. + +
+
+
+---
+
+## Ecosistema
+
+memory-lancedb-pro è il plugin principale. La community ha costruito strumenti per rendere l'installazione e l'uso quotidiano ancora più fluidi:
+
+### Script di installazione — Installazione, aggiornamento e riparazione con un clic
+
+> **[CortexReach/toolbox/memory-lancedb-pro-setup](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)**
+
+Non è un semplice installer — lo script gestisce in modo intelligente numerosi scenari reali:
+
+| La tua situazione | Cosa fa lo script |
+|---|---|
+| Mai installato | Download → installazione dipendenze → scelta configurazione → scrittura in openclaw.json → riavvio |
+| Installato tramite `git clone`, bloccato su un vecchio commit | `git fetch` + `checkout` automatico all'ultima versione → reinstallazione dipendenze → verifica |
+| La configurazione ha campi non validi | Rilevamento automatico tramite filtro schema, rimozione campi non supportati |
+| Installato tramite `npm` | Salta l'aggiornamento git, ricorda di eseguire `npm update` autonomamente |
+| CLI `openclaw` non funzionante per configurazione non valida | Fallback: lettura diretta del percorso workspace dal file `openclaw.json` |
+| `extensions/` invece di `plugins/` | Rilevamento automatico della posizione del plugin da configurazione o filesystem |
+| Già aggiornato | Solo controlli di integrità, nessuna modifica |
+
+```bash
+bash setup-memory.sh # Installa o aggiorna
+bash setup-memory.sh --dry-run # Solo anteprima
+bash setup-memory.sh --beta # Includi versioni pre-release
+bash setup-memory.sh --uninstall # Ripristina configurazione e rimuovi plugin
+```
+
+Preset di provider integrati: **Jina / DashScope / SiliconFlow / OpenAI / Ollama**, oppure usa la tua API compatibile OpenAI. Per l'utilizzo completo (inclusi `--ref`, `--selfcheck-only` e altro), consulta il [README dello script di installazione](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup).
+
+### Claude Code / OpenClaw Skill — Configurazione guidata dall'IA
+
+> **[CortexReach/memory-lancedb-pro-skill](https://github.com/CortexReach/memory-lancedb-pro-skill)**
+
+Installa questa Skill e il tuo agente IA (Claude Code o OpenClaw) acquisisce una conoscenza approfondita di tutte le funzionalità di memory-lancedb-pro. Basta dire **"aiutami ad attivare la configurazione migliore"** per ottenere:
+
+- **Workflow di configurazione guidato in 7 passaggi** con 4 piani di distribuzione:
+ - Full Power (Jina + OpenAI) / Budget (reranker SiliconFlow gratuito) / Simple (solo OpenAI) / Completamente locale (Ollama, zero costi API)
+- **Tutti i 9 strumenti MCP** usati correttamente: `memory_recall`, `memory_store`, `memory_forget`, `memory_update`, `memory_stats`, `memory_list`, `self_improvement_log`, `self_improvement_extract_skill`, `self_improvement_review` *(il set completo richiede `enableManagementTools: true` — la configurazione Quick Start predefinita espone i 4 strumenti principali)*
+- **Prevenzione delle insidie comuni**: attivazione plugin workspace, `autoRecall` predefinito a false, cache jiti, variabili d'ambiente, isolamento scope, ecc.
+
+**Installazione per Claude Code:**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro
+```
+
+**Installazione per OpenClaw:**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill
+```
+
+---
+
+## Tutorial video
+
+> Guida completa: installazione, configurazione e funzionamento interno della ricerca ibrida.
+
+[](https://youtu.be/MtukF1C8epQ)
+**https://youtu.be/MtukF1C8epQ**
+
+[](https://www.bilibili.com/video/BV1zUf2BGEgn/)
+**https://www.bilibili.com/video/BV1zUf2BGEgn/**
+
+---
+
+## Architettura
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ index.ts (Entry Point) │
+│ Plugin Registration · Config Parsing · Lifecycle Hooks │
+└────────┬──────────┬──────────┬──────────┬───────────────┘
+ │ │ │ │
+ ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
+ │ store │ │embedder│ │retriever│ │ scopes │
+ │ .ts │ │ .ts │ │ .ts │ │ .ts │
+ └────────┘ └────────┘ └────────┘ └─────────────┘
+ │ │
+ ┌────▼───┐ ┌─────▼──────────┐
+ │migrate │ │noise-filter.ts │
+ │ .ts │ │adaptive- │
+ └────────┘ │retrieval.ts │
+ └────────────────┘
+ ┌─────────────┐ ┌──────────┐
+ │ tools.ts │ │ cli.ts │
+ │ (Agent API) │ │ (CLI) │
+ └─────────────┘ └──────────┘
+```
+
+> Per un approfondimento sull'architettura completa, consulta [docs/memory_architecture_analysis.md](docs/memory_architecture_analysis.md).
+
+Importazione rapida Telegram Bot (clicca per espandere)
+ +Se stai usando l'integrazione Telegram di OpenClaw, il modo più semplice è inviare un comando di importazione direttamente al Bot principale invece di modificare manualmente la configurazione. + +Invia questo messaggio: + +```text +Help me connect this memory plugin with the most user-friendly configuration: https://github.com/CortexReach/memory-lancedb-pro + +Requirements: +1. Set it as the only active memory plugin +2. Use Jina for embedding +3. Use Jina for reranker +4. Use gpt-4o-mini for the smart-extraction LLM +5. Enable autoCapture, autoRecall, smartExtraction +6. extractMinMessages=2 +7. sessionMemory.enabled=false +8. captureAssistant=false +9. retrieval mode=hybrid, vectorWeight=0.7, bm25Weight=0.3 +10. rerank=cross-encoder, candidatePoolSize=12, minScore=0.6, hardMinScore=0.62 +11. Generate the final openclaw.json config directly, not just an explanation +``` + +
+
+
+---
+
+## Funzionalità principali
+
+### Ricerca ibrida
+
+```
+Query → embedQuery() ─┐
+ ├─→ Hybrid Fusion → Rerank → Lifecycle Decay Boost → Length Norm → Filter
+Query → BM25 FTS ─────┘
+```
+
+- **Ricerca vettoriale** — similarità semantica tramite LanceDB ANN (distanza del coseno)
+- **Ricerca full-text BM25** — corrispondenza esatta delle parole chiave tramite indice FTS di LanceDB
+- **Fusione ibrida** — punteggio vettoriale come base, i risultati BM25 ricevono un boost ponderato (non RRF standard — ottimizzato per la qualità di richiamo nel mondo reale)
+- **Pesi configurabili** — `vectorWeight`, `bm25Weight`, `minScore`
+
+### Reranking Cross-Encoder
+
+- Adattatori integrati per **Jina**, **SiliconFlow**, **Voyage AI** e **Pinecone**
+- Compatibile con qualsiasi endpoint compatibile Jina (ad es. Hugging Face TEI, DashScope)
+- Punteggio ibrido: 60% cross-encoder + 40% punteggio fuso originale
+- Degradazione elegante: fallback sulla similarità del coseno in caso di errore API
+
+### Pipeline di punteggio multi-fase
+
+| Fase | Effetto |
+| --- | --- |
+| **Fusione ibrida** | Combina richiamo semantico e corrispondenza esatta |
+| **Rerank Cross-Encoder** | Promuove risultati semanticamente precisi |
+| **Boost decadimento ciclo di vita** | Freschezza Weibull + frequenza di accesso + importance × confidence |
+| **Normalizzazione lunghezza** | Impedisce alle voci lunghe di dominare (ancora: 500 caratteri) |
+| **Punteggio minimo rigido** | Rimuove risultati irrilevanti (predefinito: 0.35) |
+| **Diversità MMR** | Similarità coseno > 0.85 → retrocesso |
+
+### Estrazione intelligente della memoria (v1.1.0)
+
+- **Estrazione LLM in 6 categorie**: profilo, preferenze, entità, eventi, casi, pattern
+- **Archiviazione a strati L0/L1/L2**: L0 (indice in una frase) → L1 (riepilogo strutturato) → L2 (narrazione completa)
+- **Deduplicazione in due fasi**: pre-filtro similarità vettoriale (≥0.7) → decisione semantica LLM (CREATE/MERGE/SKIP)
+- **Fusione consapevole delle categorie**: `profile` viene sempre fuso, `events`/`cases` solo in aggiunta
+
+### Gestione del ciclo di vita della memoria (v1.1.0)
+
+- **Motore di decadimento Weibull**: punteggio composito = freschezza + frequenza + valore intrinseco
+- **Promozione a tre livelli**: `Peripheral ↔ Working ↔ Core` con soglie configurabili
+- **Rinforzo per accesso**: i ricordi richiamati frequentemente decadono più lentamente (stile ripetizione spaziata)
+- **Emivita modulata dall'importanza**: i ricordi importanti decadono più lentamente
+
+### Isolamento multi-scope
+
+- Scope integrati: `global`, `agent:Riferimento file (clicca per espandere)
+ +| File | Scopo | +| --- | --- | +| `index.ts` | Punto di ingresso del plugin. Si registra con l'API Plugin di OpenClaw, analizza la configurazione, monta gli hook del ciclo di vita | +| `openclaw.plugin.json` | Metadati del plugin + dichiarazione completa della configurazione JSON Schema | +| `cli.ts` | Comandi CLI: `memory-pro list/search/stats/delete/delete-bulk/export/import/reembed/upgrade/migrate` | +| `src/store.ts` | Layer di storage LanceDB. Creazione tabelle / indicizzazione FTS / ricerca vettoriale / ricerca BM25 / CRUD | +| `src/embedder.ts` | Astrazione embedding. Compatibile con qualsiasi provider API compatibile OpenAI | +| `src/retriever.ts` | Motore di ricerca ibrido. Vettoriale + BM25 → Fusione ibrida → Rerank → Decadimento ciclo di vita → Filtro | +| `src/scopes.ts` | Controllo accessi multi-scope | +| `src/tools.ts` | Definizioni degli strumenti agente: `memory_recall`, `memory_store`, `memory_forget`, `memory_update` + strumenti di gestione | +| `src/noise-filter.ts` | Filtra rifiuti dell'agente, meta-domande, saluti e contenuti di bassa qualità | +| `src/adaptive-retrieval.ts` | Determina se una query necessita di ricerca nella memoria | +| `src/migrate.ts` | Migrazione dal `memory-lancedb` integrato a Pro | +| `src/smart-extractor.ts` | Estrazione LLM in 6 categorie con archiviazione a strati L0/L1/L2 e deduplicazione in due fasi | +| `src/decay-engine.ts` | Modello di decadimento esponenziale esteso Weibull | +| `src/tier-manager.ts` | Promozione/retrocessione a tre livelli: Peripheral ↔ Working ↔ Core | + +
+Confronto con
+
+| Funzionalità | `memory-lancedb` integrato | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| Ricerca vettoriale | Sì | Sì |
+| Ricerca full-text BM25 | - | Sì |
+| Fusione ibrida (Vettoriale + BM25) | - | Sì |
+| Rerank cross-encoder (multi-provider) | - | Sì |
+| Boost di freschezza e decadimento temporale | - | Sì |
+| Normalizzazione lunghezza | - | Sì |
+| Diversità MMR | - | Sì |
+| Isolamento multi-scope | - | Sì |
+| Filtraggio del rumore | - | Sì |
+| Ricerca adattiva | - | Sì |
+| CLI di gestione | - | Sì |
+| Memoria di sessione | - | Sì |
+| Embedding task-aware | - | Sì |
+| **Estrazione intelligente LLM (6 categorie)** | - | Sì (v1.1.0) |
+| **Decadimento Weibull + promozione livelli** | - | Sì (v1.1.0) |
+| Qualsiasi embedding compatibile OpenAI | Limitato | Sì |
+
+
+
+---
+
+## Configurazione
+
+Confronto con memory-lancedb integrato (clicca per espandere)
+
+| Funzionalità | `memory-lancedb` integrato | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| Ricerca vettoriale | Sì | Sì |
+| Ricerca full-text BM25 | - | Sì |
+| Fusione ibrida (Vettoriale + BM25) | - | Sì |
+| Rerank cross-encoder (multi-provider) | - | Sì |
+| Boost di freschezza e decadimento temporale | - | Sì |
+| Normalizzazione lunghezza | - | Sì |
+| Diversità MMR | - | Sì |
+| Isolamento multi-scope | - | Sì |
+| Filtraggio del rumore | - | Sì |
+| Ricerca adattiva | - | Sì |
+| CLI di gestione | - | Sì |
+| Memoria di sessione | - | Sì |
+| Embedding task-aware | - | Sì |
+| **Estrazione intelligente LLM (6 categorie)** | - | Sì (v1.1.0) |
+| **Decadimento Weibull + promozione livelli** | - | Sì (v1.1.0) |
+| Qualsiasi embedding compatibile OpenAI | Limitato | Sì |
+
+
+
+
+Esempio di configurazione completa
+ +```json +{ + "embedding": { + "apiKey": "${JINA_API_KEY}", + "model": "jina-embeddings-v5-text-small", + "baseURL": "https://api.jina.ai/v1", + "dimensions": 1024, + "taskQuery": "retrieval.query", + "taskPassage": "retrieval.passage", + "normalized": true + }, + "dbPath": "~/.openclaw/memory/lancedb-pro", + "autoCapture": true, + "autoRecall": true, + "retrieval": { + "mode": "hybrid", + "vectorWeight": 0.7, + "bm25Weight": 0.3, + "minScore": 0.3, + "rerank": "cross-encoder", + "rerankApiKey": "${JINA_API_KEY}", + "rerankModel": "jina-reranker-v3", + "rerankEndpoint": "https://api.jina.ai/v1/rerank", + "rerankProvider": "jina", + "candidatePoolSize": 20, + "recencyHalfLifeDays": 14, + "recencyWeight": 0.1, + "filterNoise": true, + "lengthNormAnchor": 500, + "hardMinScore": 0.35, + "timeDecayHalfLifeDays": 60, + "reinforcementFactor": 0.5, + "maxHalfLifeMultiplier": 3 + }, + "enableManagementTools": false, + "scopes": { + "default": "global", + "definitions": { + "global": { "description": "Shared knowledge" }, + "agent:discord-bot": { "description": "Discord bot private" } + }, + "agentAccess": { + "discord-bot": ["global", "agent:discord-bot"] + } + }, + "sessionMemory": { + "enabled": false, + "messageCount": 15 + }, + "smartExtraction": true, + "llm": { + "apiKey": "${OPENAI_API_KEY}", + "model": "gpt-4o-mini", + "baseURL": "https://api.openai.com/v1" + }, + "extractMinMessages": 2, + "extractMaxChars": 8000 +} +``` + +
+
+
+Provider di embedding
+ +Funziona con **qualsiasi API di embedding compatibile OpenAI**: + +| Provider | Modello | Base URL | Dimensioni | +| --- | --- | --- | --- | +| **Jina** (consigliato) | `jina-embeddings-v5-text-small` | `https://api.jina.ai/v1` | 1024 | +| **OpenAI** | `text-embedding-3-small` | `https://api.openai.com/v1` | 1536 | +| **Voyage** | `voyage-4-lite` / `voyage-4` | `https://api.voyageai.com/v1` | 1024 / 1024 | +| **Google Gemini** | `gemini-embedding-001` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 | +| **Ollama** (locale) | `nomic-embed-text` | `http://localhost:11434/v1` | specifico del provider | + +
+
+
+Provider di rerank
+ +Il reranking cross-encoder supporta più provider tramite `rerankProvider`: + +| Provider | `rerankProvider` | Modello di esempio | +| --- | --- | --- | +| **Jina** (predefinito) | `jina` | `jina-reranker-v3` | +| **SiliconFlow** (piano gratuito disponibile) | `siliconflow` | `BAAI/bge-reranker-v2-m3` | +| **Voyage AI** | `voyage` | `rerank-2.5` | +| **Pinecone** | `pinecone` | `bge-reranker-v2-m3` | + +Funziona anche qualsiasi endpoint di rerank compatibile Jina — imposta `rerankProvider: "jina"` e punta `rerankEndpoint` al tuo servizio (ad es. Hugging Face TEI, DashScope `qwen3-rerank`). + +
+
+
+Estrazione intelligente (LLM) — v1.1.0
+ +Quando `smartExtraction` è abilitato (predefinito: `true`), il plugin utilizza un LLM per estrarre e classificare intelligentemente i ricordi invece di trigger basati su regex. + +| Campo | Tipo | Predefinito | Descrizione | +|-------|------|---------|-------------| +| `smartExtraction` | boolean | `true` | Abilita/disabilita l'estrazione LLM in 6 categorie | +| `llm.auth` | string | `api-key` | `api-key` usa `llm.apiKey` / `embedding.apiKey`; `oauth` usa un file token OAuth con scope plugin per impostazione predefinita | +| `llm.apiKey` | string | *(fallback su `embedding.apiKey`)* | Chiave API per il provider LLM | +| `llm.model` | string | `openai/gpt-oss-120b` | Nome del modello LLM | +| `llm.baseURL` | string | *(fallback su `embedding.baseURL`)* | Endpoint API LLM | +| `llm.oauthProvider` | string | `openai-codex` | ID del provider OAuth usato quando `llm.auth` è `oauth` | +| `llm.oauthPath` | string | `~/.openclaw/.memory-lancedb-pro/oauth.json` | File token OAuth usato quando `llm.auth` è `oauth` | +| `llm.timeoutMs` | number | `30000` | Timeout della richiesta LLM in millisecondi | +| `extractMinMessages` | number | `2` | Messaggi minimi prima che l'estrazione si attivi | +| `extractMaxChars` | number | `8000` | Caratteri massimi inviati al LLM | + + +Configurazione `llm` OAuth (usa la cache di login esistente di Codex / ChatGPT per le chiamate LLM): +```json +{ + "llm": { + "auth": "oauth", + "oauthProvider": "openai-codex", + "model": "gpt-5.4", + "oauthPath": "${HOME}/.openclaw/.memory-lancedb-pro/oauth.json", + "timeoutMs": 30000 + } +} +``` + +Note per `llm.auth: "oauth"`: + +- `llm.oauthProvider` è attualmente `openai-codex`. +- I token OAuth sono salvati di default in `~/.openclaw/.memory-lancedb-pro/oauth.json`. +- Puoi impostare `llm.oauthPath` se vuoi salvare quel file altrove. +- `auth login` crea uno snapshot della configurazione `llm` precedente con api-key accanto al file OAuth, e `auth logout` ripristina quello snapshot quando disponibile. +- Il passaggio da `api-key` a `oauth` non trasferisce automaticamente `llm.baseURL`. Impostalo manualmente in modalità OAuth solo quando vuoi intenzionalmente un backend personalizzato compatibile ChatGPT/Codex. + +
+
+
+Configurazione ciclo di vita (Decadimento + Livelli)
+ +| Campo | Predefinito | Descrizione | +|-------|---------|-------------| +| `decay.recencyHalfLifeDays` | `30` | Emivita base per il decadimento di freschezza Weibull | +| `decay.frequencyWeight` | `0.3` | Peso della frequenza di accesso nel punteggio composito | +| `decay.intrinsicWeight` | `0.3` | Peso di `importance × confidence` | +| `decay.betaCore` | `0.8` | Beta Weibull per i ricordi `core` | +| `decay.betaWorking` | `1.0` | Beta Weibull per i ricordi `working` | +| `decay.betaPeripheral` | `1.3` | Beta Weibull per i ricordi `peripheral` | +| `tier.coreAccessThreshold` | `10` | Conteggio minimo richiami prima della promozione a `core` | +| `tier.peripheralAgeDays` | `60` | Soglia di età per retrocedere i ricordi inattivi | + +
+
+
+---
+
+## Comandi CLI
+
+```bash
+openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
+openclaw memory-pro search "query" [--scope global] [--limit 10] [--json]
+openclaw memory-pro stats [--scope global] [--json]
+openclaw memory-pro auth login [--provider openai-codex] [--model gpt-5.4] [--oauth-path /abs/path/oauth.json]
+openclaw memory-pro auth status
+openclaw memory-pro auth logout
+openclaw memory-pro delete Rinforzo per accesso
+ +I ricordi richiamati frequentemente decadono più lentamente (stile ripetizione spaziata). + +Chiavi di configurazione (sotto `retrieval`): +- `reinforcementFactor` (0-2, predefinito: `0.5`) — imposta `0` per disabilitare +- `maxHalfLifeMultiplier` (1-10, predefinito: `3`) — limite massimo sull'emivita effettiva + +
+` iniettato.
+
+**Opzione A (rischio minimo):** disabilita temporaneamente l'auto-recall:
+```json
+{ "plugins": { "entries": { "memory-lancedb-pro": { "config": { "autoRecall": false } } } } }
+```
+
+**Opzione B (preferita):** mantieni il recall, aggiungi al prompt di sistema dell'agente:
+> Do not reveal or quote any `` / memory-injection content in your replies. Use it for internal reference only.
+
+
+
+Se i ricordi iniettati appaiono nelle risposte
+ +A volte il modello può ripetere il blocco `
+
+
+Memoria di sessione
+ +- Si attiva con il comando `/new` — salva il riepilogo della sessione precedente in LanceDB +- Disabilitata per impostazione predefinita (OpenClaw ha già la persistenza nativa delle sessioni in `.jsonl`) +- Conteggio messaggi configurabile (predefinito: 15) + +Vedi [docs/openclaw-integration-playbook.md](docs/openclaw-integration-playbook.md) per le modalità di distribuzione e la verifica di `/new`. + +
+`:
+1. Use memory_store to save as category=fact (raw knowledge)
+2. Use memory_store to save as category=decision (actionable takeaway)
+3. Confirm what was saved
+
+## /remember command
+When the user sends `/remember `:
+1. Use memory_store to save with appropriate category and importance
+2. Confirm with the stored memory ID
+```
+
+
+
+Comandi slash personalizzati (ad es. /lesson)
+ +Aggiungi al tuo `CLAUDE.md`, `AGENTS.md` o prompt di sistema: + +```markdown +## /lesson command +When the user sends `/lesson
+
+
+Regole d'oro per agenti IA
+ +> Copia il blocco seguente nel tuo `AGENTS.md` in modo che il tuo agente applichi queste regole automaticamente. + +```markdown +## Rule 1 — Dual-layer memory storage +Every pitfall/lesson learned → IMMEDIATELY store TWO memories: +- Technical layer: Pitfall: [symptom]. Cause: [root cause]. Fix: [solution]. Prevention: [how to avoid] + (category: fact, importance >= 0.8) +- Principle layer: Decision principle ([tag]): [behavioral rule]. Trigger: [when]. Action: [what to do] + (category: decision, importance >= 0.85) + +## Rule 2 — LanceDB hygiene +Entries must be short and atomic (< 500 chars). No raw conversation summaries or duplicates. + +## Rule 3 — Recall before retry +On ANY tool failure, ALWAYS memory_recall with relevant keywords BEFORE retrying. + +## Rule 4 — Confirm target codebase +Confirm you are editing memory-lancedb-pro vs built-in memory-lancedb before changes. + +## Rule 5 — Clear jiti cache after plugin code changes +After modifying .ts files under plugins/, MUST run rm -rf /tmp/jiti/ BEFORE openclaw gateway restart. +``` + +
+
+
+Schema del database
+ +Tabella LanceDB `memories`: + +| Campo | Tipo | Descrizione | +| --- | --- | --- | +| `id` | string (UUID) | Chiave primaria | +| `text` | string | Testo del ricordo (indicizzato FTS) | +| `vector` | float[] | Vettore di embedding | +| `category` | string | Categoria di archiviazione: `preference` / `fact` / `decision` / `entity` / `reflection` / `other` | +| `scope` | string | Identificatore scope (ad es. `global`, `agent:main`) | +| `importance` | float | Punteggio di importanza 0-1 | +| `timestamp` | int64 | Timestamp di creazione (ms) | +| `metadata` | string (JSON) | Metadati estesi | + +Chiavi `metadata` comuni nella v1.1.0: `l0_abstract`, `l1_overview`, `l2_content`, `memory_category`, `tier`, `access_count`, `confidence`, `last_accessed_at` + +> **Nota sulle categorie:** Il campo `category` di primo livello usa 6 categorie di archiviazione. Le 6 etichette semantiche dell'Estrazione Intelligente (`profile` / `preferences` / `entities` / `events` / `cases` / `patterns`) sono memorizzate in `metadata.memory_category`. + +
+
+
+---
+
+## Documentazione
+
+| Documento | Descrizione |
+| --- | --- |
+| [Playbook di integrazione OpenClaw](docs/openclaw-integration-playbook.md) | Modalità di distribuzione, verifica, matrice di regressione |
+| [Analisi dell'architettura della memoria](docs/memory_architecture_analysis.md) | Analisi approfondita dell'architettura completa |
+| [CHANGELOG v1.1.0](docs/CHANGELOG-v1.1.0.md) | Modifiche comportamentali v1.1.0 e motivazioni per l'upgrade |
+| [Chunking contesto lungo](docs/long-context-chunking.md) | Strategia di chunking per documenti lunghi |
+
+---
+
+## Beta: Smart Memory v1.1.0
+
+> Stato: Beta — disponibile tramite `npm i memory-lancedb-pro@beta`. Gli utenti stabili su `latest` non sono interessati.
+
+| Funzionalità | Descrizione |
+|---------|-------------|
+| **Estrazione intelligente** | Estrazione LLM in 6 categorie con metadati L0/L1/L2. Fallback su regex se disabilitato. |
+| **Punteggio ciclo di vita** | Decadimento Weibull integrato nella ricerca — i ricordi frequenti e importanti si posizionano più in alto. |
+| **Gestione livelli** | Sistema a tre livelli (Core → Working → Peripheral) con promozione/retrocessione automatica. |
+
+Feedback: [GitHub Issues](https://github.com/CortexReach/memory-lancedb-pro/issues) · Ripristina: `npm i memory-lancedb-pro@latest`
+
+---
+
+## Dipendenze
+
+| Pacchetto | Scopo |
+| --- | --- |
+| `@lancedb/lancedb` ≥0.26.2 | Database vettoriale (ANN + FTS) |
+| `openai` ≥6.21.0 | Client API Embedding compatibile OpenAI |
+| `@sinclair/typebox` 0.34.48 | Definizioni di tipo JSON Schema |
+
+---
+
+## Contributors
+
+Risoluzione dei problemi
+ +### "Cannot mix BigInt and other types" (LanceDB / Apache Arrow) + +Con LanceDB 0.26+, alcune colonne numeriche potrebbero essere restituite come `BigInt`. Aggiorna a **memory-lancedb-pro >= 1.0.14** — questo plugin ora converte i valori usando `Number(...)` prima delle operazioni aritmetiche. + +
+
+
+# 🧠 memory-lancedb-pro · 🦞OpenClaw Plugin
+
+**[OpenClaw](https://github.com/openclaw/openclaw) エージェント向け AI メモリアシスタント**
+
+*あなたの AI エージェントに本物の記憶力を——セッションを超え、エージェントを超え、時間を超えて。*
+
+LanceDB ベースの OpenClaw 長期メモリプラグイン。好み・意思決定・プロジェクトコンテキストを自動保存し、将来のセッションで自動的に想起します。
+
+[](https://github.com/openclaw/openclaw)
+[](https://www.npmjs.com/package/memory-lancedb-pro)
+[](https://lancedb.com)
+[](LICENSE)
+
+[English](README.md) | [简体中文](README_CN.md) | [繁體中文](README_TW.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | [Español](README_ES.md) | [Deutsch](README_DE.md) | [Italiano](README_IT.md) | [Русский](README_RU.md) | [Português (Brasil)](README_PT-BR.md)
+
+
+
+---
+
+## なぜ memory-lancedb-pro なのか？
+
+ほとんどの AI エージェントは「記憶喪失」です——新しいチャットを始めるたびに、以前の会話内容はすべてリセットされます。
+
+**memory-lancedb-pro** は OpenClaw 向けのプロダクショングレードの長期メモリプラグインです。エージェントを真の **AI メモリアシスタント** に変えます——重要な情報を自動的にキャプチャし、ノイズを自然に減衰させ、適切なタイミングで適切な記憶を呼び出します。手動タグ付けも複雑な設定も不要です。
+
+### AI メモリアシスタントの実際の動作
+
+**メモリなし——毎回ゼロからスタート：**
+
+> **あなた：** 「インデントはタブで、常にエラーハンドリングを追加して。」
+> *（次のセッション）*
+> **あなた：** 「前に言ったでしょ——タブであってスペースじゃない！」 😤
+> *（さらに次のセッション）*
+> **あなた：** 「……本当にもう3回目だよ、タブ。あとエラーハンドリングも。」
+
+**memory-lancedb-pro あり——エージェントが学習し記憶する：**
+
+> **あなた：** 「インデントはタブで、常にエラーハンドリングを追加して。」
+> *（次のセッション——エージェントが自動的にあなたの好みを想起）*
+> **エージェント：** *（黙ってタブインデント＋エラーハンドリングを適用）* ✅
+> **あなた：** 「先月なぜ MongoDB ではなく PostgreSQL を選んだんだっけ？」
+> **エージェント：** 「2月12日の議論に基づくと、主な理由は……」 ✅
+
+これが **AI メモリアシスタント** の価値です——あなたのスタイルを学び、過去の意思決定を想起し、繰り返し説明することなくパーソナライズされた応答を提供します。
+
+### 他に何ができる？
+
+| | 得られるもの |
+|---|---|
+| **自動キャプチャ** | エージェントが毎回の会話から学習——手動で `memory_store` を呼ぶ必要なし |
+| **スマート抽出** | LLM 駆動の6カテゴリ分類：プロフィール、好み、エンティティ、イベント、ケース、パターン |
+| **インテリジェント忘却** | Weibull 減衰モデル——重要な記憶は残り、ノイズは自然に消える |
+| **ハイブリッド検索** | ベクトル + BM25 全文検索、クロスエンコーダーリランキングで融合 |
+| **コンテキスト注入** | 関連する記憶が各応答前に自動的に浮上 |
+| **マルチスコープ分離** | エージェント別、ユーザー別、プロジェクト別のメモリ境界 |
+| **任意のプロバイダー** | OpenAI、Jina、Gemini、Ollama、または任意の OpenAI 互換 API |
+| **フルツールキット** | CLI、バックアップ、マイグレーション、アップグレード、エクスポート/インポート——本番運用対応 |
+
+---
+
+## クイックスタート
+
+### 方法 A：ワンクリックインストールスクリプト（推奨）
+
+コミュニティが管理する **[セットアップスクリプト](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)** で、インストール・アップグレード・修復を1コマンドで実行：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
+bash setup-memory.sh
+```
+
+> スクリプトがカバーするシナリオの完全なリストとその他のコミュニティツールは、以下の [エコシステム](#エコシステム) をご覧ください。
+
+### 方法 B：手動インストール
+
+**OpenClaw CLI 経由（推奨）：**
+```bash
+openclaw plugins install memory-lancedb-pro@beta
+```
+
+**または npm 経由：**
+```bash
+npm i memory-lancedb-pro@beta
+```
+> npm を使用する場合、`openclaw.json` の `plugins.load.paths` にプラグインのインストールディレクトリの **絶対パス** を追加する必要があります。これが最も一般的なセットアップの問題です。
+
+`openclaw.json` に以下を追加：
+
+```json
+{
+ "plugins": {
+ "slots": { "memory": "memory-lancedb-pro" },
+ "entries": {
+ "memory-lancedb-pro": {
+ "enabled": true,
+ "config": {
+ "embedding": {
+ "provider": "openai-compatible",
+ "apiKey": "${OPENAI_API_KEY}",
+ "model": "text-embedding-3-small"
+ },
+ "autoCapture": true,
+ "autoRecall": true,
+ "smartExtraction": true,
+ "extractMinMessages": 2,
+ "extractMaxChars": 8000,
+ "sessionMemory": { "enabled": false }
+ }
+ }
+ }
+ }
+}
+```
+
+**これらのデフォルト値の理由：**
+- `autoCapture` + `smartExtraction` → エージェントが毎回の会話から自動的に学習
+- `autoRecall` → 関連する記憶が各応答前に自動注入
+- `extractMinMessages: 2` → 通常の2ターン会話で抽出がトリガー
+- `sessionMemory.enabled: false` → 初期段階でセッション要約が検索結果を汚染するのを回避
+
+検証と再起動：
+
+```bash
+openclaw config validate
+openclaw gateway restart
+openclaw logs --follow --plain | grep "memory-lancedb-pro"
+```
+
+以下が表示されるはずです：
+- `memory-lancedb-pro: smart extraction enabled`
+- `memory-lancedb-pro@...: plugin registered`
+
+完了！あなたのエージェントは長期メモリを持つようになりました。
+
+
+
+
+その他のインストール方法（既存ユーザー、アップグレード）
+ +**既に OpenClaw を使用中？** + +1. `plugins.load.paths` にプラグインの **絶対パス** を追加 +2. メモリスロットをバインド：`plugins.slots.memory = "memory-lancedb-pro"` +3. 検証：`openclaw plugins info memory-lancedb-pro && openclaw memory-pro stats` + +**v1.1.0 以前からのアップグレード？** + +```bash +# 1) バックアップ +openclaw memory-pro export --scope global --output memories-backup.json +# 2) ドライラン +openclaw memory-pro upgrade --dry-run +# 3) アップグレード実行 +openclaw memory-pro upgrade +# 4) 検証 +openclaw memory-pro stats +``` + +動作変更とアップグレードの詳細は `CHANGELOG-v1.1.0.md` を参照してください。 + +
+
+
+---
+
+## エコシステム
+
+memory-lancedb-pro はコアプラグインです。コミュニティがセットアップと日常利用をさらにスムーズにするツールを構築しています：
+
+### セットアップスクリプト——ワンクリックでインストール・アップグレード・修復
+
+> **[CortexReach/toolbox/memory-lancedb-pro-setup](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)**
+
+単なるインストーラーではありません——さまざまな実際のシナリオをインテリジェントに処理します：
+
+| あなたの状況 | スクリプトの動作 |
+|---|---|
+| 未インストール | 新規ダウンロード → 依存関係インストール → 設定選択 → openclaw.json に書き込み → 再起動 |
+| `git clone` でインストール済み、古いコミットで停滞 | 自動で `git fetch` + `checkout` を最新版に → 依存関係再インストール → 検証 |
+| 設定に無効なフィールドがある | スキーマフィルターで自動検出し、サポートされていないフィールドを除去 |
+| `npm` でインストール済み | git 更新をスキップし、`npm update` の実行を促す |
+| 無効な設定で `openclaw` CLI が壊れている | フォールバック：`openclaw.json` ファイルからワークスペースパスを直接読み取り |
+| `plugins/` ではなく `extensions/` | 設定またはファイルシステムからプラグインの場所を自動検出 |
+| 既に最新版 | ヘルスチェックのみ実行、変更なし |
+
+```bash
+bash setup-memory.sh # インストールまたはアップグレード
+bash setup-memory.sh --dry-run # プレビューのみ
+bash setup-memory.sh --beta # プレリリース版を含む
+bash setup-memory.sh --uninstall # 設定を元に戻しプラグインを削除
+```
+
+内蔵プロバイダープリセット：**Jina / DashScope / SiliconFlow / OpenAI / Ollama**、または任意の OpenAI 互換 API を利用可能。完全な使用方法（`--ref`、`--selfcheck-only` など）は [セットアップスクリプト README](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup) を参照してください。
+
+### Claude Code / OpenClaw Skill——AI ガイド付き設定
+
+> **[CortexReach/memory-lancedb-pro-skill](https://github.com/CortexReach/memory-lancedb-pro-skill)**
+
+この Skill をインストールすると、AI エージェント（Claude Code または OpenClaw）が memory-lancedb-pro のすべての機能を深く理解できるようになります。**「最適な設定を有効にして」** と言うだけで：
+
+- **7ステップのガイド付き設定ワークフロー**、4つのデプロイプランを提供：
+ - フルパワー版（Jina + OpenAI）/ コスト削減版（無料の SiliconFlow リランカー）/ シンプル版（OpenAI のみ）/ 完全ローカル版（Ollama、API コストゼロ）
+- **全9つの MCP ツール** の正しい使い方：`memory_recall`、`memory_store`、`memory_forget`、`memory_update`、`memory_stats`、`memory_list`、`self_improvement_log`、`self_improvement_extract_skill`、`self_improvement_review` *（フルツールセットには `enableManagementTools: true` が必要——デフォルトのクイックスタート設定では4つのコアツールのみ公開）*
+- **よくある落とし穴の回避**：ワークスペースプラグインの有効化、`autoRecall` のデフォルト false、jiti キャッシュ、環境変数、スコープ分離など
+
+**Claude Code へのインストール：**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro
+```
+
+**OpenClaw へのインストール：**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill
+```
+
+---
+
+## 動画チュートリアル
+
+> フルウォークスルー：インストール、設定、ハイブリッド検索の内部構造。
+
+[](https://youtu.be/MtukF1C8epQ)
+**https://youtu.be/MtukF1C8epQ**
+
+[](https://www.bilibili.com/video/BV1zUf2BGEgn/)
+**https://www.bilibili.com/video/BV1zUf2BGEgn/**
+
+---
+
+## アーキテクチャ
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ index.ts（エントリポイント） │
+│ プラグイン登録 · 設定解析 · ライフサイクルフック │
+└────────┬──────────┬──────────┬──────────┬───────────────┘
+ │ │ │ │
+ ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
+ │ store │ │embedder│ │retriever│ │ scopes │
+ │ .ts │ │ .ts │ │ .ts │ │ .ts │
+ └────────┘ └────────┘ └────────┘ └─────────────┘
+ │ │
+ ┌────▼───┐ ┌─────▼──────────┐
+ │migrate │ │noise-filter.ts │
+ │ .ts │ │adaptive- │
+ └────────┘ │retrieval.ts │
+ └────────────────┘
+ ┌─────────────┐ ┌──────────┐
+ │ tools.ts │ │ cli.ts │
+ │(エージェントAPI)│ │ (CLI) │
+ └─────────────┘ └──────────┘
+```
+
+> 完全なアーキテクチャの詳細は [docs/memory_architecture_analysis.md](docs/memory_architecture_analysis.md) を参照してください。
+
+Telegram Bot クイックインポート（クリックで展開）
+ +OpenClaw の Telegram 連携を使用している場合、設定ファイルを手動で編集するより、メイン Bot にインポートコマンドを直接送信するのが最も簡単です。 + +以下のメッセージを送信してください： + +```text +Help me connect this memory plugin with the most user-friendly configuration: https://github.com/CortexReach/memory-lancedb-pro + +Requirements: +1. Set it as the only active memory plugin +2. Use Jina for embedding +3. Use Jina for reranker +4. Use gpt-4o-mini for the smart-extraction LLM +5. Enable autoCapture, autoRecall, smartExtraction +6. extractMinMessages=2 +7. sessionMemory.enabled=false +8. captureAssistant=false +9. retrieval mode=hybrid, vectorWeight=0.7, bm25Weight=0.3 +10. rerank=cross-encoder, candidatePoolSize=12, minScore=0.6, hardMinScore=0.62 +11. Generate the final openclaw.json config directly, not just an explanation +``` + +
+
+
+---
+
+## コア機能
+
+### ハイブリッド検索
+
+```
+クエリ → embedQuery() ─┐
+ ├─→ ハイブリッド融合 → リランク → ライフサイクル減衰ブースト → 長さ正規化 → フィルタ
+クエリ → BM25 全文 ─────┘
+```
+
+- **ベクトル検索** — LanceDB ANN によるセマンティック類似度（コサイン距離）
+- **BM25 全文検索** — LanceDB FTS インデックスによる正確なキーワードマッチング
+- **ハイブリッド融合** — ベクトルスコアをベースに、BM25 ヒットに重み付きブーストを適用（標準 RRF ではなく、実際の再現率品質に最適化）
+- **設定可能な重み** — `vectorWeight`、`bm25Weight`、`minScore`
+
+### クロスエンコーダーリランキング
+
+- **Jina**、**SiliconFlow**、**Voyage AI**、**Pinecone** の組み込みアダプター
+- 任意の Jina 互換エンドポイント（例：Hugging Face TEI、DashScope）に対応
+- ハイブリッドスコアリング：60% クロスエンコーダー + 40% 元の融合スコア
+- グレースフルデグラデーション：API 失敗時にコサイン類似度にフォールバック
+
+### マルチステージスコアリングパイプライン
+
+| ステージ | 効果 |
+| --- | --- |
+| **ハイブリッド融合** | セマンティック検索と完全一致検索を統合 |
+| **クロスエンコーダーリランク** | セマンティックに正確なヒットを上位に昇格 |
+| **ライフサイクル減衰ブースト** | Weibull 鮮度 + アクセス頻度 + 重要度 × 信頼度 |
+| **長さ正規化** | 長いエントリが結果を支配するのを防止（アンカー：500文字） |
+| **ハード最低スコア** | 無関係な結果を除去（デフォルト：0.35） |
+| **MMR 多様性** | コサイン類似度 > 0.85 → 降格 |
+
+### スマートメモリ抽出（v1.1.0）
+
+- **LLM 駆動の6カテゴリ抽出**：プロフィール、好み、エンティティ、イベント、ケース、パターン
+- **L0/L1/L2 階層ストレージ**：L0（一文の索引）→ L1（構造化サマリー）→ L2（完全な記述）
+- **2段階重複排除**：ベクトル類似度プレフィルタ（≥0.7）→ LLM セマンティック判定（CREATE/MERGE/SKIP）
+- **カテゴリ対応マージ**：`profile` は常にマージ、`events`/`cases` は追記のみ
+
+### メモリライフサイクル管理（v1.1.0）
+
+- **Weibull 減衰エンジン**：複合スコア = 鮮度 + 頻度 + 内在的価値
+- **3段階昇格**：`周辺 ↔ ワーキング ↔ コア`、閾値は設定可能
+- **アクセス強化**：頻繁に想起される記憶はより遅く減衰（間隔反復スタイル）
+- **重要度変調半減期**：重要な記憶はより遅く減衰
+
+### マルチスコープ分離
+
+- 組み込みスコープ：`global`、`agent:ファイルリファレンス（クリックで展開）
+ +| ファイル | 用途 | +| --- | --- | +| `index.ts` | プラグインエントリポイント。OpenClaw Plugin API に登録、設定解析、ライフサイクルフックのマウント | +| `openclaw.plugin.json` | プラグインメタデータ + 完全な JSON Schema 設定宣言 | +| `cli.ts` | CLI コマンド：`memory-pro list/search/stats/delete/delete-bulk/export/import/reembed/upgrade/migrate` | +| `src/store.ts` | LanceDB ストレージレイヤー。テーブル作成 / FTS インデックス / ベクトル検索 / BM25 検索 / CRUD | +| `src/embedder.ts` | Embedding 抽象レイヤー。任意の OpenAI 互換 API プロバイダーに対応 | +| `src/retriever.ts` | ハイブリッド検索エンジン。ベクトル + BM25 → ハイブリッド融合 → リランク → ライフサイクル減衰 → フィルタ | +| `src/scopes.ts` | マルチスコープアクセス制御 | +| `src/tools.ts` | エージェントツール定義：`memory_recall`、`memory_store`、`memory_forget`、`memory_update` + 管理ツール | +| `src/noise-filter.ts` | エージェントの拒否応答、メタ質問、挨拶などの低品質コンテンツをフィルタリング | +| `src/adaptive-retrieval.ts` | クエリがメモリ検索を必要とするかどうかを判定 | +| `src/migrate.ts` | 内蔵 `memory-lancedb` から Pro へのマイグレーション | +| `src/smart-extractor.ts` | LLM 駆動の6カテゴリ抽出、L0/L1/L2 階層ストレージと2段階重複排除対応 | +| `src/decay-engine.ts` | Weibull 伸長指数関数減衰モデル | +| `src/tier-manager.ts` | 3段階昇格/降格：周辺 ↔ ワーキング ↔ コア | + +
+内蔵
+
+| 機能 | 内蔵 `memory-lancedb` | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| ベクトル検索 | あり | あり |
+| BM25 全文検索 | - | あり |
+| ハイブリッド融合（ベクトル + BM25） | - | あり |
+| クロスエンコーダーリランク（マルチプロバイダー） | - | あり |
+| 鮮度ブースト＆時間減衰 | - | あり |
+| 長さ正規化 | - | あり |
+| MMR 多様性 | - | あり |
+| マルチスコープ分離 | - | あり |
+| ノイズフィルタリング | - | あり |
+| アダプティブ検索 | - | あり |
+| 管理 CLI | - | あり |
+| セッションメモリ | - | あり |
+| タスク対応 Embedding | - | あり |
+| **LLM スマート抽出（6カテゴリ）** | - | あり（v1.1.0） |
+| **Weibull 減衰 + 階層昇格** | - | あり（v1.1.0） |
+| 任意の OpenAI 互換 Embedding | 限定的 | あり |
+
+
+
+---
+
+## 設定
+
+内蔵 memory-lancedb との比較（クリックで展開）
+
+| 機能 | 内蔵 `memory-lancedb` | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| ベクトル検索 | あり | あり |
+| BM25 全文検索 | - | あり |
+| ハイブリッド融合（ベクトル + BM25） | - | あり |
+| クロスエンコーダーリランク（マルチプロバイダー） | - | あり |
+| 鮮度ブースト＆時間減衰 | - | あり |
+| 長さ正規化 | - | あり |
+| MMR 多様性 | - | あり |
+| マルチスコープ分離 | - | あり |
+| ノイズフィルタリング | - | あり |
+| アダプティブ検索 | - | あり |
+| 管理 CLI | - | あり |
+| セッションメモリ | - | あり |
+| タスク対応 Embedding | - | あり |
+| **LLM スマート抽出（6カテゴリ）** | - | あり（v1.1.0） |
+| **Weibull 減衰 + 階層昇格** | - | あり（v1.1.0） |
+| 任意の OpenAI 互換 Embedding | 限定的 | あり |
+
+
+
+
+完全な設定例
+ +```json +{ + "embedding": { + "apiKey": "${JINA_API_KEY}", + "model": "jina-embeddings-v5-text-small", + "baseURL": "https://api.jina.ai/v1", + "dimensions": 1024, + "taskQuery": "retrieval.query", + "taskPassage": "retrieval.passage", + "normalized": true + }, + "dbPath": "~/.openclaw/memory/lancedb-pro", + "autoCapture": true, + "autoRecall": true, + "retrieval": { + "mode": "hybrid", + "vectorWeight": 0.7, + "bm25Weight": 0.3, + "minScore": 0.3, + "rerank": "cross-encoder", + "rerankApiKey": "${JINA_API_KEY}", + "rerankModel": "jina-reranker-v3", + "rerankEndpoint": "https://api.jina.ai/v1/rerank", + "rerankProvider": "jina", + "candidatePoolSize": 20, + "recencyHalfLifeDays": 14, + "recencyWeight": 0.1, + "filterNoise": true, + "lengthNormAnchor": 500, + "hardMinScore": 0.35, + "timeDecayHalfLifeDays": 60, + "reinforcementFactor": 0.5, + "maxHalfLifeMultiplier": 3 + }, + "enableManagementTools": false, + "scopes": { + "default": "global", + "definitions": { + "global": { "description": "Shared knowledge" }, + "agent:discord-bot": { "description": "Discord bot private" } + }, + "agentAccess": { + "discord-bot": ["global", "agent:discord-bot"] + } + }, + "sessionMemory": { + "enabled": false, + "messageCount": 15 + }, + "smartExtraction": true, + "llm": { + "apiKey": "${OPENAI_API_KEY}", + "model": "gpt-4o-mini", + "baseURL": "https://api.openai.com/v1" + }, + "extractMinMessages": 2, + "extractMaxChars": 8000 +} +``` + +
+
+
+Embedding プロバイダー
+ +**任意の OpenAI 互換 Embedding API** で動作： + +| プロバイダー | モデル | Base URL | 次元数 | +| --- | --- | --- | --- | +| **Jina**（推奨） | `jina-embeddings-v5-text-small` | `https://api.jina.ai/v1` | 1024 | +| **OpenAI** | `text-embedding-3-small` | `https://api.openai.com/v1` | 1536 | +| **Voyage** | `voyage-4-lite` / `voyage-4` | `https://api.voyageai.com/v1` | 1024 / 1024 | +| **Google Gemini** | `gemini-embedding-001` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 | +| **Ollama**（ローカル） | `nomic-embed-text` | `http://localhost:11434/v1` | プロバイダー依存 | + +
+
+
+リランクプロバイダー
+ +クロスエンコーダーリランキングは `rerankProvider` で複数のプロバイダーをサポート： + +| プロバイダー | `rerankProvider` | モデル例 | +| --- | --- | --- | +| **Jina**（デフォルト） | `jina` | `jina-reranker-v3` | +| **SiliconFlow**（無料枠あり） | `siliconflow` | `BAAI/bge-reranker-v2-m3` | +| **Voyage AI** | `voyage` | `rerank-2.5` | +| **Pinecone** | `pinecone` | `bge-reranker-v2-m3` | + +任意の Jina 互換リランクエンドポイントも使用可能——`rerankProvider: "jina"` を設定し、`rerankEndpoint` をあなたのサービスに向けてください（例：Hugging Face TEI、DashScope `qwen3-rerank`）。 + +
+
+
+スマート抽出（LLM）— v1.1.0
+ +`smartExtraction` が有効（デフォルト：`true`）の場合、プラグインは正規表現ベースのトリガーの代わりに LLM を使用してインテリジェントにメモリを抽出・分類します。 + +| フィールド | 型 | デフォルト | 説明 | +|-------|------|---------|-------------| +| `smartExtraction` | boolean | `true` | LLM 駆動の6カテゴリ抽出の有効化/無効化 | +| `llm.auth` | string | `api-key` | `api-key` は `llm.apiKey` / `embedding.apiKey` を使用；`oauth` はデフォルトでプラグインスコープの OAuth トークンファイルを使用 | +| `llm.apiKey` | string | *（`embedding.apiKey` にフォールバック）* | LLM プロバイダーの API キー | +| `llm.model` | string | `openai/gpt-oss-120b` | LLM モデル名 | +| `llm.baseURL` | string | *（`embedding.baseURL` にフォールバック）* | LLM API エンドポイント | +| `llm.oauthProvider` | string | `openai-codex` | `llm.auth` が `oauth` の場合に使用する OAuth プロバイダー ID | +| `llm.oauthPath` | string | `~/.openclaw/.memory-lancedb-pro/oauth.json` | `llm.auth` が `oauth` の場合に使用する OAuth トークンファイル | +| `llm.timeoutMs` | number | `30000` | LLM リクエストタイムアウト（ミリ秒） | +| `extractMinMessages` | number | `2` | 抽出がトリガーされる最小メッセージ数 | +| `extractMaxChars` | number | `8000` | LLM に送信される最大文字数 | + + +OAuth `llm` 設定（既存の Codex / ChatGPT ログインキャッシュを使用して LLM 呼び出しを行う）： +```json +{ + "llm": { + "auth": "oauth", + "oauthProvider": "openai-codex", + "model": "gpt-5.4", + "oauthPath": "${HOME}/.openclaw/.memory-lancedb-pro/oauth.json", + "timeoutMs": 30000 + } +} +``` + +`llm.auth: "oauth"` に関する注意点： + +- `llm.oauthProvider` は現在 `openai-codex` です。 +- OAuth トークンのデフォルト保存先は `~/.openclaw/.memory-lancedb-pro/oauth.json` です。 +- 別の場所に保存したい場合は `llm.oauthPath` を設定してください。 +- `auth login` は OAuth ファイルの隣に以前の api-key モードの `llm` 設定のスナップショットを保存し、`auth logout` は利用可能な場合にそのスナップショットを復元します。 +- `api-key` から `oauth` への切り替え時、`llm.baseURL` は自動的に引き継がれません。意図的にカスタム ChatGPT/Codex 互換バックエンドを使用する場合のみ、OAuth モードで手動設定してください。 + +
+
+
+ライフサイクル設定（減衰 + 階層）
+ +| フィールド | デフォルト | 説明 | +|-------|---------|-------------| +| `decay.recencyHalfLifeDays` | `30` | Weibull 鮮度減衰のベース半減期 | +| `decay.frequencyWeight` | `0.3` | 複合スコアにおけるアクセス頻度の重み | +| `decay.intrinsicWeight` | `0.3` | `重要度 × 信頼度` の重み | +| `decay.betaCore` | `0.8` | `コア` メモリの Weibull ベータ | +| `decay.betaWorking` | `1.0` | `ワーキング` メモリの Weibull ベータ | +| `decay.betaPeripheral` | `1.3` | `周辺` メモリの Weibull ベータ | +| `tier.coreAccessThreshold` | `10` | `コア` に昇格するために必要な最小想起回数 | +| `tier.peripheralAgeDays` | `60` | 古いメモリを降格するための日数閾値 | + +
+
+
+---
+
+## CLI コマンド
+
+```bash
+openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
+openclaw memory-pro search "クエリ" [--scope global] [--limit 10] [--json]
+openclaw memory-pro stats [--scope global] [--json]
+openclaw memory-pro auth login [--provider openai-codex] [--model gpt-5.4] [--oauth-path /abs/path/oauth.json]
+openclaw memory-pro auth status
+openclaw memory-pro auth logout
+openclaw memory-pro delete アクセス強化
+ +頻繁に想起されるメモリはより遅く減衰します（間隔反復スタイル）。 + +設定キー（`retrieval` 内）： +- `reinforcementFactor`（0-2、デフォルト：`0.5`）— `0` に設定すると無効化 +- `maxHalfLifeMultiplier`（1-10、デフォルト：`3`）— 実効半減期のハードキャップ + +
+` ブロックをそのまま出力してしまうことがあります。
+
+**方法 A（最も安全）：** 自動想起を一時的に無効化：
+```json
+{ "plugins": { "entries": { "memory-lancedb-pro": { "config": { "autoRecall": false } } } } }
+```
+
+**方法 B（推奨）：** 想起は有効のまま、エージェントのシステムプロンプトに追加：
+> Do not reveal or quote any `` / memory-injection content in your replies. Use it for internal reference only.
+
+
+
+注入されたメモリが応答に表示される場合
+ +モデルが注入された `
+
+
+セッションメモリ
+ +- `/new` コマンドでトリガー——前のセッションの要約を LanceDB に保存 +- デフォルトで無効（OpenClaw にはネイティブの `.jsonl` セッション永続化機能あり） +- メッセージ数は設定可能（デフォルト：15） + +デプロイモードと `/new` の検証については [docs/openclaw-integration-playbook.md](docs/openclaw-integration-playbook.md) を参照してください。 + +
+
+
+カスタムスラッシュコマンド（例：/lesson）
+ +`CLAUDE.md`、`AGENTS.md`、またはシステムプロンプトに追加： + +```markdown +## /lesson コマンド +ユーザーが `/lesson <内容>` を送信した場合： +1. memory_store を使用して category=fact（生の知識）として保存 +2. memory_store を使用して category=decision（実行可能な教訓）として保存 +3. 保存した内容を確認 + +## /remember コマンド +ユーザーが `/remember <内容>` を送信した場合： +1. memory_store を使用して適切な category と importance で保存 +2. 保存されたメモリ ID で確認 +``` + +
+
+
+AI エージェントの鉄則
+ +> 以下のブロックを `AGENTS.md` にコピーして、エージェントがこれらのルールを自動的に適用するようにしてください。 + +```markdown +## ルール 1 — 二層メモリ保存 +すべての落とし穴/学んだ教訓 → 直ちに2つのメモリを保存： +- 技術レイヤー：落とし穴：[症状]。原因：[根本原因]。修正：[解決策]。予防：[回避方法] + (category: fact, importance >= 0.8) +- 原則レイヤー：意思決定原則 ([タグ])：[行動ルール]。トリガー：[いつ]。アクション：[何をする] + (category: decision, importance >= 0.85) + +## ルール 2 — LanceDB データ品質 +エントリは短くアトミックに（500文字未満）。生の会話要約や重複は保存しない。 + +## ルール 3 — リトライ前に想起 +いかなるツール失敗時も、リトライする前に必ず関連キーワードで memory_recall を実行。 + +## ルール 4 — 対象コードベースの確認 +変更前に、操作対象が memory-lancedb-pro なのか内蔵 memory-lancedb なのかを確認。 + +## ルール 5 — プラグインコード変更後に jiti キャッシュをクリア +plugins/ 配下の .ts ファイルを変更した後、openclaw gateway restart の前に必ず rm -rf /tmp/jiti/ を実行。 +``` + +
+
+
+データベーススキーマ
+ +LanceDB テーブル `memories`： + +| フィールド | 型 | 説明 | +| --- | --- | --- | +| `id` | string (UUID) | 主キー | +| `text` | string | メモリテキスト（FTS インデックス付き） | +| `vector` | float[] | Embedding ベクトル | +| `category` | string | ストレージカテゴリ：`preference` / `fact` / `decision` / `entity` / `reflection` / `other` | +| `scope` | string | スコープ識別子（例：`global`、`agent:main`） | +| `importance` | float | 重要度スコア 0-1 | +| `timestamp` | int64 | 作成タイムスタンプ（ミリ秒） | +| `metadata` | string (JSON) | 拡張メタデータ | + +v1.1.0 の一般的な `metadata` キー：`l0_abstract`、`l1_overview`、`l2_content`、`memory_category`、`tier`、`access_count`、`confidence`、`last_accessed_at` + +> **カテゴリに関する注意：** トップレベルの `category` フィールドは6つのストレージカテゴリを使用します。スマート抽出の6カテゴリセマンティックラベル（`profile` / `preferences` / `entities` / `events` / `cases` / `patterns`）は `metadata.memory_category` に保存されます。 + +
+
+
+---
+
+## ドキュメント
+
+| ドキュメント | 説明 |
+| --- | --- |
+| [OpenClaw 統合プレイブック](docs/openclaw-integration-playbook.md) | デプロイモード、検証、リグレッションマトリックス |
+| [メモリアーキテクチャ分析](docs/memory_architecture_analysis.md) | 完全なアーキテクチャ詳細解説 |
+| [CHANGELOG v1.1.0](docs/CHANGELOG-v1.1.0.md) | v1.1.0 の動作変更とアップグレード根拠 |
+| [ロングコンテキストチャンキング](docs/long-context-chunking.md) | 長文ドキュメントのチャンキング戦略 |
+
+---
+
+## Beta：スマートメモリ v1.1.0
+
+> ステータス：Beta——`npm i memory-lancedb-pro@beta` でインストール可能。`latest` を使用している安定版ユーザーには影響しません。
+
+| 機能 | 説明 |
+|---------|-------------|
+| **スマート抽出** | LLM 駆動の6カテゴリ抽出、L0/L1/L2 メタデータ対応。無効時は正規表現にフォールバック。 |
+| **ライフサイクルスコアリング** | Weibull 減衰を検索に統合——高頻度・高重要度のメモリが上位にランク。 |
+| **階層管理** | 3段階システム（コア → ワーキング → 周辺）、自動昇格/降格。 |
+
+フィードバック：[GitHub Issues](https://github.com/CortexReach/memory-lancedb-pro/issues) · 元に戻す：`npm i memory-lancedb-pro@latest`
+
+---
+
+## 依存関係
+
+| パッケージ | 用途 |
+| --- | --- |
+| `@lancedb/lancedb` ≥0.26.2 | ベクトルデータベース（ANN + FTS） |
+| `openai` ≥6.21.0 | OpenAI 互換 Embedding API クライアント |
+| `@sinclair/typebox` 0.34.48 | JSON Schema 型定義 |
+
+---
+
+## コントリビューター
+
+トラブルシューティング
+ +### "Cannot mix BigInt and other types"（LanceDB / Apache Arrow） + +LanceDB 0.26+ では、一部の数値カラムが `BigInt` として返されることがあります。**memory-lancedb-pro >= 1.0.14** にアップグレードしてください——プラグインは算術演算の前に `Number(...)` で値を変換するようになっています。 + +
+
+
+# 🧠 memory-lancedb-pro · 🦞OpenClaw Plugin
+
+**[OpenClaw](https://github.com/openclaw/openclaw) 에이전트를 위한 AI 메모리 어시스턴트**
+
+*AI 에이전트에게 진짜 기억하는 두뇌를 선물하세요 — 세션을 넘어, 에이전트를 넘어, 시간을 넘어.*
+
+LanceDB 기반 OpenClaw 메모리 플러그인으로, 사용자 선호도·의사결정·프로젝트 맥락을 저장하고 이후 세션에서 자동으로 불러옵니다.
+
+[](https://github.com/openclaw/openclaw)
+[](https://www.npmjs.com/package/memory-lancedb-pro)
+[](https://lancedb.com)
+[](LICENSE)
+
+[English](README.md) | [简体中文](README_CN.md) | [繁體中文](README_TW.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | [Español](README_ES.md) | [Deutsch](README_DE.md) | [Italiano](README_IT.md) | [Русский](README_RU.md) | [Português (Brasil)](README_PT-BR.md)
+
+
+
+---
+
+## 왜 memory-lancedb-pro인가?
+
+대부분의 AI 에이전트는 건망증이 있습니다. 새 채팅을 시작하는 순간 모든 것을 잊어버립니다.
+
+**memory-lancedb-pro**는 OpenClaw를 위한 프로덕션 수준의 장기 기억 플러그인으로, 에이전트를 **AI 메모리 어시스턴트**로 바꿔줍니다 — 중요한 내용을 자동으로 캡처하고, 노이즈는 자연스럽게 희미해지게 하며, 적시에 적절한 기억을 검색합니다. 수동 태그 지정도, 복잡한 설정도 필요 없습니다.
+
+### AI 메모리 어시스턴트 실제 사용 모습
+
+**기억 없이 — 매 세션이 처음부터 시작:**
+
+> **사용자:** "들여쓰기에 탭을 사용하고, 항상 에러 처리를 추가해."
+> *(다음 세션)*
+> **사용자:** "이미 말했잖아 — 스페이스 말고 탭이라고!" 😤
+> *(다음 세션)*
+> **사용자:** "...진짜로, 탭이라고. 에러 처리도. 또."
+
+**memory-lancedb-pro와 함께 — 에이전트가 학습하고 기억합니다:**
+
+> **사용자:** "들여쓰기에 탭을 사용하고, 항상 에러 처리를 추가해."
+> *(다음 세션 — 에이전트가 사용자 선호도를 자동으로 불러옴)*
+> **에이전트:** *(자동으로 탭 + 에러 처리 적용)* ✅
+> **사용자:** "지난달에 왜 MongoDB 대신 PostgreSQL을 선택했지?"
+> **에이전트:** "2월 12일 논의 내용에 따르면, 주요 이유는..." ✅
+
+이것이 **AI 메모리 어시스턴트**가 만드는 차이입니다 — 사용자의 스타일을 학습하고, 과거 결정을 불러오며, 반복 없이 개인화된 응답을 제공합니다.
+
+### 그 외 무엇을 할 수 있나요?
+
+| | 제공 기능 |
+|---|---|
+| **Auto-Capture** | 에이전트가 모든 대화에서 학습 — 수동 `memory_store` 불필요 |
+| **Smart Extraction** | LLM 기반 6개 카테고리 분류: profile, preferences, entities, events, cases, patterns |
+| **Intelligent Forgetting** | Weibull 감쇠 모델 — 중요한 기억은 유지, 노이즈는 자연스럽게 사라짐 |
+| **Hybrid Retrieval** | 벡터 + BM25 전문 검색, Cross-Encoder 리랭킹으로 융합 |
+| **Context Injection** | 관련 기억이 매 응답 전에 자동으로 불러와짐 |
+| **Multi-Scope Isolation** | 에이전트별, 사용자별, 프로젝트별 메모리 경계 |
+| **Any Provider** | OpenAI, Jina, Gemini, Ollama 또는 OpenAI 호환 API 모두 지원 |
+| **Full Toolkit** | CLI, 백업, 마이그레이션, 업그레이드, 내보내기/가져오기 — 프로덕션 환경에 적합 |
+
+---
+
+## 빠른 시작
+
+### 옵션 A: 원클릭 설치 스크립트 (권장)
+
+커뮤니티에서 관리하는 **[설치 스크립트](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)**가 설치, 업그레이드, 복구를 하나의 명령어로 처리합니다:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
+bash setup-memory.sh
+```
+
+> 스크립트가 다루는 전체 시나리오와 기타 커뮤니티 도구 목록은 아래 [에코시스템](#에코시스템)을 참조하세요.
+
+### 옵션 B: 수동 설치
+
+**OpenClaw CLI를 통한 설치 (권장):**
+```bash
+openclaw plugins install memory-lancedb-pro@beta
+```
+
+**또는 npm을 통한 설치:**
+```bash
+npm i memory-lancedb-pro@beta
+```
+> npm을 사용하는 경우, `openclaw.json`의 `plugins.load.paths`에 플러그인 설치 디렉터리의 **절대** 경로를 추가해야 합니다. 이것이 가장 흔한 설정 문제입니다.
+
+`openclaw.json`에 다음을 추가하세요:
+
+```json
+{
+ "plugins": {
+ "slots": { "memory": "memory-lancedb-pro" },
+ "entries": {
+ "memory-lancedb-pro": {
+ "enabled": true,
+ "config": {
+ "embedding": {
+ "provider": "openai-compatible",
+ "apiKey": "${OPENAI_API_KEY}",
+ "model": "text-embedding-3-small"
+ },
+ "autoCapture": true,
+ "autoRecall": true,
+ "smartExtraction": true,
+ "extractMinMessages": 2,
+ "extractMaxChars": 8000,
+ "sessionMemory": { "enabled": false }
+ }
+ }
+ }
+ }
+}
+```
+
+**왜 이러한 기본값인가?**
+- `autoCapture` + `smartExtraction` → 에이전트가 모든 대화에서 자동으로 학습
+- `autoRecall` → 매 응답 전에 관련 기억이 주입됨
+- `extractMinMessages: 2` → 일반적인 두 턴 대화에서 추출이 시작됨
+- `sessionMemory.enabled: false` → 초기에 세션 요약으로 검색이 오염되는 것을 방지
+
+검증 및 재시작:
+
+```bash
+openclaw config validate
+openclaw gateway restart
+openclaw logs --follow --plain | grep "memory-lancedb-pro"
+```
+
+다음이 표시되어야 합니다:
+- `memory-lancedb-pro: smart extraction enabled`
+- `memory-lancedb-pro@...: plugin registered`
+
+완료! 이제 에이전트가 장기 기억을 갖게 됩니다.
+
+
+
+
+추가 설치 경로 (기존 사용자, 업그레이드)
+ +**이미 OpenClaw를 사용 중인 경우:** + +1. **절대** 경로의 `plugins.load.paths` 항목으로 플러그인 추가 +2. 메모리 슬롯 바인딩: `plugins.slots.memory = "memory-lancedb-pro"` +3. 확인: `openclaw plugins info memory-lancedb-pro && openclaw memory-pro stats` + +**v1.1.0 이전 버전에서 업그레이드하는 경우:** + +```bash +# 1) 백업 +openclaw memory-pro export --scope global --output memories-backup.json +# 2) 시뮬레이션 실행 +openclaw memory-pro upgrade --dry-run +# 3) 업그레이드 실행 +openclaw memory-pro upgrade +# 4) 확인 +openclaw memory-pro stats +``` + +동작 변경사항과 업그레이드 근거는 `CHANGELOG-v1.1.0.md`를 참조하세요. + +
+
+
+---
+
+## 에코시스템
+
+memory-lancedb-pro는 핵심 플러그인입니다. 커뮤니티에서 설정과 일상적인 사용을 더욱 원활하게 만드는 도구들을 구축했습니다:
+
+### 설치 스크립트 — 원클릭 설치, 업그레이드 및 복구
+
+> **[CortexReach/toolbox/memory-lancedb-pro-setup](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)**
+
+단순한 인스톨러가 아닙니다 — 스크립트가 다양한 실제 시나리오를 지능적으로 처리합니다:
+
+| 상황 | 스크립트의 동작 |
+|---|---|
+| 설치한 적 없음 | 새로 다운로드 → 의존성 설치 → 설정 선택 → openclaw.json에 기록 → 재시작 |
+| `git clone`으로 설치, 이전 커밋에서 멈춤 | 자동 `git fetch` + `checkout`으로 최신 버전 이동 → 의존성 재설치 → 확인 |
+| 설정에 유효하지 않은 필드 존재 | 스키마 필터를 통한 자동 감지, 지원되지 않는 필드 제거 |
+| `npm`으로 설치 | git 업데이트 건너뜀, `npm update` 직접 실행 알림 |
+| 유효하지 않은 설정으로 `openclaw` CLI 동작 불가 | 대체 방법: `openclaw.json` 파일에서 직접 워크스페이스 경로 읽기 |
+| `plugins/` 대신 `extensions/` 사용 | 설정 또는 파일시스템에서 플러그인 위치 자동 감지 |
+| 이미 최신 상태 | 상태 확인만 실행, 변경 없음 |
+
+```bash
+bash setup-memory.sh # 설치 또는 업그레이드
+bash setup-memory.sh --dry-run # 미리보기만
+bash setup-memory.sh --beta # 사전 릴리스 버전 포함
+bash setup-memory.sh --uninstall # 설정 복원 및 플러그인 제거
+```
+
+내장 프로바이더 프리셋: **Jina / DashScope / SiliconFlow / OpenAI / Ollama**, 또는 자체 OpenAI 호환 API를 사용할 수 있습니다. `--ref`, `--selfcheck-only` 등 전체 사용법은 [설치 스크립트 README](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)를 참조하세요.
+
+### Claude Code / OpenClaw Skill — AI 가이드 설정
+
+> **[CortexReach/memory-lancedb-pro-skill](https://github.com/CortexReach/memory-lancedb-pro-skill)**
+
+이 Skill을 설치하면 AI 에이전트(Claude Code 또는 OpenClaw)가 memory-lancedb-pro의 모든 기능에 대한 깊은 지식을 갖게 됩니다. **"최적의 설정을 도와줘"**라고 말하면 다음을 제공합니다:
+
+- **가이드 7단계 설정 워크플로우**와 4가지 배포 계획:
+ - Full Power (Jina + OpenAI) / Budget (무료 SiliconFlow 리랭커) / Simple (OpenAI만) / Fully Local (Ollama, API 비용 제로)
+- **모든 9개 MCP 도구**의 올바른 사용법: `memory_recall`, `memory_store`, `memory_forget`, `memory_update`, `memory_stats`, `memory_list`, `self_improvement_log`, `self_improvement_extract_skill`, `self_improvement_review` *(전체 도구 세트를 사용하려면 `enableManagementTools: true`가 필요합니다 — 기본 빠른 시작 설정은 4개 핵심 도구만 노출합니다)*
+- **일반적인 함정 방지**: 워크스페이스 플러그인 활성화, `autoRecall` 기본값 false, jiti 캐시, 환경 변수, 스코프 격리 등
+
+**Claude Code용 설치:**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro
+```
+
+**OpenClaw용 설치:**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill
+```
+
+---
+
+## 비디오 튜토리얼
+
+> 전체 안내: 설치, 설정, 하이브리드 검색 내부 구조.
+
+[](https://youtu.be/MtukF1C8epQ)
+**https://youtu.be/MtukF1C8epQ**
+
+[](https://www.bilibili.com/video/BV1zUf2BGEgn/)
+**https://www.bilibili.com/video/BV1zUf2BGEgn/**
+
+---
+
+## 아키텍처
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ index.ts (진입점) │
+│ 플러그인 등록 · 설정 파싱 · 라이프사이클 훅 │
+└────────┬──────────┬──────────┬──────────┬───────────────┘
+ │ │ │ │
+ ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
+ │ store │ │embedder│ │retriever│ │ scopes │
+ │ .ts │ │ .ts │ │ .ts │ │ .ts │
+ └────────┘ └────────┘ └────────┘ └─────────────┘
+ │ │
+ ┌────▼───┐ ┌─────▼──────────┐
+ │migrate │ │noise-filter.ts │
+ │ .ts │ │adaptive- │
+ └────────┘ │retrieval.ts │
+ └────────────────┘
+ ┌─────────────┐ ┌──────────┐
+ │ tools.ts │ │ cli.ts │
+ │ (에이전트API)│ │ (CLI) │
+ └─────────────┘ └──────────┘
+```
+
+> 전체 아키텍처에 대한 심층 분석은 [docs/memory_architecture_analysis.md](docs/memory_architecture_analysis.md)를 참조하세요.
+
+Telegram 봇 빠른 가져오기 (클릭하여 펼치기)
+ +OpenClaw의 Telegram 연동을 사용하는 경우, 수동으로 설정을 편집하는 대신 메인 봇에 가져오기 명령어를 직접 보내는 것이 가장 쉬운 방법입니다. + +다음 메시지를 전송하세요 (봇에 그대로 복사하여 붙여넣기하는 영문 프롬프트입니다): + +```text +Help me connect this memory plugin with the most user-friendly configuration: https://github.com/CortexReach/memory-lancedb-pro + +Requirements: +1. Set it as the only active memory plugin +2. Use Jina for embedding +3. Use Jina for reranker +4. Use gpt-4o-mini for the smart-extraction LLM +5. Enable autoCapture, autoRecall, smartExtraction +6. extractMinMessages=2 +7. sessionMemory.enabled=false +8. captureAssistant=false +9. retrieval mode=hybrid, vectorWeight=0.7, bm25Weight=0.3 +10. rerank=cross-encoder, candidatePoolSize=12, minScore=0.6, hardMinScore=0.62 +11. Generate the final openclaw.json config directly, not just an explanation +``` + +
+
+
+---
+
+## 핵심 기능
+
+### 하이브리드 검색
+
+```
+Query → embedQuery() ─┐
+ ├─→ Hybrid Fusion → Rerank → Lifecycle Decay Boost → Length Norm → Filter
+Query → BM25 FTS ─────┘
+```
+
+- **벡터 검색** — LanceDB ANN을 통한 의미적 유사도 (코사인 거리)
+- **BM25 전문 검색** — LanceDB FTS 인덱스를 통한 정확한 키워드 매칭
+- **하이브리드 퓨전** — 벡터 스코어를 기본으로, BM25 히트에 가중 부스트 적용 (표준 RRF가 아님 — 실제 검색 품질에 맞게 튜닝됨)
+- **가중치 설정 가능** — `vectorWeight`, `bm25Weight`, `minScore`
+
+### Cross-Encoder 리랭킹
+
+- **Jina**, **SiliconFlow**, **Voyage AI**, **Pinecone** 내장 어댑터
+- Jina 호환 엔드포인트와 호환 (예: Hugging Face TEI, DashScope)
+- 하이브리드 스코어링: Cross-Encoder 60% + 원래 퓨전 스코어 40%
+- 그레이스풀 디그레이데이션: API 실패 시 코사인 유사도로 폴백
+
+### 다단계 스코어링 파이프라인
+
+| 단계 | 효과 |
+| --- | --- |
+| **하이브리드 퓨전** | 의미적 검색과 정확한 매칭 결합 |
+| **Cross-Encoder 리랭크** | 의미적으로 정확한 결과 승격 |
+| **라이프사이클 감쇠 부스트** | Weibull 최신성 + 접근 빈도 + 중요도 × 신뢰도 |
+| **길이 정규화** | 긴 항목이 결과를 지배하는 것을 방지 (앵커: 500자) |
+| **최소 점수 하한** | 관련 없는 결과 제거 (기본값: 0.35) |
+| **MMR 다양성** | 코사인 유사도 > 0.85 → 강등 |
+
+### Smart Memory Extraction (v1.1.0)
+
+- **LLM 기반 6개 카테고리 추출**: profile, preferences, entities, events, cases, patterns
+- **L0/L1/L2 계층 저장**: L0 (한 줄 인덱스) → L1 (구조화된 요약) → L2 (전체 내러티브)
+- **2단계 중복 제거**: 벡터 유사도 사전 필터 (≥0.7) → LLM 의미 판단 (CREATE/MERGE/SKIP)
+- **카테고리 인식 병합**: `profile`은 항상 병합, `events`/`cases`는 추가 전용
+
+### 메모리 라이프사이클 관리 (v1.1.0)
+
+- **Weibull 감쇠 엔진**: 복합 점수 = 최신성 + 빈도 + 내재적 가치
+- **3단계 승격**: `Peripheral ↔ Working ↔ Core`, 설정 가능한 임계값
+- **접근 강화**: 자주 불러오는 기억은 더 느리게 감쇠 (간격 반복 학습 방식)
+- **중요도 조절 반감기**: 중요한 기억은 더 느리게 감쇠
+
+### Multi-Scope 격리
+
+- 내장 스코프: `global`, `agent:파일 레퍼런스 (클릭하여 펼치기)
+ +| 파일 | 용도 | +| --- | --- | +| `index.ts` | 플러그인 진입점. OpenClaw Plugin API에 등록, 설정 파싱, 라이프사이클 훅 마운트 | +| `openclaw.plugin.json` | 플러그인 메타데이터 + 전체 JSON Schema 설정 선언 | +| `cli.ts` | CLI 명령어: `memory-pro list/search/stats/delete/delete-bulk/export/import/reembed/upgrade/migrate` | +| `src/store.ts` | LanceDB 스토리지 레이어. 테이블 생성 / FTS 인덱싱 / 벡터 검색 / BM25 검색 / CRUD | +| `src/embedder.ts` | 임베딩 추상화. OpenAI 호환 API 프로바이더 모두 지원 | +| `src/retriever.ts` | 하이브리드 검색 엔진. 벡터 + BM25 → 하이브리드 퓨전 → 리랭크 → 라이프사이클 감쇠 → 필터 | +| `src/scopes.ts` | 멀티 스코프 접근 제어 | +| `src/tools.ts` | 에이전트 도구 정의: `memory_recall`, `memory_store`, `memory_forget`, `memory_update` + 관리 도구 | +| `src/noise-filter.ts` | 에이전트 거절, 메타 질문, 인사, 저품질 콘텐츠 필터링 | +| `src/adaptive-retrieval.ts` | 쿼리에 메모리 검색이 필요한지 판단 | +| `src/migrate.ts` | 내장 `memory-lancedb`에서 Pro로의 마이그레이션 | +| `src/smart-extractor.ts` | LLM 기반 6개 카테고리 추출 + L0/L1/L2 계층 저장 + 2단계 중복 제거 | +| `src/decay-engine.ts` | Weibull 확장 지수 감쇠 모델 | +| `src/tier-manager.ts` | 3단계 승격/강등: Peripheral ↔ Working ↔ Core | + +
+내장
+
+| 기능 | 내장 `memory-lancedb` | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| 벡터 검색 | 예 | 예 |
+| BM25 전문 검색 | - | 예 |
+| 하이브리드 퓨전 (벡터 + BM25) | - | 예 |
+| Cross-Encoder 리랭크 (멀티 프로바이더) | - | 예 |
+| 최신성 부스트 및 시간 감쇠 | - | 예 |
+| 길이 정규화 | - | 예 |
+| MMR 다양성 | - | 예 |
+| 멀티 스코프 격리 | - | 예 |
+| 노이즈 필터링 | - | 예 |
+| 적응형 검색 | - | 예 |
+| 관리 CLI | - | 예 |
+| 세션 메모리 | - | 예 |
+| 태스크 인식 임베딩 | - | 예 |
+| **LLM Smart Extraction (6개 카테고리)** | - | 예 (v1.1.0) |
+| **Weibull 감쇠 + 단계 승격** | - | 예 (v1.1.0) |
+| OpenAI 호환 임베딩 | 제한적 | 예 |
+
+
+
+---
+
+## 설정
+
+내장 memory-lancedb와의 비교 (클릭하여 펼치기)
+
+| 기능 | 내장 `memory-lancedb` | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| 벡터 검색 | 예 | 예 |
+| BM25 전문 검색 | - | 예 |
+| 하이브리드 퓨전 (벡터 + BM25) | - | 예 |
+| Cross-Encoder 리랭크 (멀티 프로바이더) | - | 예 |
+| 최신성 부스트 및 시간 감쇠 | - | 예 |
+| 길이 정규화 | - | 예 |
+| MMR 다양성 | - | 예 |
+| 멀티 스코프 격리 | - | 예 |
+| 노이즈 필터링 | - | 예 |
+| 적응형 검색 | - | 예 |
+| 관리 CLI | - | 예 |
+| 세션 메모리 | - | 예 |
+| 태스크 인식 임베딩 | - | 예 |
+| **LLM Smart Extraction (6개 카테고리)** | - | 예 (v1.1.0) |
+| **Weibull 감쇠 + 단계 승격** | - | 예 (v1.1.0) |
+| OpenAI 호환 임베딩 | 제한적 | 예 |
+
+
+
+
+전체 설정 예시
+ +```json +{ + "embedding": { + "apiKey": "${JINA_API_KEY}", + "model": "jina-embeddings-v5-text-small", + "baseURL": "https://api.jina.ai/v1", + "dimensions": 1024, + "taskQuery": "retrieval.query", + "taskPassage": "retrieval.passage", + "normalized": true + }, + "dbPath": "~/.openclaw/memory/lancedb-pro", + "autoCapture": true, + "autoRecall": true, + "retrieval": { + "mode": "hybrid", + "vectorWeight": 0.7, + "bm25Weight": 0.3, + "minScore": 0.3, + "rerank": "cross-encoder", + "rerankApiKey": "${JINA_API_KEY}", + "rerankModel": "jina-reranker-v3", + "rerankEndpoint": "https://api.jina.ai/v1/rerank", + "rerankProvider": "jina", + "candidatePoolSize": 20, + "recencyHalfLifeDays": 14, + "recencyWeight": 0.1, + "filterNoise": true, + "lengthNormAnchor": 500, + "hardMinScore": 0.35, + "timeDecayHalfLifeDays": 60, + "reinforcementFactor": 0.5, + "maxHalfLifeMultiplier": 3 + }, + "enableManagementTools": false, + "scopes": { + "default": "global", + "definitions": { + "global": { "description": "Shared knowledge" }, + "agent:discord-bot": { "description": "Discord bot private" } + }, + "agentAccess": { + "discord-bot": ["global", "agent:discord-bot"] + } + }, + "sessionMemory": { + "enabled": false, + "messageCount": 15 + }, + "smartExtraction": true, + "llm": { + "apiKey": "${OPENAI_API_KEY}", + "model": "gpt-4o-mini", + "baseURL": "https://api.openai.com/v1" + }, + "extractMinMessages": 2, + "extractMaxChars": 8000 +} +``` + +
+
+
+임베딩 프로바이더
+ +**OpenAI 호환 임베딩 API**와 모두 동작합니다: + +| 프로바이더 | 모델 | Base URL | 차원 | +| --- | --- | --- | --- | +| **Jina** (권장) | `jina-embeddings-v5-text-small` | `https://api.jina.ai/v1` | 1024 | +| **OpenAI** | `text-embedding-3-small` | `https://api.openai.com/v1` | 1536 | +| **Voyage** | `voyage-4-lite` / `voyage-4` | `https://api.voyageai.com/v1` | 1024 / 1024 | +| **Google Gemini** | `gemini-embedding-001` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 | +| **Ollama** (로컬) | `nomic-embed-text` | `http://localhost:11434/v1` | 프로바이더별 상이 | + +
+
+
+리랭크 프로바이더
+ +Cross-Encoder 리랭킹은 `rerankProvider`를 통해 여러 프로바이더를 지원합니다: + +| 프로바이더 | `rerankProvider` | 예시 모델 | +| --- | --- | --- | +| **Jina** (기본값) | `jina` | `jina-reranker-v3` | +| **SiliconFlow** (무료 티어 제공) | `siliconflow` | `BAAI/bge-reranker-v2-m3` | +| **Voyage AI** | `voyage` | `rerank-2.5` | +| **Pinecone** | `pinecone` | `bge-reranker-v2-m3` | + +Jina 호환 리랭크 엔드포인트도 사용 가능합니다 — `rerankProvider: "jina"`로 설정하고 `rerankEndpoint`를 해당 서비스로 지정하세요 (예: Hugging Face TEI, DashScope `qwen3-rerank`). + +
+
+
+Smart Extraction (LLM) — v1.1.0
+ +`smartExtraction`이 활성화되면 (기본값: `true`), 플러그인이 정규식 기반 트리거 대신 LLM을 사용하여 기억을 지능적으로 추출하고 분류합니다. + +| 필드 | 타입 | 기본값 | 설명 | +|-------|------|---------|-------------| +| `smartExtraction` | boolean | `true` | LLM 기반 6개 카테고리 추출 활성화/비활성화 | +| `llm.auth` | string | `api-key` | `api-key`는 `llm.apiKey` / `embedding.apiKey`를 사용; `oauth`는 기본적으로 플러그인 범위의 OAuth 토큰 파일을 사용 | +| `llm.apiKey` | string | *(`embedding.apiKey`로 폴백)* | LLM 프로바이더용 API 키 | +| `llm.model` | string | `openai/gpt-oss-120b` | LLM 모델명 | +| `llm.baseURL` | string | *(`embedding.baseURL`로 폴백)* | LLM API 엔드포인트 | +| `llm.oauthProvider` | string | `openai-codex` | `llm.auth`가 `oauth`일 때 사용되는 OAuth 프로바이더 ID | +| `llm.oauthPath` | string | `~/.openclaw/.memory-lancedb-pro/oauth.json` | `llm.auth`가 `oauth`일 때 사용되는 OAuth 토큰 파일 | +| `llm.timeoutMs` | number | `30000` | LLM 요청 타임아웃 (밀리초) | +| `extractMinMessages` | number | `2` | 추출이 시작되는 최소 메시지 수 | +| `extractMaxChars` | number | `8000` | LLM에 전송되는 최대 문자 수 | + + +OAuth `llm` 설정 (기존 Codex / ChatGPT 로그인 캐시를 LLM 호출에 사용): +```json +{ + "llm": { + "auth": "oauth", + "oauthProvider": "openai-codex", + "model": "gpt-5.4", + "oauthPath": "${HOME}/.openclaw/.memory-lancedb-pro/oauth.json", + "timeoutMs": 30000 + } +} +``` + +`llm.auth: "oauth"` 참고사항: + +- `llm.oauthProvider`는 현재 `openai-codex`입니다. +- OAuth 토큰은 기본적으로 `~/.openclaw/.memory-lancedb-pro/oauth.json`에 저장됩니다. +- 파일을 다른 곳에 저장하려면 `llm.oauthPath`를 설정하세요. +- `auth login`은 OAuth 파일 옆에 이전 api-key `llm` 설정의 스냅샷을 저장하며, `auth logout`은 해당 스냅샷이 있을 때 복원합니다. +- `api-key`에서 `oauth`로 전환할 때 `llm.baseURL`이 자동으로 이전되지 않습니다. OAuth 모드에서 의도적으로 사용자 정의 ChatGPT/Codex 호환 백엔드를 원하는 경우에만 수동으로 설정하세요. + +
+
+
+라이프사이클 설정 (감쇠 + 단계)
+ +| 필드 | 기본값 | 설명 | +|-------|---------|-------------| +| `decay.recencyHalfLifeDays` | `30` | Weibull 최신성 감쇠의 기본 반감기 | +| `decay.frequencyWeight` | `0.3` | 복합 점수에서 접근 빈도의 가중치 | +| `decay.intrinsicWeight` | `0.3` | `importance × confidence`의 가중치 | +| `decay.betaCore` | `0.8` | `core` 기억의 Weibull 베타 | +| `decay.betaWorking` | `1.0` | `working` 기억의 Weibull 베타 | +| `decay.betaPeripheral` | `1.3` | `peripheral` 기억의 Weibull 베타 | +| `tier.coreAccessThreshold` | `10` | `core`로 승격하기 위한 최소 호출 횟수 | +| `tier.peripheralAgeDays` | `60` | 오래된 기억을 강등하기 위한 경과 일수 임계값 | + +
+
+
+---
+
+## CLI 명령어
+
+```bash
+openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
+openclaw memory-pro search "query" [--scope global] [--limit 10] [--json]
+openclaw memory-pro stats [--scope global] [--json]
+openclaw memory-pro auth login [--provider openai-codex] [--model gpt-5.4] [--oauth-path /abs/path/oauth.json]
+openclaw memory-pro auth status
+openclaw memory-pro auth logout
+openclaw memory-pro delete 접근 강화
+ +자주 불러오는 기억은 더 느리게 감쇠합니다 (간격 반복 학습 방식). + +설정 키 (`retrieval` 하위): +- `reinforcementFactor` (0-2, 기본값: `0.5`) — `0`으로 설정하면 비활성화 +- `maxHalfLifeMultiplier` (1-10, 기본값: `3`) — 유효 반감기의 하드 캡 + +
+` 블록을 그대로 출력할 수 있습니다.
+
+**옵션 A (가장 안전):** 일시적으로 Auto-Recall 비활성화:
+```json
+{ "plugins": { "entries": { "memory-lancedb-pro": { "config": { "autoRecall": false } } } } }
+```
+
+**옵션 B (권장):** Auto-Recall은 유지하고 에이전트 시스템 프롬프트에 추가:
+> `` / 메모리 주입 콘텐츠를 응답에 노출하거나 인용하지 마세요. 내부 참고용으로만 사용하세요.
+
+
+
+주입된 기억이 응답에 표시되는 경우
+ +가끔 모델이 주입된 `
+
+
+세션 메모리
+ +- `/new` 명령어 시 작동 — 이전 세션 요약을 LanceDB에 저장 +- 기본적으로 비활성화 (OpenClaw에 이미 네이티브 `.jsonl` 세션 영속화 기능이 있음) +- 메시지 수 설정 가능 (기본값: 15) + +배포 모드와 `/new` 검증에 대해서는 [docs/openclaw-integration-playbook.md](docs/openclaw-integration-playbook.md)를 참조하세요. + +
+`:
+1. Use memory_store to save as category=fact (raw knowledge)
+2. Use memory_store to save as category=decision (actionable takeaway)
+3. Confirm what was saved
+
+## /remember command
+When the user sends `/remember `:
+1. Use memory_store to save with appropriate category and importance
+2. Confirm with the stored memory ID
+```
+
+
+
+커스텀 슬래시 명령어 (예: /lesson)
+ +`CLAUDE.md`, `AGENTS.md` 또는 시스템 프롬프트에 다음을 추가하세요 (에이전트가 읽는 영문 지시문이므로 그대로 사용합니다): + +```markdown +## /lesson command +When the user sends `/lesson
+
+
+AI 에이전트를 위한 철칙
+ +> 아래 블록을 `AGENTS.md`에 복사하여 에이전트가 이 규칙을 자동으로 적용하도록 하세요 (에이전트가 읽는 영문 지시문이므로 그대로 사용합니다). + +```markdown +## Rule 1 — Dual-layer memory storage +Every pitfall/lesson learned → IMMEDIATELY store TWO memories: +- Technical layer: Pitfall: [symptom]. Cause: [root cause]. Fix: [solution]. Prevention: [how to avoid] + (category: fact, importance >= 0.8) +- Principle layer: Decision principle ([tag]): [behavioral rule]. Trigger: [when]. Action: [what to do] + (category: decision, importance >= 0.85) + +## Rule 2 — LanceDB hygiene +Entries must be short and atomic (< 500 chars). No raw conversation summaries or duplicates. + +## Rule 3 — Recall before retry +On ANY tool failure, ALWAYS memory_recall with relevant keywords BEFORE retrying. + +## Rule 4 — Confirm target codebase +Confirm you are editing memory-lancedb-pro vs built-in memory-lancedb before changes. + +## Rule 5 — Clear jiti cache after plugin code changes +After modifying .ts files under plugins/, MUST run rm -rf /tmp/jiti/ BEFORE openclaw gateway restart. +``` + +
+
+
+데이터베이스 스키마
+ +LanceDB 테이블 `memories`: + +| 필드 | 타입 | 설명 | +| --- | --- | --- | +| `id` | string (UUID) | 기본 키 | +| `text` | string | 기억 텍스트 (FTS 인덱싱됨) | +| `vector` | float[] | 임베딩 벡터 | +| `category` | string | 저장 카테고리: `preference` / `fact` / `decision` / `entity` / `reflection` / `other` | +| `scope` | string | 스코프 식별자 (예: `global`, `agent:main`) | +| `importance` | float | 중요도 점수 0-1 | +| `timestamp` | int64 | 생성 타임스탬프 (ms) | +| `metadata` | string (JSON) | 확장 메타데이터 | + +v1.1.0의 주요 `metadata` 키: `l0_abstract`, `l1_overview`, `l2_content`, `memory_category`, `tier`, `access_count`, `confidence`, `last_accessed_at` + +> **카테고리 참고:** 최상위 `category` 필드는 6개 저장 카테고리를 사용합니다. Smart Extraction의 6개 카테고리 의미 라벨 (`profile` / `preferences` / `entities` / `events` / `cases` / `patterns`)은 `metadata.memory_category`에 저장됩니다. + +
+
+
+---
+
+## 문서
+
+| 문서 | 설명 |
+| --- | --- |
+| [OpenClaw 통합 플레이북](docs/openclaw-integration-playbook.md) | 배포 모드, 검증, 회귀 매트릭스 |
+| [메모리 아키텍처 분석](docs/memory_architecture_analysis.md) | 전체 아키텍처 심층 분석 |
+| [CHANGELOG v1.1.0](docs/CHANGELOG-v1.1.0.md) | v1.1.0 동작 변경사항 및 업그레이드 근거 |
+| [장문 컨텍스트 청킹](docs/long-context-chunking.md) | 긴 문서를 위한 청킹 전략 |
+
+---
+
+## 베타: Smart Memory v1.1.0
+
+> 상태: 베타 — `npm i memory-lancedb-pro@beta`로 사용 가능. `latest`를 사용하는 안정 버전 사용자는 영향 없음.
+
+| 기능 | 설명 |
+|---------|-------------|
+| **Smart Extraction** | LLM 기반 6개 카테고리 추출 + L0/L1/L2 메타데이터. 비활성화 시 정규식으로 폴백. |
+| **라이프사이클 스코어링** | 검색에 Weibull 감쇠 통합 — 높은 빈도와 높은 중요도의 기억이 상위에 랭크. |
+| **단계 관리** | 3단계 시스템 (Core → Working → Peripheral), 자동 승격/강등. |
+
+피드백: [GitHub Issues](https://github.com/CortexReach/memory-lancedb-pro/issues) · 되돌리기: `npm i memory-lancedb-pro@latest`
+
+---
+
+## 의존성
+
+| 패키지 | 용도 |
+| --- | --- |
+| `@lancedb/lancedb` ≥0.26.2 | 벡터 데이터베이스 (ANN + FTS) |
+| `openai` ≥6.21.0 | OpenAI 호환 Embedding API 클라이언트 |
+| `@sinclair/typebox` 0.34.48 | JSON Schema 타입 정의 |
+
+---
+
+## Contributors
+
+문제 해결
+ +### "Cannot mix BigInt and other types" (LanceDB / Apache Arrow) + +LanceDB 0.26 이상에서 일부 숫자 열이 `BigInt`로 반환될 수 있습니다. **memory-lancedb-pro >= 1.0.14**로 업그레이드하세요 — 이 플러그인은 이제 산술 연산 전에 `Number(...)`를 사용하여 값을 변환합니다. + +
+
+
+# 🧠 memory-lancedb-pro · 🦞OpenClaw Plugin
+
+**Assistente de Memória IA para Agentes [OpenClaw](https://github.com/openclaw/openclaw)**
+
+*Dê ao seu agente de IA um cérebro que realmente lembra — entre sessões, entre agentes, ao longo do tempo.*
+
+Um plugin de memória de longo prazo para OpenClaw baseado em LanceDB que armazena preferências, decisões e contexto de projetos, e os recupera automaticamente em sessões futuras.
+
+[](https://github.com/openclaw/openclaw)
+[](https://www.npmjs.com/package/memory-lancedb-pro)
+[](https://lancedb.com)
+[](LICENSE)
+
+[English](README.md) | [简体中文](README_CN.md) | [繁體中文](README_TW.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | [Español](README_ES.md) | [Deutsch](README_DE.md) | [Italiano](README_IT.md) | [Русский](README_RU.md) | [Português (Brasil)](README_PT-BR.md)
+
+
+
+---
+
+## Por que memory-lancedb-pro?
+
+A maioria dos agentes de IA sofre de amnésia. Eles esquecem tudo no momento em que você inicia um novo chat.
+
+**memory-lancedb-pro** é um plugin de memória de longo prazo de nível de produção para OpenClaw que transforma seu agente em um verdadeiro **Assistente de Memória IA** — captura automaticamente o que importa, deixa o ruído desaparecer naturalmente e recupera a memória certa no momento certo. Sem tags manuais, sem dores de cabeça com configuração.
+
+### Seu Assistente de Memória IA em ação
+
+**Sem memória — cada sessão começa do zero:**
+
+> **Você:** "Use tabs para indentação, sempre adicione tratamento de erros."
+> *(próxima sessão)*
+> **Você:** "Eu já te disse — tabs, não espaços!" 😤
+> *(próxima sessão)*
+> **Você:** "…sério, tabs. E tratamento de erros. De novo."
+
+**Com memory-lancedb-pro — seu agente aprende e lembra:**
+
+> **Você:** "Use tabs para indentação, sempre adicione tratamento de erros."
+> *(próxima sessão — agente recupera automaticamente suas preferências)*
+> **Agente:** *(aplica silenciosamente tabs + tratamento de erros)* ✅
+> **Você:** "Por que escolhemos PostgreSQL em vez de MongoDB no mês passado?"
+> **Agente:** "Com base na nossa discussão de 12 de fevereiro, os principais motivos foram…" ✅
+
+Essa é a diferença que um **Assistente de Memória IA** faz — aprende seu estilo, lembra decisões passadas e entrega respostas personalizadas sem você precisar se repetir.
+
+### O que mais ele pode fazer?
+
+| | O que você obtém |
+|---|---|
+| **Auto-Capture** | Seu agente aprende de cada conversa — sem necessidade de `memory_store` manual |
+| **Extração inteligente** | Classificação LLM em 6 categorias: perfis, preferências, entidades, eventos, casos, padrões |
+| **Esquecimento inteligente** | Modelo de decaimento Weibull — memórias importantes permanecem, ruído desaparece |
+| **Busca híbrida** | Busca vetorial + BM25 full-text, fundida com reranking cross-encoder |
+| **Injeção de contexto** | Memórias relevantes aparecem automaticamente antes de cada resposta |
+| **Isolamento multi-scope** | Limites de memória por agente, por usuário, por projeto |
+| **Qualquer provedor** | OpenAI, Jina, Gemini, Ollama ou qualquer API compatível com OpenAI |
+| **Toolkit completo** | CLI, backup, migração, upgrade, exportação/importação — pronto para produção |
+
+---
+
+## Início rápido
+
+### Opção A: Script de instalação com um clique (recomendado)
+
+O **[script de instalação](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)** mantido pela comunidade gerencia instalação, atualização e reparo em um único comando:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
+bash setup-memory.sh
+```
+
+> Veja [Ecossistema](#ecossistema) abaixo para a lista completa de cenários cobertos e outras ferramentas da comunidade.
+
+### Opção B: Instalação manual
+
+**Via OpenClaw CLI (recomendado):**
+```bash
+openclaw plugins install memory-lancedb-pro@beta
+```
+
+**Ou via npm:**
+```bash
+npm i memory-lancedb-pro@beta
+```
+> Se usar npm, você também precisará adicionar o diretório de instalação do plugin como caminho **absoluto** em `plugins.load.paths` no seu `openclaw.json`. Este é o problema de configuração mais comum.
+
+Adicione ao seu `openclaw.json`:
+
+```json
+{
+ "plugins": {
+ "slots": { "memory": "memory-lancedb-pro" },
+ "entries": {
+ "memory-lancedb-pro": {
+ "enabled": true,
+ "config": {
+ "embedding": {
+ "provider": "openai-compatible",
+ "apiKey": "${OPENAI_API_KEY}",
+ "model": "text-embedding-3-small"
+ },
+ "autoCapture": true,
+ "autoRecall": true,
+ "smartExtraction": true,
+ "extractMinMessages": 2,
+ "extractMaxChars": 8000,
+ "sessionMemory": { "enabled": false }
+ }
+ }
+ }
+ }
+}
+```
+
+**Por que esses valores padrão?**
+- `autoCapture` + `smartExtraction` → seu agente aprende automaticamente de cada conversa
+- `autoRecall` → memórias relevantes são injetadas antes de cada resposta
+- `extractMinMessages: 2` → a extração é acionada em chats normais de dois turnos
+- `sessionMemory.enabled: false` → evita poluir a busca com resumos de sessão no início
+
+Valide e reinicie:
+
+```bash
+openclaw config validate
+openclaw gateway restart
+openclaw logs --follow --plain | grep "memory-lancedb-pro"
+```
+
+Você deve ver:
+- `memory-lancedb-pro: smart extraction enabled`
+- `memory-lancedb-pro@...: plugin registered`
+
+Pronto! Seu agente agora tem memória de longo prazo.
+
+
+
+
+Mais caminhos de instalação (usuários existentes, upgrades)
+ +**Já está usando OpenClaw?** + +1. Adicione o plugin com um caminho **absoluto** em `plugins.load.paths` +2. Vincule o slot de memória: `plugins.slots.memory = "memory-lancedb-pro"` +3. Verifique: `openclaw plugins info memory-lancedb-pro && openclaw memory-pro stats` + +**Atualizando de versões anteriores ao v1.1.0?** + +```bash +# 1) Backup +openclaw memory-pro export --scope global --output memories-backup.json +# 2) Dry run +openclaw memory-pro upgrade --dry-run +# 3) Run upgrade +openclaw memory-pro upgrade +# 4) Verify +openclaw memory-pro stats +``` + +Veja `CHANGELOG-v1.1.0.md` para mudanças de comportamento e justificativa de upgrade. + +
+
+
+---
+
+## Ecossistema
+
+memory-lancedb-pro é o plugin principal. A comunidade construiu ferramentas ao redor dele para tornar a configuração e o uso diário ainda mais suaves:
+
+### Script de instalação — Instalação, atualização e reparo com um clique
+
+> **[CortexReach/toolbox/memory-lancedb-pro-setup](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)**
+
+Não é apenas um instalador simples — o script lida inteligentemente com diversos cenários reais:
+
+| Sua situação | O que o script faz |
+|---|---|
+| Nunca instalou | Download → instalar dependências → escolher config → gravar em openclaw.json → reiniciar |
+| Instalado via `git clone`, preso em um commit antigo | `git fetch` + `checkout` automático para a versão mais recente → reinstalar dependências → verificar |
+| Config tem campos inválidos | Detecção automática via filtro de schema, remoção de campos não suportados |
+| Instalado via `npm` | Pula atualização git, lembra de executar `npm update` por conta própria |
+| CLI `openclaw` quebrado por config inválida | Fallback: ler caminho do workspace diretamente do arquivo `openclaw.json` |
+| `extensions/` em vez de `plugins/` | Detecção automática da localização do plugin a partir da config ou sistema de arquivos |
+| Já está atualizado | Executa apenas verificações de saúde, sem alterações |
+
+```bash
+bash setup-memory.sh # Install or upgrade
+bash setup-memory.sh --dry-run # Preview only
+bash setup-memory.sh --beta # Include pre-release versions
+bash setup-memory.sh --uninstall # Revert config and remove plugin
+```
+
+Presets de provedores integrados: **Jina / DashScope / SiliconFlow / OpenAI / Ollama**, ou traga sua própria API compatível com OpenAI. Para uso completo (incluindo `--ref`, `--selfcheck-only` e mais), veja o [README do script de instalação](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup).
+
+### Claude Code / OpenClaw Skill — Configuração guiada por IA
+
+> **[CortexReach/memory-lancedb-pro-skill](https://github.com/CortexReach/memory-lancedb-pro-skill)**
+
+Instale esta Skill e seu agente de IA (Claude Code ou OpenClaw) ganha conhecimento profundo de todas as funcionalidades do memory-lancedb-pro. Basta dizer **"me ajude a ativar a melhor configuração"** e obtenha:
+
+- **Workflow de configuração guiado em 7 etapas** com 4 planos de implantação:
+ - Full Power (Jina + OpenAI) / Budget (reranker SiliconFlow gratuito) / Simple (apenas OpenAI) / Totalmente local (Ollama, custo API zero)
+- **Todas as 9 ferramentas MCP** usadas corretamente: `memory_recall`, `memory_store`, `memory_forget`, `memory_update`, `memory_stats`, `memory_list`, `self_improvement_log`, `self_improvement_extract_skill`, `self_improvement_review` *(o toolkit completo requer `enableManagementTools: true` — a configuração padrão do Quick Start expõe as 4 ferramentas principais)*
+- **Prevenção de armadilhas comuns**: ativação de plugin workspace, `autoRecall` padrão false, cache jiti, variáveis de ambiente, isolamento de scope, etc.
+
+**Instalação para Claude Code:**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro
+```
+
+**Instalação para OpenClaw:**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill
+```
+
+---
+
+## Tutorial em vídeo
+
+> Guia completo: instalação, configuração e funcionamento interno da busca híbrida.
+
+[](https://youtu.be/MtukF1C8epQ)
+**https://youtu.be/MtukF1C8epQ**
+
+[](https://www.bilibili.com/video/BV1zUf2BGEgn/)
+**https://www.bilibili.com/video/BV1zUf2BGEgn/**
+
+---
+
+## Arquitetura
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ index.ts (Entry Point) │
+│ Plugin Registration · Config Parsing · Lifecycle Hooks │
+└────────┬──────────┬──────────┬──────────┬───────────────┘
+ │ │ │ │
+ ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
+ │ store │ │embedder│ │retriever│ │ scopes │
+ │ .ts │ │ .ts │ │ .ts │ │ .ts │
+ └────────┘ └────────┘ └────────┘ └─────────────┘
+ │ │
+ ┌────▼───┐ ┌─────▼──────────┐
+ │migrate │ │noise-filter.ts │
+ │ .ts │ │adaptive- │
+ └────────┘ │retrieval.ts │
+ └────────────────┘
+ ┌─────────────┐ ┌──────────┐
+ │ tools.ts │ │ cli.ts │
+ │ (Agent API) │ │ (CLI) │
+ └─────────────┘ └──────────┘
+```
+
+> Para um mergulho profundo na arquitetura completa, veja [docs/memory_architecture_analysis.md](docs/memory_architecture_analysis.md).
+
+Importação rápida via Telegram Bot (clique para expandir)
+ +Se você está usando a integração Telegram do OpenClaw, a maneira mais fácil é enviar um comando de importação diretamente para o Bot principal em vez de editar a configuração manualmente. + +Envie esta mensagem: + +```text +Help me connect this memory plugin with the most user-friendly configuration: https://github.com/CortexReach/memory-lancedb-pro + +Requirements: +1. Set it as the only active memory plugin +2. Use Jina for embedding +3. Use Jina for reranker +4. Use gpt-4o-mini for the smart-extraction LLM +5. Enable autoCapture, autoRecall, smartExtraction +6. extractMinMessages=2 +7. sessionMemory.enabled=false +8. captureAssistant=false +9. retrieval mode=hybrid, vectorWeight=0.7, bm25Weight=0.3 +10. rerank=cross-encoder, candidatePoolSize=12, minScore=0.6, hardMinScore=0.62 +11. Generate the final openclaw.json config directly, not just an explanation +``` + +
+
+
+---
+
+## Funcionalidades principais
+
+### Busca híbrida
+
+```
+Query → embedQuery() ─┐
+ ├─→ Hybrid Fusion → Rerank → Lifecycle Decay Boost → Length Norm → Filter
+Query → BM25 FTS ─────┘
+```
+
+- **Busca vetorial** — similaridade semântica via LanceDB ANN (distância cosseno)
+- **Busca full-text BM25** — correspondência exata de palavras-chave via índice FTS do LanceDB
+- **Fusão híbrida** — pontuação vetorial como base, resultados BM25 recebem boost ponderado (não é RRF padrão — ajustado para qualidade de recall no mundo real)
+- **Pesos configuráveis** — `vectorWeight`, `bm25Weight`, `minScore`
+
+### Reranking Cross-Encoder
+
+- Adaptadores integrados para **Jina**, **SiliconFlow**, **Voyage AI** e **Pinecone**
+- Compatível com qualquer endpoint compatível com Jina (ex.: Hugging Face TEI, DashScope)
+- Pontuação híbrida: 60% cross-encoder + 40% pontuação fundida original
+- Degradação elegante: fallback para similaridade cosseno em caso de falha da API
+
+### Pipeline de pontuação multi-estágio
+
+| Estágio | Efeito |
+| --- | --- |
+| **Fusão híbrida** | Combina recall semântico e correspondência exata |
+| **Rerank Cross-Encoder** | Promove resultados semanticamente precisos |
+| **Boost de decaimento do ciclo de vida** | Frescor Weibull + frequência de acesso + importância × confiança |
+| **Normalização de comprimento** | Impede que entradas longas dominem (âncora: 500 caracteres) |
+| **Pontuação mínima rígida** | Remove resultados irrelevantes (padrão: 0.35) |
+| **Diversidade MMR** | Similaridade cosseno > 0.85 → rebaixado |
+
+### Extração inteligente de memória (v1.1.0)
+
+- **Extração LLM em 6 categorias**: perfil, preferências, entidades, eventos, casos, padrões
+- **Armazenamento em camadas L0/L1/L2**: L0 (índice em uma frase) → L1 (resumo estruturado) → L2 (narrativa completa)
+- **Deduplicação em dois estágios**: pré-filtro de similaridade vetorial (≥0.7) → decisão semântica LLM (CREATE/MERGE/SKIP)
+- **Fusão consciente de categorias**: `profile` sempre funde, `events`/`cases` apenas adicionam
+
+### Gerenciamento do ciclo de vida da memória (v1.1.0)
+
+- **Motor de decaimento Weibull**: pontuação composta = frescor + frequência + valor intrínseco
+- **Promoção em três níveis**: `Peripheral ↔ Working ↔ Core` com limiares configuráveis
+- **Reforço por acesso**: memórias recuperadas frequentemente decaem mais lentamente (estilo repetição espaçada)
+- **Meia-vida modulada pela importância**: memórias importantes decaem mais lentamente
+
+### Isolamento multi-scope
+
+- Scopes integrados: `global`, `agent:Referência de arquivos (clique para expandir)
+ +| Arquivo | Finalidade | +| --- | --- | +| `index.ts` | Ponto de entrada do plugin. Registra na API de Plugin do OpenClaw, analisa config, monta lifecycle hooks | +| `openclaw.plugin.json` | Metadados do plugin + declaração completa de config via JSON Schema | +| `cli.ts` | Comandos CLI: `memory-pro list/search/stats/delete/delete-bulk/export/import/reembed/upgrade/migrate` | +| `src/store.ts` | Camada de armazenamento LanceDB. Criação de tabelas / Indexação FTS / Busca vetorial / Busca BM25 / CRUD | +| `src/embedder.ts` | Abstração de embedding. Compatível com qualquer provedor de API compatível com OpenAI | +| `src/retriever.ts` | Motor de busca híbrida. Vector + BM25 → Fusão Híbrida → Rerank → Decaimento do Ciclo de Vida → Filtro | +| `src/scopes.ts` | Controle de acesso multi-scope | +| `src/tools.ts` | Definições de ferramentas do agente: `memory_recall`, `memory_store`, `memory_forget`, `memory_update` + ferramentas de gerenciamento | +| `src/noise-filter.ts` | Filtra recusas do agente, meta-perguntas, saudações e conteúdo de baixa qualidade | +| `src/adaptive-retrieval.ts` | Determina se uma consulta precisa de busca na memória | +| `src/migrate.ts` | Migração do `memory-lancedb` integrado para o Pro | +| `src/smart-extractor.ts` | Extração LLM em 6 categorias com armazenamento em camadas L0/L1/L2 e deduplicação em dois estágios | +| `src/decay-engine.ts` | Modelo de decaimento exponencial esticado Weibull | +| `src/tier-manager.ts` | Promoção/rebaixamento em três níveis: Peripheral ↔ Working ↔ Core | + +
+Comparação com o
+
+| Funcionalidade | `memory-lancedb` integrado | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| Busca vetorial | Sim | Sim |
+| Busca full-text BM25 | - | Sim |
+| Fusão híbrida (Vector + BM25) | - | Sim |
+| Rerank cross-encoder (multi-provedor) | - | Sim |
+| Boost de frescor e decaimento temporal | - | Sim |
+| Normalização de comprimento | - | Sim |
+| Diversidade MMR | - | Sim |
+| Isolamento multi-scope | - | Sim |
+| Filtragem de ruído | - | Sim |
+| Busca adaptativa | - | Sim |
+| CLI de gerenciamento | - | Sim |
+| Memória de sessão | - | Sim |
+| Embeddings conscientes de tarefa | - | Sim |
+| **Extração inteligente LLM (6 categorias)** | - | Sim (v1.1.0) |
+| **Decaimento Weibull + Promoção de nível** | - | Sim (v1.1.0) |
+| Qualquer embedding compatível com OpenAI | Limitado | Sim |
+
+
+
+---
+
+## Configuração
+
+Comparação com o memory-lancedb integrado (clique para expandir)
+
+| Funcionalidade | `memory-lancedb` integrado | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| Busca vetorial | Sim | Sim |
+| Busca full-text BM25 | - | Sim |
+| Fusão híbrida (Vector + BM25) | - | Sim |
+| Rerank cross-encoder (multi-provedor) | - | Sim |
+| Boost de frescor e decaimento temporal | - | Sim |
+| Normalização de comprimento | - | Sim |
+| Diversidade MMR | - | Sim |
+| Isolamento multi-scope | - | Sim |
+| Filtragem de ruído | - | Sim |
+| Busca adaptativa | - | Sim |
+| CLI de gerenciamento | - | Sim |
+| Memória de sessão | - | Sim |
+| Embeddings conscientes de tarefa | - | Sim |
+| **Extração inteligente LLM (6 categorias)** | - | Sim (v1.1.0) |
+| **Decaimento Weibull + Promoção de nível** | - | Sim (v1.1.0) |
+| Qualquer embedding compatível com OpenAI | Limitado | Sim |
+
+
+
+
+Exemplo de configuração completa
+ +```json +{ + "embedding": { + "apiKey": "${JINA_API_KEY}", + "model": "jina-embeddings-v5-text-small", + "baseURL": "https://api.jina.ai/v1", + "dimensions": 1024, + "taskQuery": "retrieval.query", + "taskPassage": "retrieval.passage", + "normalized": true + }, + "dbPath": "~/.openclaw/memory/lancedb-pro", + "autoCapture": true, + "autoRecall": true, + "retrieval": { + "mode": "hybrid", + "vectorWeight": 0.7, + "bm25Weight": 0.3, + "minScore": 0.3, + "rerank": "cross-encoder", + "rerankApiKey": "${JINA_API_KEY}", + "rerankModel": "jina-reranker-v3", + "rerankEndpoint": "https://api.jina.ai/v1/rerank", + "rerankProvider": "jina", + "candidatePoolSize": 20, + "recencyHalfLifeDays": 14, + "recencyWeight": 0.1, + "filterNoise": true, + "lengthNormAnchor": 500, + "hardMinScore": 0.35, + "timeDecayHalfLifeDays": 60, + "reinforcementFactor": 0.5, + "maxHalfLifeMultiplier": 3 + }, + "enableManagementTools": false, + "scopes": { + "default": "global", + "definitions": { + "global": { "description": "Shared knowledge" }, + "agent:discord-bot": { "description": "Discord bot private" } + }, + "agentAccess": { + "discord-bot": ["global", "agent:discord-bot"] + } + }, + "sessionMemory": { + "enabled": false, + "messageCount": 15 + }, + "smartExtraction": true, + "llm": { + "apiKey": "${OPENAI_API_KEY}", + "model": "gpt-4o-mini", + "baseURL": "https://api.openai.com/v1" + }, + "extractMinMessages": 2, + "extractMaxChars": 8000 +} +``` + +
+
+
+Provedores de Embedding
+ +Funciona com **qualquer API de embedding compatível com OpenAI**: + +| Provedor | Modelo | Base URL | Dimensões | +| --- | --- | --- | --- | +| **Jina** (recomendado) | `jina-embeddings-v5-text-small` | `https://api.jina.ai/v1` | 1024 | +| **OpenAI** | `text-embedding-3-small` | `https://api.openai.com/v1` | 1536 | +| **Voyage** | `voyage-4-lite` / `voyage-4` | `https://api.voyageai.com/v1` | 1024 / 1024 | +| **Google Gemini** | `gemini-embedding-001` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 | +| **Ollama** (local) | `nomic-embed-text` | `http://localhost:11434/v1` | específico do provedor | + +
+
+
+Provedores de Rerank
+ +O reranking cross-encoder suporta múltiplos provedores via `rerankProvider`: + +| Provedor | `rerankProvider` | Modelo de exemplo | +| --- | --- | --- | +| **Jina** (padrão) | `jina` | `jina-reranker-v3` | +| **SiliconFlow** (plano gratuito disponível) | `siliconflow` | `BAAI/bge-reranker-v2-m3` | +| **Voyage AI** | `voyage` | `rerank-2.5` | +| **Pinecone** | `pinecone` | `bge-reranker-v2-m3` | + +Qualquer endpoint de rerank compatível com Jina também funciona — defina `rerankProvider: "jina"` e aponte `rerankEndpoint` para seu serviço (ex.: Hugging Face TEI, DashScope `qwen3-rerank`). + +
+
+
+Extração inteligente (LLM) — v1.1.0
+ +Quando `smartExtraction` está habilitado (padrão: `true`), o plugin usa um LLM para extrair e classificar memórias de forma inteligente em vez de gatilhos baseados em regex. + +| Campo | Tipo | Padrão | Descrição | +|-------|------|--------|-----------| +| `smartExtraction` | boolean | `true` | Habilitar/desabilitar extração LLM em 6 categorias | +| `llm.auth` | string | `api-key` | `api-key` usa `llm.apiKey` / `embedding.apiKey`; `oauth` usa um arquivo de token OAuth com escopo de plugin por padrão | +| `llm.apiKey` | string | *(fallback para `embedding.apiKey`)* | Chave de API para o provedor LLM | +| `llm.model` | string | `openai/gpt-oss-120b` | Nome do modelo LLM | +| `llm.baseURL` | string | *(fallback para `embedding.baseURL`)* | Endpoint da API LLM | +| `llm.oauthProvider` | string | `openai-codex` | ID do provedor OAuth usado quando `llm.auth` é `oauth` | +| `llm.oauthPath` | string | `~/.openclaw/.memory-lancedb-pro/oauth.json` | Arquivo de token OAuth usado quando `llm.auth` é `oauth` | +| `llm.timeoutMs` | number | `30000` | Timeout da requisição LLM em milissegundos | +| `extractMinMessages` | number | `2` | Mensagens mínimas antes da extração ser acionada | +| `extractMaxChars` | number | `8000` | Máximo de caracteres enviados ao LLM | + + +Configuração `llm` com OAuth (usa cache de login existente do Codex / ChatGPT para chamadas LLM): +```json +{ + "llm": { + "auth": "oauth", + "oauthProvider": "openai-codex", + "model": "gpt-5.4", + "oauthPath": "${HOME}/.openclaw/.memory-lancedb-pro/oauth.json", + "timeoutMs": 30000 + } +} +``` + +Notas para `llm.auth: "oauth"`: + +- `llm.oauthProvider` é atualmente `openai-codex`. +- Tokens OAuth têm como padrão `~/.openclaw/.memory-lancedb-pro/oauth.json`. +- Você pode definir `llm.oauthPath` se quiser armazenar esse arquivo em outro lugar. +- `auth login` faz snapshot da configuração `llm` anterior (api-key) ao lado do arquivo OAuth, e `auth logout` restaura esse snapshot quando disponível. +- Mudar de `api-key` para `oauth` não transfere automaticamente `llm.baseURL`. Defina-o manualmente no modo OAuth apenas quando você intencionalmente quiser um backend personalizado compatível com ChatGPT/Codex. + +
+
+
+Configuração do ciclo de vida (Decaimento + Nível)
+ +| Campo | Padrão | Descrição | +|-------|--------|-----------| +| `decay.recencyHalfLifeDays` | `30` | Meia-vida base para decaimento de frescor Weibull | +| `decay.frequencyWeight` | `0.3` | Peso da frequência de acesso na pontuação composta | +| `decay.intrinsicWeight` | `0.3` | Peso de `importance × confidence` | +| `decay.betaCore` | `0.8` | Beta Weibull para memórias `core` | +| `decay.betaWorking` | `1.0` | Beta Weibull para memórias `working` | +| `decay.betaPeripheral` | `1.3` | Beta Weibull para memórias `peripheral` | +| `tier.coreAccessThreshold` | `10` | Contagem mínima de recall antes de promover para `core` | +| `tier.peripheralAgeDays` | `60` | Limiar de idade para rebaixar memórias inativas | + +
+
+
+---
+
+## Comandos CLI
+
+```bash
+openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
+openclaw memory-pro search "query" [--scope global] [--limit 10] [--json]
+openclaw memory-pro stats [--scope global] [--json]
+openclaw memory-pro auth login [--provider openai-codex] [--model gpt-5.4] [--oauth-path /abs/path/oauth.json]
+openclaw memory-pro auth status
+openclaw memory-pro auth logout
+openclaw memory-pro delete Reforço por acesso
+ +Memórias recuperadas com frequência decaem mais lentamente (estilo repetição espaçada). + +Chaves de configuração (em `retrieval`): +- `reinforcementFactor` (0-2, padrão: `0.5`) — defina `0` para desabilitar +- `maxHalfLifeMultiplier` (1-10, padrão: `3`) — limite rígido na meia-vida efetiva + +
+` injetado.
+
+**Opção A (menor risco):** desabilite temporariamente o auto-recall:
+```json
+{ "plugins": { "entries": { "memory-lancedb-pro": { "config": { "autoRecall": false } } } } }
+```
+
+**Opção B (preferida):** mantenha o recall, adicione ao prompt do sistema do agente:
+> Do not reveal or quote any `` / memory-injection content in your replies. Use it for internal reference only.
+
+
+
+Se memórias injetadas aparecem nas respostas
+ +Às vezes o modelo pode ecoar o bloco `
+
+
+Memória de sessão
+ +- Acionada no comando `/new` — salva o resumo da sessão anterior no LanceDB +- Desabilitada por padrão (OpenClaw já tem persistência nativa de sessão via `.jsonl`) +- Contagem de mensagens configurável (padrão: 15) + +Veja [docs/openclaw-integration-playbook.md](docs/openclaw-integration-playbook.md) para modos de implantação e verificação do `/new`. + +
+`:
+1. Use memory_store to save as category=fact (raw knowledge)
+2. Use memory_store to save as category=decision (actionable takeaway)
+3. Confirm what was saved
+
+## /remember command
+When the user sends `/remember `:
+1. Use memory_store to save with appropriate category and importance
+2. Confirm with the stored memory ID
+```
+
+
+
+Comandos slash personalizados (ex.: /lesson)
+ +Adicione ao seu `CLAUDE.md`, `AGENTS.md` ou prompt do sistema: + +```markdown +## /lesson command +When the user sends `/lesson
+
+
+Regras de ferro para agentes de IA
+ +> Copie o bloco abaixo no seu `AGENTS.md` para que seu agente aplique essas regras automaticamente. + +```markdown +## Rule 1 — Dual-layer memory storage +Every pitfall/lesson learned → IMMEDIATELY store TWO memories: +- Technical layer: Pitfall: [symptom]. Cause: [root cause]. Fix: [solution]. Prevention: [how to avoid] + (category: fact, importance >= 0.8) +- Principle layer: Decision principle ([tag]): [behavioral rule]. Trigger: [when]. Action: [what to do] + (category: decision, importance >= 0.85) + +## Rule 2 — LanceDB hygiene +Entries must be short and atomic (< 500 chars). No raw conversation summaries or duplicates. + +## Rule 3 — Recall before retry +On ANY tool failure, ALWAYS memory_recall with relevant keywords BEFORE retrying. + +## Rule 4 — Confirm target codebase +Confirm you are editing memory-lancedb-pro vs built-in memory-lancedb before changes. + +## Rule 5 — Clear jiti cache after plugin code changes +After modifying .ts files under plugins/, MUST run rm -rf /tmp/jiti/ BEFORE openclaw gateway restart. +``` + +
+
+
+Schema do banco de dados
+ +Tabela LanceDB `memories`: + +| Campo | Tipo | Descrição | +| --- | --- | --- | +| `id` | string (UUID) | Chave primária | +| `text` | string | Texto da memória (indexado FTS) | +| `vector` | float[] | Vetor de embedding | +| `category` | string | Categoria de armazenamento: `preference` / `fact` / `decision` / `entity` / `reflection` / `other` | +| `scope` | string | Identificador de scope (ex.: `global`, `agent:main`) | +| `importance` | float | Pontuação de importância 0-1 | +| `timestamp` | int64 | Timestamp de criação (ms) | +| `metadata` | string (JSON) | Metadados estendidos | + +Chaves `metadata` comuns no v1.1.0: `l0_abstract`, `l1_overview`, `l2_content`, `memory_category`, `tier`, `access_count`, `confidence`, `last_accessed_at` + +> **Nota sobre categorias:** O campo `category` de nível superior usa 6 categorias de armazenamento. As 6 categorias semânticas da Extração Inteligente (`profile` / `preferences` / `entities` / `events` / `cases` / `patterns`) são armazenadas em `metadata.memory_category`. + +
+
+
+---
+
+## Documentação
+
+| Documento | Descrição |
+| --- | --- |
+| [Playbook de integração OpenClaw](docs/openclaw-integration-playbook.md) | Modos de implantação, verificação, matriz de regressão |
+| [Análise da arquitetura de memória](docs/memory_architecture_analysis.md) | Análise aprofundada da arquitetura completa |
+| [CHANGELOG v1.1.0](docs/CHANGELOG-v1.1.0.md) | Mudanças de comportamento v1.1.0 e justificativa de upgrade |
+| [Chunking de contexto longo](docs/long-context-chunking.md) | Estratégia de chunking para documentos longos |
+
+---
+
+## Beta: Smart Memory v1.1.0
+
+> Status: Beta — disponível via `npm i memory-lancedb-pro@beta`. Usuários estáveis no `latest` não são afetados.
+
+| Funcionalidade | Descrição |
+|---------|-------------|
+| **Extração inteligente** | Extração LLM em 6 categorias com metadados L0/L1/L2. Fallback para regex quando desabilitado. |
+| **Pontuação do ciclo de vida** | Decaimento Weibull integrado à busca — memórias frequentes e importantes ficam mais bem ranqueadas. |
+| **Gerenciamento de níveis** | Sistema de três níveis (Core → Working → Peripheral) com promoção/rebaixamento automático. |
+
+Feedback: [GitHub Issues](https://github.com/CortexReach/memory-lancedb-pro/issues) · Reverter: `npm i memory-lancedb-pro@latest`
+
+---
+
+## Dependências
+
+| Pacote | Finalidade |
+| --- | --- |
+| `@lancedb/lancedb` ≥0.26.2 | Banco de dados vetorial (ANN + FTS) |
+| `openai` ≥6.21.0 | Cliente de API de Embedding compatível com OpenAI |
+| `@sinclair/typebox` 0.34.48 | Definições de tipo JSON Schema |
+
+---
+
+## Contributors
+
+Solução de problemas
+ +### "Cannot mix BigInt and other types" (LanceDB / Apache Arrow) + +No LanceDB 0.26+, algumas colunas numéricas podem ser retornadas como `BigInt`. Atualize para **memory-lancedb-pro >= 1.0.14** — este plugin agora converte valores usando `Number(...)` antes de operações aritméticas. + +
+
+
+# 🧠 memory-lancedb-pro · 🦞OpenClaw Plugin
+
+**ИИ-ассистент памяти для агентов [OpenClaw](https://github.com/openclaw/openclaw)**
+
+*Дайте вашему ИИ-агенту мозг, который действительно помнит: между сессиями, между агентами и с течением времени.*
+
+Плагин долгосрочной памяти для OpenClaw на базе LanceDB, который сохраняет предпочтения, решения и контекст проекта, а затем автоматически вспоминает их в будущих сессиях.
+
+[](https://github.com/openclaw/openclaw)
+[](https://www.npmjs.com/package/memory-lancedb-pro)
+[](https://lancedb.com)
+[](LICENSE)
+
+[English](README.md) | [简体中文](README_CN.md) | [繁體中文](README_TW.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | [Español](README_ES.md) | [Deutsch](README_DE.md) | [Italiano](README_IT.md) | [Русский](README_RU.md) | [Português (Brasil)](README_PT-BR.md)
+
+
+
+---
+
+## Почему memory-lancedb-pro?
+
+Большинство ИИ-агентов страдают амнезией. Они забывают все, как только вы начинаете новый чат.
+
+**memory-lancedb-pro** — это production-grade плагин долгосрочной памяти для OpenClaw, который превращает вашего агента в настоящего **ИИ-ассистента памяти**. Он автоматически фиксирует важное, позволяет шуму естественно угасать и поднимает нужное воспоминание в нужный момент. Никаких ручных тегов, никаких мучений с конфигурацией.
+
+### Как это выглядит на практике
+
+**Без памяти: каждая сессия начинается с нуля**
+
+> **Вы:** "Используй табы для отступов и всегда добавляй обработку ошибок."
+> *(следующая сессия)*
+> **Вы:** "Я же уже говорил: табы, а не пробелы!" 😤
+> *(еще одна сессия)*
+> **Вы:** "...серьезно, табы. И обработка ошибок. Снова."
+
+**С memory-lancedb-pro агент учится и помнит**
+
+> **Вы:** "Используй табы для отступов и всегда добавляй обработку ошибок."
+> *(следующая сессия: агент автоматически вспоминает ваши предпочтения)*
+> **Агент:** *(молча применяет табы + обработку ошибок)* ✅
+> **Вы:** "Почему в прошлом месяце мы выбрали PostgreSQL, а не MongoDB?"
+> **Агент:** "Судя по нашему обсуждению 12 февраля, основные причины были..." ✅
+
+В этом и есть разница: **ИИ-ассистент памяти** изучает ваш стиль, вспоминает прошлые решения и дает персонализированные ответы без необходимости повторять одно и то же.
+
+### Что еще он умеет?
+
+| | Что вы получаете |
+|---|---|
+| **Автозахват** | Агент учится на каждом разговоре, без ручного `memory_store` |
+| **Умное извлечение** | Классификация на основе LLM по 6 категориям: профили, предпочтения, сущности, события, кейсы, паттерны |
+| **Интеллектуальное забывание** | Модель затухания Weibull: важные воспоминания остаются, шум естественно исчезает |
+| **Гибридный поиск** | Векторный поиск + полнотекстовый BM25 с объединением и cross-encoder rerank |
+| **Инъекция контекста** | Релевантные воспоминания автоматически подаются перед каждым ответом |
+| **Изоляция областей памяти** | Границы памяти на уровне агента, пользователя и проекта |
+| **Любой провайдер** | OpenAI, Jina, Gemini, Ollama или любой OpenAI-compatible API |
+| **Полный набор инструментов** | CLI, backup, migration, upgrade, export/import — готово к продакшену |
+
+---
+
+## Быстрый старт
+
+### Вариант A: скрипт установки в один клик (рекомендуется)
+
+Поддерживаемый сообществом **[скрипт установки](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)** берет на себя установку, обновление и восстановление одной командой:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
+bash setup-memory.sh
+```
+
+> Полный список сценариев, которые покрывает скрипт, и другие инструменты сообщества смотрите ниже в разделе [Экосистема](#экосистема).
+
+### Вариант B: ручная установка
+
+**Через OpenClaw CLI (рекомендуется):**
+```bash
+openclaw plugins install memory-lancedb-pro@beta
+```
+
+**Или через npm:**
+```bash
+npm i memory-lancedb-pro@beta
+```
+> Если используете npm, вам также нужно добавить директорию установки плагина как **абсолютный** путь в `plugins.load.paths` вашего `openclaw.json`. Это самая частая проблема при настройке.
+
+Добавьте в `openclaw.json`:
+
+```json
+{
+ "plugins": {
+ "slots": { "memory": "memory-lancedb-pro" },
+ "entries": {
+ "memory-lancedb-pro": {
+ "enabled": true,
+ "config": {
+ "embedding": {
+ "provider": "openai-compatible",
+ "apiKey": "${OPENAI_API_KEY}",
+ "model": "text-embedding-3-small"
+ },
+ "autoCapture": true,
+ "autoRecall": true,
+ "smartExtraction": true,
+ "extractMinMessages": 2,
+ "extractMaxChars": 8000,
+ "sessionMemory": { "enabled": false }
+ }
+ }
+ }
+ }
+}
+```
+
+**Почему именно такие значения по умолчанию?**
+- `autoCapture` + `smartExtraction` → агент автоматически учится на каждом разговоре
+- `autoRecall` → релевантные воспоминания подставляются перед каждым ответом
+- `extractMinMessages: 2` → извлечение срабатывает в обычном двухходовом диалоге
+- `sessionMemory.enabled: false` → поиск не засоряется сводками сессий с первого дня
+
+Проверьте и перезапустите:
+
+```bash
+openclaw config validate
+openclaw gateway restart
+openclaw logs --follow --plain | grep "memory-lancedb-pro"
+```
+
+Вы должны увидеть:
+- `memory-lancedb-pro: smart extraction enabled`
+- `memory-lancedb-pro@...: plugin registered`
+
+Готово. Теперь у вашего агента есть долгосрочная память.
+
+
+
+
+Дополнительные варианты установки (для действующих пользователей и апгрейдов)
+ +**Уже используете OpenClaw?** + +1. Добавьте плагин в `plugins.load.paths` как **абсолютный** путь +2. Привяжите memory slot: `plugins.slots.memory = "memory-lancedb-pro"` +3. Проверьте: `openclaw plugins info memory-lancedb-pro && openclaw memory-pro stats` + +**Обновляетесь с версии до v1.1.0?** + +```bash +# 1) Резервная копия +openclaw memory-pro export --scope global --output memories-backup.json +# 2) Пробный запуск +openclaw memory-pro upgrade --dry-run +# 3) Выполнить апгрейд +openclaw memory-pro upgrade +# 4) Проверка +openclaw memory-pro stats +``` + +Изменения поведения и причины апгрейда описаны в `CHANGELOG-v1.1.0.md`. + +
+
+
+---
+
+## Экосистема
+
+memory-lancedb-pro — это основной плагин. Сообщество построило вокруг него инструменты, чтобы установка и ежедневная работа были еще проще.
+
+### Скрипт установки: установка, апгрейд и ремонт в один клик
+
+> **[CortexReach/toolbox/memory-lancedb-pro-setup](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)**
+
+Это не просто установщик: скрипт грамотно обрабатывает широкий набор реальных сценариев.
+
+| Ваша ситуация | Что делает скрипт |
+|---|---|
+| Никогда не устанавливали | Скачивает заново → ставит зависимости → помогает выбрать конфиг → записывает в `openclaw.json` → перезапускает |
+| Установлено через `git clone`, но застряли на старом коммите | Автоматически делает `git fetch` + `checkout` на актуальную версию → переустанавливает зависимости → проверяет |
+| В конфиге есть невалидные поля | Автоматически находит их через schema filter и удаляет неподдерживаемые значения |
+| Установлено через `npm` | Пропускает git-обновление и напоминает вручную запустить `npm update` |
+| `openclaw` CLI сломан из-за невалидного конфига | Фолбэк: читает путь workspace напрямую из файла `openclaw.json` |
+| Используется `extensions/`, а не `plugins/` | Автоматически определяет расположение плагина по конфигу или файловой системе |
+| Уже актуальная версия | Запускает только health checks, без изменений |
+
+```bash
+bash setup-memory.sh # Установить или обновить
+bash setup-memory.sh --dry-run # Только предпросмотр
+bash setup-memory.sh --beta # Включить pre-release версии
+bash setup-memory.sh --uninstall # Откатить конфиг и удалить плагин
+```
+
+Встроенные пресеты провайдеров: **Jina / DashScope / SiliconFlow / OpenAI / Ollama**, либо любой собственный OpenAI-compatible API. Полное использование (включая `--ref`, `--selfcheck-only` и другое) смотрите в [README скрипта установки](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup).
+
+### Навык Claude Code / OpenClaw: настройка под управлением ИИ
+
+> **[CortexReach/memory-lancedb-pro-skill](https://github.com/CortexReach/memory-lancedb-pro-skill)**
+
+Установите этот навык, и ваш ИИ-агент (Claude Code или OpenClaw) получит глубокое знание всех возможностей memory-lancedb-pro. Достаточно сказать **"help me enable the best config"**, и вы получите:
+
+- **Пошаговый процесс настройки из 7 шагов** с 4 вариантами деплоя:
+ - Полная мощность (Jina + OpenAI) / Экономный (бесплатный reranker от SiliconFlow) / Простой (только OpenAI) / Полностью локальный (Ollama, нулевая стоимость API)
+- **Корректное использование всех 9 инструментов MCP**: `memory_recall`, `memory_store`, `memory_forget`, `memory_update`, `memory_stats`, `memory_list`, `self_improvement_log`, `self_improvement_extract_skill`, `self_improvement_review` *(полный набор доступен при `enableManagementTools: true` — стандартный Quick Start открывает только 4 базовых инструмента)*
+- **Защиту от типичных ошибок**: включение плагина в workspace, `autoRecall` со значением false по умолчанию, кэш jiti, переменные окружения, изоляция областей памяти и другое
+
+**Установка для Claude Code:**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro
+```
+
+**Установка для OpenClaw:**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill
+```
+
+---
+
+## Видеоруководство
+
+> Полный разбор: установка, настройка и внутреннее устройство гибридного поиска.
+
+[](https://youtu.be/MtukF1C8epQ)
+**https://youtu.be/MtukF1C8epQ**
+
+[](https://www.bilibili.com/video/BV1zUf2BGEgn/)
+**https://www.bilibili.com/video/BV1zUf2BGEgn/**
+
+---
+
+## Архитектура
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ index.ts (Entry Point) │
+│ Plugin Registration · Config Parsing · Lifecycle Hooks │
+└────────┬──────────┬──────────┬──────────┬───────────────┘
+ │ │ │ │
+ ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
+ │ store │ │embedder│ │retriever│ │ scopes │
+ │ .ts │ │ .ts │ │ .ts │ │ .ts │
+ └────────┘ └────────┘ └────────┘ └─────────────┘
+ │ │
+ ┌────▼───┐ ┌─────▼──────────┐
+ │migrate │ │noise-filter.ts │
+ │ .ts │ │adaptive- │
+ └────────┘ │retrieval.ts │
+ └────────────────┘
+ ┌─────────────┐ ┌──────────┐
+ │ tools.ts │ │ cli.ts │
+ │ (Agent API) │ │ (CLI) │
+ └─────────────┘ └──────────┘
+```
+
+> Для глубокого разбора полной архитектуры смотрите [docs/memory_architecture_analysis.md](docs/memory_architecture_analysis.md).
+
+Быстрый импорт для Telegram Bot (нажмите, чтобы раскрыть)
+ +Если вы используете Telegram-интеграцию OpenClaw, самый простой путь — отправить команду импорта прямо основному боту вместо ручного редактирования конфига. + +Отправьте такое сообщение: + +```text +Help me connect this memory plugin with the most user-friendly configuration: https://github.com/CortexReach/memory-lancedb-pro + +Requirements: +1. Set it as the only active memory plugin +2. Use Jina for embedding +3. Use Jina for reranker +4. Use gpt-4o-mini for the smart-extraction LLM +5. Enable autoCapture, autoRecall, smartExtraction +6. extractMinMessages=2 +7. sessionMemory.enabled=false +8. captureAssistant=false +9. retrieval mode=hybrid, vectorWeight=0.7, bm25Weight=0.3 +10. rerank=cross-encoder, candidatePoolSize=12, minScore=0.6, hardMinScore=0.62 +11. Generate the final openclaw.json config directly, not just an explanation +``` + +
+
+
+---
+
+## Ключевые возможности
+
+### Гибридный поиск
+
+```
+Query → embedQuery() ─┐
+ ├─→ Hybrid Fusion → Rerank → Lifecycle Decay Boost → Length Norm → Filter
+Query → BM25 FTS ─────┘
+```
+
+- **Векторный поиск** — семантическая близость через LanceDB ANN (cosine distance)
+- **Полнотекстовый BM25** — точное совпадение по ключевым словам через LanceDB FTS index
+- **Hybrid Fusion** — векторный score служит базой, а BM25-попадания получают взвешенный буст (это не стандартный RRF, а вариант, настроенный под качество реального recall)
+- **Настраиваемые веса** — `vectorWeight`, `bm25Weight`, `minScore`
+
+### Кросс-энкодерное реранжирование
+
+- Встроенные адаптеры для **Jina**, **SiliconFlow**, **Voyage AI** и **Pinecone**
+- Совместимо с любым Jina-compatible endpoint (например, Hugging Face TEI, DashScope)
+- Гибридный скоринг: 60% cross-encoder + 40% исходный fused score
+- Graceful degradation: при сбое API откатывается к cosine similarity
+
+### Многоэтапный пайплайн скоринга
+
+| Этап | Эффект |
+| --- | --- |
+| **Hybrid Fusion** | Комбинирует семантический recall и точное совпадение |
+| **Cross-Encoder Rerank** | Продвигает семантически точные попадания |
+| **Lifecycle Decay Boost** | Свежесть по Weibull + частота доступа + важность × уверенность |
+| **Length Normalization** | Не дает длинным записям доминировать (anchor: 500 chars) |
+| **Hard Min Score** | Убирает нерелевантные результаты (по умолчанию: 0.35) |
+| **MMR Diversity** | Cosine similarity > 0.85 → понижается |
+
+### Умное извлечение памяти (v1.1.0)
+
+- **LLM-powered извлечение по 6 категориям**: profile, preferences, entities, events, cases, patterns
+- **Многослойное хранение L0/L1/L2**: L0 (одно предложение-индекс) → L1 (структурированное summary) → L2 (полный narrative)
+- **Двухэтапная дедупликация**: предварительный фильтр по векторному сходству (≥0.7) → LLM-решение по смыслу (CREATE/MERGE/SKIP)
+- **Слияние с учетом категории**: `profile` всегда merge, `events` и `cases` добавляются append-only
+
+### Управление жизненным циклом памяти (v1.1.0)
+
+- **Weibull Decay Engine**: composite score = recency + frequency + intrinsic value
+- **Трехуровневое продвижение**: `Peripheral ↔ Working ↔ Core` с настраиваемыми порогами
+- **Усиление при доступе**: часто вспоминаемые записи затухают медленнее (в духе spaced repetition)
+- **Half-life с учетом важности**: важные воспоминания живут дольше
+
+### Изоляция между областями памяти
+
+- Встроенные области памяти: `global`, `agent:Справочник по файлам (нажмите, чтобы раскрыть)
+ +| Файл | Назначение | +| --- | --- | +| `index.ts` | Точка входа плагина. Регистрация в API плагинов OpenClaw, разбор конфига, подключение хуков жизненного цикла | +| `openclaw.plugin.json` | Метаданные плагина + полная декларация JSON Schema для конфига | +| `cli.ts` | CLI-команды: `memory-pro list/search/stats/delete/delete-bulk/export/import/reembed/upgrade/migrate` | +| `src/store.ts` | Слой хранения LanceDB. Создание таблиц / FTS-индекс / векторный поиск / BM25-поиск / CRUD | +| `src/embedder.ts` | Абстракция эмбеддингов. Совместима с любым провайдером OpenAI-compatible API | +| `src/retriever.ts` | Движок гибридного поиска. Векторный поиск + BM25 → гибридное объединение → реранжирование → затухание жизненного цикла → фильтрация | +| `src/scopes.ts` | Контроль доступа для нескольких областей памяти | +| `src/tools.ts` | Определения инструментов агента: `memory_recall`, `memory_store`, `memory_forget`, `memory_update` + административные инструменты | +| `src/noise-filter.ts` | Фильтрует отказы агента, мета-вопросы, приветствия и низкокачественный контент | +| `src/adaptive-retrieval.ts` | Определяет, нужен ли конкретному запросу поиск по памяти | +| `src/migrate.ts` | Миграция со встроенного `memory-lancedb` на Pro | +| `src/smart-extractor.ts` | Извлечение по 6 категориям на базе LLM с многослойным хранением L0/L1/L2 и двухэтапной дедупликацией | +| `src/decay-engine.ts` | Модель растянутого экспоненциального затухания Weibull | +| `src/tier-manager.ts` | Трехуровневое продвижение/понижение: Peripheral ↔ Working ↔ Core | + +
+Сравнение со встроенным
+
+| Возможность | Встроенный `memory-lancedb` | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| Векторный поиск | Yes | Yes |
+| Полнотекстовый BM25 | - | Yes |
+| Гибридное объединение (Vector + BM25) | - | Yes |
+| Реранжирование cross-encoder (несколько провайдеров) | - | Yes |
+| Буст по свежести и затухание во времени | - | Yes |
+| Нормализация по длине | - | Yes |
+| MMR-диверсификация | - | Yes |
+| Изоляция областей памяти | - | Yes |
+| Фильтрация шума | - | Yes |
+| Адаптивный поиск по памяти | - | Yes |
+| Административный CLI | - | Yes |
+| Память сессий | - | Yes |
+| Эмбеддинги с учетом задачи | - | Yes |
+| **Умное извлечение LLM (6 категорий)** | - | Yes (v1.1.0) |
+| **Затухание Weibull + продвижение по уровням** | - | Yes (v1.1.0) |
+| Любые OpenAI-compatible эмбеддинги | Limited | Yes |
+
+
+
+---
+
+## Конфигурация
+
+Сравнение со встроенным memory-lancedb (нажмите, чтобы раскрыть)
+
+| Возможность | Встроенный `memory-lancedb` | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| Векторный поиск | Yes | Yes |
+| Полнотекстовый BM25 | - | Yes |
+| Гибридное объединение (Vector + BM25) | - | Yes |
+| Реранжирование cross-encoder (несколько провайдеров) | - | Yes |
+| Буст по свежести и затухание во времени | - | Yes |
+| Нормализация по длине | - | Yes |
+| MMR-диверсификация | - | Yes |
+| Изоляция областей памяти | - | Yes |
+| Фильтрация шума | - | Yes |
+| Адаптивный поиск по памяти | - | Yes |
+| Административный CLI | - | Yes |
+| Память сессий | - | Yes |
+| Эмбеддинги с учетом задачи | - | Yes |
+| **Умное извлечение LLM (6 категорий)** | - | Yes (v1.1.0) |
+| **Затухание Weibull + продвижение по уровням** | - | Yes (v1.1.0) |
+| Любые OpenAI-compatible эмбеддинги | Limited | Yes |
+
+
+
+
+Полный пример конфигурации
+ +```json +{ + "embedding": { + "apiKey": "${JINA_API_KEY}", + "model": "jina-embeddings-v5-text-small", + "baseURL": "https://api.jina.ai/v1", + "dimensions": 1024, + "taskQuery": "retrieval.query", + "taskPassage": "retrieval.passage", + "normalized": true + }, + "dbPath": "~/.openclaw/memory/lancedb-pro", + "autoCapture": true, + "autoRecall": true, + "retrieval": { + "mode": "hybrid", + "vectorWeight": 0.7, + "bm25Weight": 0.3, + "minScore": 0.3, + "rerank": "cross-encoder", + "rerankApiKey": "${JINA_API_KEY}", + "rerankModel": "jina-reranker-v3", + "rerankEndpoint": "https://api.jina.ai/v1/rerank", + "rerankProvider": "jina", + "candidatePoolSize": 20, + "recencyHalfLifeDays": 14, + "recencyWeight": 0.1, + "filterNoise": true, + "lengthNormAnchor": 500, + "hardMinScore": 0.35, + "timeDecayHalfLifeDays": 60, + "reinforcementFactor": 0.5, + "maxHalfLifeMultiplier": 3 + }, + "enableManagementTools": false, + "scopes": { + "default": "global", + "definitions": { + "global": { "description": "Shared knowledge" }, + "agent:discord-bot": { "description": "Discord bot private" } + }, + "agentAccess": { + "discord-bot": ["global", "agent:discord-bot"] + } + }, + "sessionMemory": { + "enabled": false, + "messageCount": 15 + }, + "smartExtraction": true, + "llm": { + "apiKey": "${OPENAI_API_KEY}", + "model": "gpt-4o-mini", + "baseURL": "https://api.openai.com/v1" + }, + "extractMinMessages": 2, + "extractMaxChars": 8000 +} +``` + +
+
+
+Провайдеры эмбеддингов
+ +Работает с **любым OpenAI-compatible API для эмбеддингов**: + +| Provider | Model | Base URL | Dimensions | +| --- | --- | --- | --- | +| **Jina** (recommended) | `jina-embeddings-v5-text-small` | `https://api.jina.ai/v1` | 1024 | +| **OpenAI** | `text-embedding-3-small` | `https://api.openai.com/v1` | 1536 | +| **Voyage** | `voyage-4-lite` / `voyage-4` | `https://api.voyageai.com/v1` | 1024 / 1024 | +| **Google Gemini** | `gemini-embedding-001` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 | +| **Ollama** (local) | `nomic-embed-text` | `http://localhost:11434/v1` | зависит от провайдера | + +
+
+
+Провайдеры реранжирования
+ +Кросс-энкодерное реранжирование поддерживает несколько провайдеров через `rerankProvider`: + +| Provider | `rerankProvider` | Example Model | +| --- | --- | --- | +| **Jina** (default) | `jina` | `jina-reranker-v3` | +| **SiliconFlow** (есть бесплатный тариф) | `siliconflow` | `BAAI/bge-reranker-v2-m3` | +| **Voyage AI** | `voyage` | `rerank-2.5` | +| **Pinecone** | `pinecone` | `bge-reranker-v2-m3` | + +Подойдет и любой Jina-compatible rerank endpoint: задайте `rerankProvider: "jina"` и укажите ваш `rerankEndpoint` (например, Hugging Face TEI, DashScope `qwen3-rerank`). + +
+
+
+Smart Extraction (LLM) — v1.1.0
+ +Когда включен `smartExtraction` (по умолчанию: `true`), плагин использует LLM для интеллектуального извлечения и классификации воспоминаний вместо правил на регулярных выражениях. + +| Поле | Тип | По умолчанию | Описание | +|-------|------|---------|-------------| +| `smartExtraction` | boolean | `true` | Включить/выключить извлечение по 6 категориям на базе LLM | +| `llm.auth` | string | `api-key` | `api-key` использует `llm.apiKey` / `embedding.apiKey`; `oauth` по умолчанию использует OAuth-файл токена в области плагина | +| `llm.apiKey` | string | *(по умолчанию берется из `embedding.apiKey`)* | API-ключ провайдера LLM | +| `llm.model` | string | `openai/gpt-oss-120b` | Имя модели LLM | +| `llm.baseURL` | string | *(по умолчанию берется из `embedding.baseURL`)* | URL LLM API | +| `llm.oauthProvider` | string | `openai-codex` | Идентификатор OAuth-провайдера, используемый при `llm.auth = "oauth"` | +| `llm.oauthPath` | string | `~/.openclaw/.memory-lancedb-pro/oauth.json` | Путь к OAuth-файлу токена при `llm.auth = "oauth"` | +| `llm.timeoutMs` | number | `30000` | Таймаут запроса к LLM в миллисекундах | +| `extractMinMessages` | number | `2` | Минимум сообщений до срабатывания извлечения | +| `extractMaxChars` | number | `8000` | Максимум символов, отправляемых в LLM | + + +OAuth `llm` config (использует существующий кэш логина Codex / ChatGPT для LLM-запросов): +```json +{ + "llm": { + "auth": "oauth", + "oauthProvider": "openai-codex", + "model": "gpt-5.4", + "oauthPath": "${HOME}/.openclaw/.memory-lancedb-pro/oauth.json", + "timeoutMs": 30000 + } +} +``` + +Примечания для `llm.auth: "oauth"`: + +- `llm.oauthProvider` сейчас равен `openai-codex`. +- По умолчанию OAuth token хранится в `~/.openclaw/.memory-lancedb-pro/oauth.json`. +- Если хотите хранить этот файл в другом месте, можно задать `llm.oauthPath`. +- `auth login` сохраняет снимок предыдущего `llm` конфига в режиме api-key рядом с OAuth-файлом, а `auth logout` восстанавливает этот снимок, если он доступен. +- При переключении с `api-key` на `oauth` значение `llm.baseURL` автоматически не переносится. Указывайте его вручную в OAuth-режиме только если вам действительно нужен кастомный ChatGPT/Codex-compatible backend. + +
+
+
+Конфигурация жизненного цикла (Decay + Tier)
+ +| Поле | По умолчанию | Описание | +|-------|---------|-------------| +| `decay.recencyHalfLifeDays` | `30` | Базовый период полураспада для Weibull recency decay | +| `decay.frequencyWeight` | `0.3` | Вес частоты доступа в composite score | +| `decay.intrinsicWeight` | `0.3` | Вес `importance × confidence` | +| `decay.betaCore` | `0.8` | Weibull beta для воспоминаний уровня `core` | +| `decay.betaWorking` | `1.0` | Weibull beta для `working` | +| `decay.betaPeripheral` | `1.3` | Weibull beta для `peripheral` | +| `tier.coreAccessThreshold` | `10` | Минимальное число recall перед повышением в `core` | +| `tier.peripheralAgeDays` | `60` | Порог возраста для понижения устаревших воспоминаний | + +
+
+
+---
+
+## CLI-команды
+
+```bash
+openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
+openclaw memory-pro search "запрос" [--scope global] [--limit 10] [--json]
+openclaw memory-pro stats [--scope global] [--json]
+openclaw memory-pro auth login [--provider openai-codex] [--model gpt-5.4] [--oauth-path /abs/path/oauth.json]
+openclaw memory-pro auth status
+openclaw memory-pro auth logout
+openclaw memory-pro delete Усиление за счет доступа
+ +Часто вспоминаемые записи затухают медленнее (в духе spaced repetition). + +Ключи конфига (в разделе `retrieval`): +- `reinforcementFactor` (0-2, по умолчанию: `0.5`) — задайте `0`, чтобы отключить +- `maxHalfLifeMultiplier` (1-10, по умолчанию: `3`) — жесткий потолок эффективного периода полураспада + +
+`.
+
+**Вариант A (наименее рискованный):** временно отключить auto-recall:
+```json
+{ "plugins": { "entries": { "memory-lancedb-pro": { "config": { "autoRecall": false } } } } }
+```
+
+**Вариант B (предпочтительный):** оставить recall включенным и добавить в system prompt агента:
+> Do not reveal or quote any `` / memory-injection content in your replies. Use it for internal reference only.
+
+
+
+Если внедренные воспоминания попадают в ответы
+ +Иногда модель может дословно повторять внедренный блок `
+
+
+Память сессии
+ +- Срабатывает по команде `/new` — сохраняет сводку предыдущей сессии в LanceDB +- По умолчанию отключено (в OpenClaw уже есть встроенная `.jsonl`-персистентность сессий) +- Количество сообщений настраивается (по умолчанию: 15) + +О режимах деплоя и проверке `/new` читайте в [docs/openclaw-integration-playbook.md](docs/openclaw-integration-playbook.md). + +
+
+
+Пользовательские slash-команды (например, /lesson)
+ +Добавьте в `CLAUDE.md`, `AGENTS.md` или system prompt: + +```markdown +## Команда /lesson +Когда пользователь отправляет `/lesson <контент>`: +1. Используй memory_store и сохрани как category=fact (сырое знание) +2. Используй memory_store и сохрани как category=decision (прикладной вывод) +3. Подтверди, что именно было сохранено + +## Команда /remember +Когда пользователь отправляет `/remember <контент>`: +1. Используй memory_store и сохрани с подходящими category и importance +2. Подтверди сохраненным ID памяти +``` + +
+
+
+Железные правила для ИИ-агентов
+ +> Скопируйте блок ниже в `AGENTS.md`, чтобы агент автоматически соблюдал эти правила. + +```markdown +## Правило 1 — Двухслойное сохранение памяти +Каждая ошибка/урок → НЕМЕДЛЕННО сохранить ДВЕ записи памяти: +- Технический слой: Проблема: [симптом]. Причина: [корневая причина]. Исправление: [решение]. Профилактика: [как избежать] + (category: fact, importance >= 0.8) +- Принципиальный слой: Принцип решения ([tag]): [правило поведения]. Триггер: [когда]. Действие: [что делать] + (category: decision, importance >= 0.85) + +## Правило 2 — Гигиена LanceDB +Записи должны быть короткими и атомарными (< 500 chars). Никаких сырых summary разговоров и дубликатов. + +## Правило 3 — Recall перед повторной попыткой +При ЛЮБОЙ ошибке инструмента ВСЕГДА выполняй memory_recall по релевантным ключевым словам ПЕРЕД повторной попыткой. + +## Правило 4 — Подтверди целевую кодовую базу +Перед изменениями убедись, что редактируешь memory-lancedb-pro, а не встроенный memory-lancedb. + +## Правило 5 — Очищай кэш jiti после изменений кода плагина +После изменения .ts-файлов в plugins/ ОБЯЗАТЕЛЬНО выполни rm -rf /tmp/jiti/ перед openclaw gateway restart. +``` + +
+
+
+Схема базы данных
+ +Таблица LanceDB `memories`: + +| Поле | Тип | Описание | +| --- | --- | --- | +| `id` | string (UUID) | Первичный ключ | +| `text` | string | Текст памяти (индексируется для FTS) | +| `vector` | float[] | Вектор эмбеддинга | +| `category` | string | Категория хранения: `preference` / `fact` / `decision` / `entity` / `reflection` / `other` | +| `scope` | string | Идентификатор области памяти (например, `global`, `agent:main`) | +| `importance` | float | Оценка важности от 0 до 1 | +| `timestamp` | int64 | Временная метка создания (мс) | +| `metadata` | string (JSON) | Расширенные метаданные | + +Обычные ключи `metadata` в v1.1.0: `l0_abstract`, `l1_overview`, `l2_content`, `memory_category`, `tier`, `access_count`, `confidence`, `last_accessed_at` + +> **Примечание о категориях:** поле верхнего уровня `category` использует 6 storage categories. Семантические метки Smart Extraction (`profile` / `preferences` / `entities` / `events` / `cases` / `patterns`) сохраняются в `metadata.memory_category`. + +
+
+
+---
+
+## Документация
+
+| Документ | Описание |
+| --- | --- |
+| [OpenClaw Integration Playbook](docs/openclaw-integration-playbook.md) | Режимы деплоя, проверка, матрица регрессии |
+| [Memory Architecture Analysis](docs/memory_architecture_analysis.md) | Глубокий разбор полной архитектуры |
+| [CHANGELOG v1.1.0](docs/CHANGELOG-v1.1.0.md) | Изменения поведения в v1.1.0 и причины апгрейда |
+| [Long-Context Chunking](docs/long-context-chunking.md) | Стратегия разбиения длинных документов |
+
+---
+
+## Бета: Smart Memory v1.1.0
+
+> Статус: Beta — доступно через `npm i memory-lancedb-pro@beta`. Пользователи стабильного `latest` не затронуты.
+
+| Возможность | Описание |
+|---------|-------------|
+| **Умное извлечение** | Извлечение по 6 категориям на базе LLM с метаданными L0/L1/L2. При отключении откатывается к регулярным правилам. |
+| **Оценка жизненного цикла** | Затухание Weibull встроено в поиск по памяти: записи с высокой частотой и важностью ранжируются выше. |
+| **Управление уровнями** | Трехуровневая система (Core → Working → Peripheral) с автоматическим повышением и понижением. |
+
+Обратная связь: [GitHub Issues](https://github.com/CortexReach/memory-lancedb-pro/issues) · Откат: `npm i memory-lancedb-pro@latest`
+
+---
+
+## Зависимости
+
+| Пакет | Назначение |
+| --- | --- |
+| `@lancedb/lancedb` ≥0.26.2 | Векторная база данных (ANN + FTS) |
+| `openai` ≥6.21.0 | Клиент OpenAI-compatible Embedding API |
+| `@sinclair/typebox` 0.34.48 | Определения типов для JSON Schema |
+
+---
+
+## Участники
+
+Устранение неполадок
+ +### "Cannot mix BigInt and other types" (LanceDB / Apache Arrow) + +Начиная с LanceDB 0.26+, некоторые числовые колонки могут возвращаться как `BigInt`. Обновитесь до **memory-lancedb-pro >= 1.0.14**: теперь плагин приводит такие значения через `Number(...)` перед арифметикой. + +
+
+
+# 🧠 memory-lancedb-pro · 🦞OpenClaw Plugin
+
+**[OpenClaw](https://github.com/openclaw/openclaw) 智慧體的 AI 記憶助理**
+
+*讓你的 AI 智慧體擁有真正的記憶力——跨工作階段、跨智慧體、跨時間。*
+
+基於 LanceDB 的 OpenClaw 長期記憶外掛，自動儲存偏好、決策和專案上下文，在後續工作階段中自動回憶。
+
+[](https://github.com/openclaw/openclaw)
+[](https://www.npmjs.com/package/memory-lancedb-pro)
+[](https://lancedb.com)
+[](LICENSE)
+
+[English](README.md) | [简体中文](README_CN.md) | [繁體中文](README_TW.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Français](README_FR.md) | [Español](README_ES.md) | [Deutsch](README_DE.md) | [Italiano](README_IT.md) | [Русский](README_RU.md) | [Português (Brasil)](README_PT-BR.md)
+
+
+
+---
+
+## 為什麼選 memory-lancedb-pro？
+
+大多數 AI 智慧體都有「失憶症」——每次新對話，之前聊過的全部清零。
+
+**memory-lancedb-pro** 是 OpenClaw 的生產級長期記憶外掛，把你的智慧體變成一個真正的 **AI 記憶助理**——自動擷取重要資訊，讓雜訊自然衰減，在恰當的時候回憶起恰當的內容。無需手動標記，無需複雜設定。
+
+### AI 記憶助理實際效果
+
+**沒有記憶——每次都從零開始：**
+
+> **你：** 「縮排用 tab，所有函式都要加錯誤處理。」
+> *（下一次工作階段）*
+> **你：** 「我都說了用 tab 不是空格！」 😤
+> *（再下一次工作階段）*
+> **你：** 「……我真的說了第三遍了，tab，還有錯誤處理。」
+
+**有了 memory-lancedb-pro——你的智慧體學會了、記住了：**
+
+> **你：** 「縮排用 tab，所有函式都要加錯誤處理。」
+> *（下一次工作階段——智慧體自動回憶你的偏好）*
+> **智慧體：** *（默默改成 tab 縮排，並補上錯誤處理）* ✅
+> **你：** 「上個月我們為什麼選了 PostgreSQL 而不是 MongoDB？」
+> **智慧體：** 「根據我們 2 月 12 日的討論，主要原因是……」 ✅
+
+這就是 **AI 記憶助理** 的價值——學習你的風格，回憶過去的決策，提供個人化的回應，不再讓你重複自己。
+
+### 還能做什麼？
+
+| | 你能得到的 |
+|---|---|
+| **自動擷取** | 智慧體從每次對話中學習——不需要手動呼叫 `memory_store` |
+| **智慧擷取** | LLM 驅動的 6 類分類：使用者輪廓、偏好、實體、事件、案例、模式 |
+| **智慧遺忘** | Weibull 衰減模型——重要記憶留存，雜訊自然消退 |
+| **混合檢索** | 向量 + BM25 全文搜尋，融合交叉編碼器重排序 |
+| **上下文注入** | 相關記憶在每次回覆前自動浮現 |
+| **多作用域隔離** | 按智慧體、按使用者、按專案隔離記憶邊界 |
+| **任意服務商** | OpenAI、Jina、Gemini、Ollama 或任意 OpenAI 相容 API |
+| **完整工具鏈** | CLI、備份、遷移、升級、匯入匯出——生產可用 |
+
+---
+
+## 快速開始
+
+### 方式 A：一鍵安裝指令碼（推薦）
+
+社群維護的 **[安裝指令碼](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)** 一條指令搞定安裝、升級和修復：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
+bash setup-memory.sh
+```
+
+> 指令碼涵蓋的完整場景和其他社群工具，詳見下方 [生態工具](#生態工具)。
+
+### 方式 B：手動安裝
+
+**透過 OpenClaw CLI（推薦）：**
+```bash
+openclaw plugins install memory-lancedb-pro@beta
+```
+
+**或透過 npm：**
+```bash
+npm i memory-lancedb-pro@beta
+```
+> 如果用 npm 安裝，你還需要在 `openclaw.json` 的 `plugins.load.paths` 中新增外掛安裝目錄的 **絕對路徑**。這是最常見的安裝問題。
+
+在 `openclaw.json` 中新增設定：
+
+```json
+{
+ "plugins": {
+ "slots": { "memory": "memory-lancedb-pro" },
+ "entries": {
+ "memory-lancedb-pro": {
+ "enabled": true,
+ "config": {
+ "embedding": {
+ "provider": "openai-compatible",
+ "apiKey": "${OPENAI_API_KEY}",
+ "model": "text-embedding-3-small"
+ },
+ "autoCapture": true,
+ "autoRecall": true,
+ "smartExtraction": true,
+ "extractMinMessages": 2,
+ "extractMaxChars": 8000,
+ "sessionMemory": { "enabled": false }
+ }
+ }
+ }
+ }
+}
+```
+
+**為什麼用這些預設值？**
+- `autoCapture` + `smartExtraction` → 智慧體自動從每次對話中學習
+- `autoRecall` → 相關記憶在每次回覆前自動注入
+- `extractMinMessages: 2` → 正常兩輪對話即觸發擷取
+- `sessionMemory.enabled: false` → 避免工作階段摘要在初期汙染檢索結果
+
+驗證並重啟：
+
+```bash
+openclaw config validate
+openclaw gateway restart
+openclaw logs --follow --plain | grep "memory-lancedb-pro"
+```
+
+你應該能看到：
+- `memory-lancedb-pro: smart extraction enabled`
+- `memory-lancedb-pro@...: plugin registered`
+
+完成！你的智慧體現在擁有長期記憶了。
+
+
+
+
+更多安裝路徑（現有使用者、升級）
+ +**已在使用 OpenClaw？** + +1. 在 `plugins.load.paths` 中新增外掛的 **絕對路徑** +2. 繫結記憶插槽：`plugins.slots.memory = "memory-lancedb-pro"` +3. 驗證：`openclaw plugins info memory-lancedb-pro && openclaw memory-pro stats` + +**從 v1.1.0 之前的版本升級？** + +```bash +# 1) 備份 +openclaw memory-pro export --scope global --output memories-backup.json +# 2) 試執行 +openclaw memory-pro upgrade --dry-run +# 3) 執行升級 +openclaw memory-pro upgrade +# 4) 驗證 +openclaw memory-pro stats +``` + +詳見 [`CHANGELOG-v1.1.0.md`](docs/CHANGELOG-v1.1.0.md) 了解行為變更和升級說明。 + +
+
+
+---
+
+## 生態工具
+
+memory-lancedb-pro 是核心外掛。社群圍繞它建構了配套工具，讓安裝和日常使用更加順暢：
+
+### 安裝指令碼——一鍵安裝、升級和修復
+
+> **[CortexReach/toolbox/memory-lancedb-pro-setup](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)**
+
+不只是簡單的安裝器——指令碼能智慧處理各種常見場景：
+
+| 你的情況 | 指令碼會做什麼 |
+|---|---|
+| 從未安裝 | 全新下載 → 安裝依賴 → 選擇設定 → 寫入 openclaw.json → 重啟 |
+| 透過 `git clone` 安裝，卡在舊版本 | 自動 `git fetch` + `checkout` 到最新 → 重裝依賴 → 驗證 |
+| 設定中有無效欄位 | 自動偵測並透過 schema 過濾移除不支援的欄位 |
+| 透過 `npm` 安裝 | 跳過 git 更新，提醒你自行執行 `npm update` |
+| `openclaw` CLI 因無效設定崩潰 | 降級方案：直接從 `openclaw.json` 檔案讀取工作目錄路徑 |
+| `extensions/` 而非 `plugins/` | 從設定或檔案系統自動偵測外掛位置 |
+| 已是最新版 | 僅執行健康檢查，不做變動 |
+
+```bash
+bash setup-memory.sh # 安裝或升級
+bash setup-memory.sh --dry-run # 僅預覽
+bash setup-memory.sh --beta # 包含預發布版本
+bash setup-memory.sh --uninstall # 還原設定並移除外掛
+```
+
+內建服務商預設：**Jina / DashScope / SiliconFlow / OpenAI / Ollama**，或自帶任意 OpenAI 相容 API。完整用法（含 `--ref`、`--selfcheck-only` 等）詳見[安裝指令碼 README](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)。
+
+### Claude Code / OpenClaw Skill——AI 引導式設定
+
+> **[CortexReach/memory-lancedb-pro-skill](https://github.com/CortexReach/memory-lancedb-pro-skill)**
+
+安裝這個 Skill，你的 AI 智慧體（Claude Code 或 OpenClaw）就能深度掌握 memory-lancedb-pro 的所有功能。只需說 **「help me enable the best config」** 即可獲得：
+
+- **7 步引導式設定流程**，提供 4 套部署方案：
+ - 滿血版（Jina + OpenAI）/ 省錢版（免費 SiliconFlow 重排序）/ 簡約版（僅 OpenAI）/ 全本機版（Ollama，零 API 成本）
+- **全部 9 個 MCP 工具** 的正確用法：`memory_recall`、`memory_store`、`memory_forget`、`memory_update`、`memory_stats`、`memory_list`、`self_improvement_log`、`self_improvement_extract_skill`、`self_improvement_review` *（完整工具集需要設定 `enableManagementTools: true`——預設快速設定僅公開 4 個核心工具）*
+- **避開常見陷阱**：workspace 外掛啟用、`autoRecall` 預設 false、jiti 快取、環境變數、作用域隔離等
+
+**Claude Code 安裝：**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro
+```
+
+**OpenClaw 安裝：**
+```bash
+git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill
+```
+
+---
+
+## 影片教學
+
+> 完整演示：安裝、設定、混合檢索內部原理。
+
+[](https://youtu.be/MtukF1C8epQ)
+**https://youtu.be/MtukF1C8epQ**
+
+[](https://www.bilibili.com/video/BV1zUf2BGEgn/)
+**https://www.bilibili.com/video/BV1zUf2BGEgn/**
+
+---
+
+## 架構
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ index.ts (入口) │
+│ 外掛註冊 · 設定解析 · 生命週期鉤子 │
+└────────┬──────────┬──────────┬──────────┬───────────────┘
+ │ │ │ │
+ ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
+ │ store │ │embedder│ │retriever│ │ scopes │
+ │ .ts │ │ .ts │ │ .ts │ │ .ts │
+ └────────┘ └────────┘ └────────┘ └─────────────┘
+ │ │
+ ┌────▼───┐ ┌─────▼──────────┐
+ │migrate │ │noise-filter.ts │
+ │ .ts │ │adaptive- │
+ └────────┘ │retrieval.ts │
+ └────────────────┘
+ ┌─────────────┐ ┌──────────┐
+ │ tools.ts │ │ cli.ts │
+ │ (智慧體 API)│ │ (CLI) │
+ └─────────────┘ └──────────┘
+```
+
+> 完整架構解析見 [docs/memory_architecture_analysis.md](docs/memory_architecture_analysis.md)。
+
+Telegram Bot 快速匯入（點選展開）
+ +如果你在使用 OpenClaw 的 Telegram 整合，最簡單的方式是直接給主 Bot 發訊息，而不是手動編輯設定檔。 + +以下為英文原文，方便直接複製傳送給 Bot： + +```text +Help me connect this memory plugin with the most user-friendly configuration: https://github.com/CortexReach/memory-lancedb-pro + +Requirements: +1. Set it as the only active memory plugin +2. Use Jina for embedding +3. Use Jina for reranker +4. Use gpt-4o-mini for the smart-extraction LLM +5. Enable autoCapture, autoRecall, smartExtraction +6. extractMinMessages=2 +7. sessionMemory.enabled=false +8. captureAssistant=false +9. retrieval mode=hybrid, vectorWeight=0.7, bm25Weight=0.3 +10. rerank=cross-encoder, candidatePoolSize=12, minScore=0.6, hardMinScore=0.62 +11. Generate the final openclaw.json config directly, not just an explanation +``` + +
+
+
+---
+
+## 核心功能
+
+### 混合檢索
+
+```
+查詢 → embedQuery() ─┐
+ ├─→ 混合融合 → 重排序 → 生命週期衰減加權 → 長度正規化 → 過濾
+查詢 → BM25 全文 ─────┘
+```
+
+- **向量搜尋** — 基於 LanceDB ANN 的語意相似度（餘弦距離）
+- **BM25 全文搜尋** — 透過 LanceDB FTS 索引進行精確關鍵字比對
+- **混合融合** — 以向量分數為基礎，BM25 命中結果獲得加權提升（非標準 RRF——針對實際召回品質調優）
+- **可設定權重** — `vectorWeight`、`bm25Weight`、`minScore`
+
+### 交叉編碼器重排序
+
+- 內建 **Jina**、**SiliconFlow**、**Voyage AI** 和 **Pinecone** 適配器
+- 相容任意 Jina 相容端點（如 Hugging Face TEI、DashScope）
+- 混合打分：60% 交叉編碼器 + 40% 原始融合分數
+- 優雅降級：API 失敗時回退到餘弦相似度
+
+### 多階段評分管線
+
+| 階段 | 效果 |
+| --- | --- |
+| **混合融合** | 結合語意召回和精確比對召回 |
+| **交叉編碼器重排序** | 提升語意精確命中的排名 |
+| **生命週期衰減加權** | Weibull 時效性 + 存取頻率 + 重要性 × 置信度 |
+| **長度正規化** | 防止長條目主導結果（錨點：500 字元） |
+| **硬最低分** | 移除無關結果（預設：0.35） |
+| **MMR 多樣性** | 餘弦相似度 > 0.85 → 降權 |
+
+### 智慧記憶擷取（v1.1.0）
+
+- **LLM 驅動的 6 類擷取**：使用者輪廓、偏好、實體、事件、案例、模式
+- **L0/L1/L2 分層儲存**：L0（一句話索引）→ L1（結構化摘要）→ L2（完整敘述）
+- **兩階段去重**：向量相似度預過濾（≥0.7）→ LLM 語意決策（CREATE/MERGE/SKIP）
+- **類別感知合併**：`profile` 始終合併，`events`/`cases` 僅追加
+
+### 記憶生命週期管理（v1.1.0）
+
+- **Weibull 衰減引擎**：綜合分數 = 時效性 + 頻率 + 內在價值
+- **三級晉升**：`外圍 ↔ 工作 ↔ 核心`，閾值可設定
+- **存取強化**：頻繁被召回的記憶衰減更慢（類似間隔重複機制）
+- **重要性調制半衰期**：重要記憶衰減更慢
+
+### 多作用域隔離
+
+- 內建作用域：`global`、`agent:檔案說明（點選展開）
+ +| 檔案 | 用途 | +| --- | --- | +| `index.ts` | 外掛入口，註冊 OpenClaw Plugin API、解析設定、掛載生命週期鉤子 | +| `openclaw.plugin.json` | 外掛中繼資料 + 完整 JSON Schema 設定宣告 | +| `cli.ts` | CLI 指令：`memory-pro list/search/stats/delete/delete-bulk/export/import/reembed/upgrade/migrate` | +| `src/store.ts` | LanceDB 儲存層：建表 / 全文索引 / 向量搜尋 / BM25 搜尋 / CRUD | +| `src/embedder.ts` | Embedding 抽象層，相容任意 OpenAI 相容 API | +| `src/retriever.ts` | 混合檢索引擎：向量 + BM25 → 混合融合 → 重排序 → 生命週期衰減 → 過濾 | +| `src/scopes.ts` | 多作用域存取控制 | +| `src/tools.ts` | 智慧體工具定義：`memory_recall`、`memory_store`、`memory_forget`、`memory_update` + 管理工具 | +| `src/noise-filter.ts` | 過濾智慧體拒絕回覆、元問題、打招呼等低品質內容 | +| `src/adaptive-retrieval.ts` | 判斷查詢是否需要記憶檢索 | +| `src/migrate.ts` | 從內建 `memory-lancedb` 遷移到 Pro | +| `src/smart-extractor.ts` | LLM 驅動的 6 類擷取，支援 L0/L1/L2 分層儲存和兩階段去重 | +| `src/decay-engine.ts` | Weibull 拉伸指數衰減模型 | +| `src/tier-manager.ts` | 三級晉升/降級：外圍 ↔ 工作 ↔ 核心 | + +
+與內建
+
+| 功能 | 內建 `memory-lancedb` | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| 向量搜尋 | 有 | 有 |
+| BM25 全文搜尋 | - | 有 |
+| 混合融合（向量 + BM25） | - | 有 |
+| 交叉編碼器重排序（多服務商） | - | 有 |
+| 時效性提升和時間衰減 | - | 有 |
+| 長度正規化 | - | 有 |
+| MMR 多樣性 | - | 有 |
+| 多作用域隔離 | - | 有 |
+| 雜訊過濾 | - | 有 |
+| 自適應檢索 | - | 有 |
+| 管理 CLI | - | 有 |
+| 工作階段記憶 | - | 有 |
+| 任務感知 Embedding | - | 有 |
+| **LLM 智慧擷取（6 類）** | - | 有（v1.1.0） |
+| **Weibull 衰減 + 層級晉升** | - | 有（v1.1.0） |
+| 任意 OpenAI 相容 Embedding | 有限 | 有 |
+
+
+
+---
+
+## 設定
+
+與內建 memory-lancedb 的對比（點選展開）
+
+| 功能 | 內建 `memory-lancedb` | **memory-lancedb-pro** |
+| --- | :---: | :---: |
+| 向量搜尋 | 有 | 有 |
+| BM25 全文搜尋 | - | 有 |
+| 混合融合（向量 + BM25） | - | 有 |
+| 交叉編碼器重排序（多服務商） | - | 有 |
+| 時效性提升和時間衰減 | - | 有 |
+| 長度正規化 | - | 有 |
+| MMR 多樣性 | - | 有 |
+| 多作用域隔離 | - | 有 |
+| 雜訊過濾 | - | 有 |
+| 自適應檢索 | - | 有 |
+| 管理 CLI | - | 有 |
+| 工作階段記憶 | - | 有 |
+| 任務感知 Embedding | - | 有 |
+| **LLM 智慧擷取（6 類）** | - | 有（v1.1.0） |
+| **Weibull 衰減 + 層級晉升** | - | 有（v1.1.0） |
+| 任意 OpenAI 相容 Embedding | 有限 | 有 |
+
+
+
+
+完整設定範例
+ +```json +{ + "embedding": { + "apiKey": "${JINA_API_KEY}", + "model": "jina-embeddings-v5-text-small", + "baseURL": "https://api.jina.ai/v1", + "dimensions": 1024, + "taskQuery": "retrieval.query", + "taskPassage": "retrieval.passage", + "normalized": true + }, + "dbPath": "~/.openclaw/memory/lancedb-pro", + "autoCapture": true, + "autoRecall": true, + "retrieval": { + "mode": "hybrid", + "vectorWeight": 0.7, + "bm25Weight": 0.3, + "minScore": 0.3, + "rerank": "cross-encoder", + "rerankApiKey": "${JINA_API_KEY}", + "rerankModel": "jina-reranker-v3", + "rerankEndpoint": "https://api.jina.ai/v1/rerank", + "rerankProvider": "jina", + "candidatePoolSize": 20, + "recencyHalfLifeDays": 14, + "recencyWeight": 0.1, + "filterNoise": true, + "lengthNormAnchor": 500, + "hardMinScore": 0.35, + "timeDecayHalfLifeDays": 60, + "reinforcementFactor": 0.5, + "maxHalfLifeMultiplier": 3 + }, + "enableManagementTools": false, + "scopes": { + "default": "global", + "definitions": { + "global": { "description": "Shared knowledge" }, + "agent:discord-bot": { "description": "Discord bot private" } + }, + "agentAccess": { + "discord-bot": ["global", "agent:discord-bot"] + } + }, + "sessionMemory": { + "enabled": false, + "messageCount": 15 + }, + "smartExtraction": true, + "llm": { + "apiKey": "${OPENAI_API_KEY}", + "model": "gpt-4o-mini", + "baseURL": "https://api.openai.com/v1" + }, + "extractMinMessages": 2, + "extractMaxChars": 8000 +} +``` + +
+
+
+Embedding 服務商
+ +相容 **任意 OpenAI 相容 Embedding API**： + +| 服務商 | 模型 | Base URL | 維度 | +| --- | --- | --- | --- | +| **Jina**（推薦） | `jina-embeddings-v5-text-small` | `https://api.jina.ai/v1` | 1024 | +| **OpenAI** | `text-embedding-3-small` | `https://api.openai.com/v1` | 1536 | +| **Voyage** | `voyage-4-lite` / `voyage-4` | `https://api.voyageai.com/v1` | 1024 / 1024 | +| **Google Gemini** | `gemini-embedding-001` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 | +| **Ollama**（本地） | `nomic-embed-text` | `http://localhost:11434/v1` | 取決於模型 | + +
+
+
+重排序服務商
+ +交叉編碼器重排序透過 `rerankProvider` 支援多個服務商： + +| 服務商 | `rerankProvider` | 範例模型 | +| --- | --- | --- | +| **Jina**（預設） | `jina` | `jina-reranker-v3` | +| **SiliconFlow**（有免費額度） | `siliconflow` | `BAAI/bge-reranker-v2-m3` | +| **Voyage AI** | `voyage` | `rerank-2.5` | +| **Pinecone** | `pinecone` | `bge-reranker-v2-m3` | + +任何 Jina 相容的重排序端點也可以使用——設定 `rerankProvider: "jina"` 並將 `rerankEndpoint` 指向你的服務（如 Hugging Face TEI、DashScope `qwen3-rerank`）。 + +
+
+
+智慧擷取（LLM）— v1.1.0
+ +當 `smartExtraction` 啟用（預設 `true`）時，外掛使用 LLM 智慧擷取和分類記憶，取代基於正則的觸發方式。 + +| 欄位 | 類型 | 預設值 | 說明 | +|------|------|--------|------| +| `smartExtraction` | boolean | `true` | 是否啟用 LLM 智慧 6 類別擷取 | +| `llm.auth` | string | `api-key` | `api-key` 使用 `llm.apiKey` / `embedding.apiKey`；`oauth` 預設使用外掛級 OAuth token 檔案 | +| `llm.apiKey` | string | *（複用 `embedding.apiKey`）* | LLM 服務商 API Key | +| `llm.model` | string | `openai/gpt-oss-120b` | LLM 模型名稱 | +| `llm.baseURL` | string | *（複用 `embedding.baseURL`）* | LLM API 端點 | +| `llm.oauthProvider` | string | `openai-codex` | `llm.auth` 為 `oauth` 時使用的 OAuth provider id | +| `llm.oauthPath` | string | `~/.openclaw/.memory-lancedb-pro/oauth.json` | `llm.auth` 為 `oauth` 時使用的 OAuth token 檔案 | +| `llm.timeoutMs` | number | `30000` | LLM 請求逾時（毫秒） | +| `extractMinMessages` | number | `2` | 觸發擷取的最小訊息數 | +| `extractMaxChars` | number | `8000` | 傳送給 LLM 的最大字元數 | + + +OAuth `llm` 設定（使用現有 Codex / ChatGPT 登入快取來發送 LLM 請求）： +```json +{ + "llm": { + "auth": "oauth", + "oauthProvider": "openai-codex", + "model": "gpt-5.4", + "oauthPath": "${HOME}/.openclaw/.memory-lancedb-pro/oauth.json", + "timeoutMs": 30000 + } +} +``` + +`llm.auth: "oauth"` 說明： + +- `llm.oauthProvider` 目前僅支援 `openai-codex`。 +- OAuth token 預設存放在 `~/.openclaw/.memory-lancedb-pro/oauth.json`。 +- 如需自訂路徑，可設定 `llm.oauthPath`。 +- `auth login` 會在 OAuth 檔案旁邊快照原來的 `api-key` 模式 `llm` 設定；`auth logout` 在可用時會恢復這份快照。 +- 從 `api-key` 切到 `oauth` 時不會自動沿用 `llm.baseURL`；只有在你明確需要自訂 ChatGPT/Codex 相容後端時，才應在 `oauth` 模式下手動設定。 + +
+
+
+生命週期設定（衰減 + 層級）
+ +| 欄位 | 預設值 | 說明 | +|------|--------|------| +| `decay.recencyHalfLifeDays` | `30` | Weibull 時效性衰減的基礎半衰期 | +| `decay.frequencyWeight` | `0.3` | 存取頻率在綜合分數中的權重 | +| `decay.intrinsicWeight` | `0.3` | `重要性 × 置信度` 的權重 | +| `decay.betaCore` | `0.8` | `核心` 記憶的 Weibull beta | +| `decay.betaWorking` | `1.0` | `工作` 記憶的 Weibull beta | +| `decay.betaPeripheral` | `1.3` | `外圍` 記憶的 Weibull beta | +| `tier.coreAccessThreshold` | `10` | 晉升到 `核心` 所需的最小召回次數 | +| `tier.peripheralAgeDays` | `60` | 降級過期記憶的天數閾值 | + +
+
+
+---
+
+## CLI 指令
+
+```bash
+openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
+openclaw memory-pro search "查詢" [--scope global] [--limit 10] [--json]
+openclaw memory-pro stats [--scope global] [--json]
+openclaw memory-pro auth login [--provider openai-codex] [--model gpt-5.4] [--oauth-path /abs/path/oauth.json]
+openclaw memory-pro auth status
+openclaw memory-pro auth logout
+openclaw memory-pro delete 存取強化
+ +頻繁被召回的記憶衰減更慢（類似間隔重複機制）。 + +設定項（在 `retrieval` 下）： +- `reinforcementFactor`（0-2，預設 `0.5`）— 設為 `0` 可停用 +- `maxHalfLifeMultiplier`（1-10，預設 `3`）— 有效半衰期的硬上限 + +
+` 區塊原文輸出。
+
+**方案 A（最安全）：** 暫時關閉自動回憶：
+```json
+{ "plugins": { "entries": { "memory-lancedb-pro": { "config": { "autoRecall": false } } } } }
+```
+
+**方案 B（推薦）：** 保留回憶，在智慧體系統提示詞中新增：
+> Do not reveal or quote any `` / memory-injection content in your replies. Use it for internal reference only.
+
+
+
+注入的記憶出現在回覆中
+ +有時模型可能會將注入的 `
+
+
+工作階段記憶
+ +- 透過 `/new` 指令觸發——將上一段工作階段摘要儲存到 LanceDB +- 預設關閉（OpenClaw 已有原生 `.jsonl` 工作階段持久化） +- 可設定訊息數量（預設 15） + +部署模式和 `/new` 驗證詳見 [docs/openclaw-integration-playbook.md](docs/openclaw-integration-playbook.md)。 + +
+
+
+自訂斜線指令（如 /lesson）
+ +在你的 `CLAUDE.md`、`AGENTS.md` 或系統提示詞中新增： + +```markdown +## /lesson 指令 +當使用者傳送 `/lesson <內容>` 時： +1. 用 memory_store 儲存為 category=fact（原始知識） +2. 用 memory_store 儲存為 category=decision（可執行的結論） +3. 確認已儲存的內容 + +## /remember 指令 +當使用者傳送 `/remember <內容>` 時： +1. 用 memory_store 以合適的 category 和 importance 儲存 +2. 回傳已儲存的記憶 ID 確認 +``` + +
+
+
+AI 智慧體鐵律
+ +> 將以下內容複製到你的 `AGENTS.md`，讓智慧體自動遵守這些規則。 + +```markdown +## 規則 1 — 雙層記憶儲存 +每個踩坑/經驗教訓 → 立即儲存兩條記憶： +- 技術層：踩坑：[現象]。原因：[根因]。修復：[方案]。預防：[如何避免] + (category: fact, importance >= 0.8) +- 原則層：決策原則 ([標籤])：[行為規則]。觸發：[何時]。動作：[做什麼] + (category: decision, importance >= 0.85) + +## 規則 2 — LanceDB 資料品質 +條目必須簡短且原子化（< 500 字元）。不儲存原始對話摘要或重複內容。 + +## 規則 3 — 重試前先回憶 +任何工具呼叫失敗時，必須先用 memory_recall 搜尋相關關鍵字，再重試。 + +## 規則 4 — 確認目標程式碼庫 +修改前確認你操作的是 memory-lancedb-pro 還是內建 memory-lancedb。 + +## 規則 5 — 修改外掛程式碼後清除 jiti 快取 +修改 plugins/ 下的 .ts 檔案後，必須先清除 /tmp/jiti/ 目錄再重啟 openclaw gateway。 +``` + +
+
+
+資料庫 Schema
+ +LanceDB 表 `memories`： + +| 欄位 | 類型 | 說明 | +| --- | --- | --- | +| `id` | string (UUID) | 主鍵 | +| `text` | string | 記憶文字（全文索引） | +| `vector` | float[] | Embedding 向量 | +| `category` | string | 儲存類別：`preference` / `fact` / `decision` / `entity` / `reflection` / `other` | +| `scope` | string | 作用域識別碼（如 `global`、`agent:main`） | +| `importance` | float | 重要性分數 0-1 | +| `timestamp` | int64 | 建立時間戳記（毫秒） | +| `metadata` | string (JSON) | 擴充中繼資料 | + +v1.1.0 常用 `metadata` 欄位：`l0_abstract`、`l1_overview`、`l2_content`、`memory_category`、`tier`、`access_count`、`confidence`、`last_accessed_at` + +> **關於分類的說明：** 頂層 `category` 欄位使用 6 個儲存類別。智慧擷取的 6 類語意標籤（`profile` / `preferences` / `entities` / `events` / `cases` / `patterns`）儲存在 `metadata.memory_category` 中。 + +
+
+
+---
+
+## 文件
+
+| 文件 | 說明 |
+| --- | --- |
+| [OpenClaw 整合手冊](docs/openclaw-integration-playbook.md) | 部署模式、驗證、迴歸矩陣 |
+| [記憶架構分析](docs/memory_architecture_analysis.md) | 完整架構深度解析 |
+| [CHANGELOG v1.1.0](docs/CHANGELOG-v1.1.0.md) | v1.1.0 行為變更和升級說明 |
+| [長上下文分塊](docs/long-context-chunking.md) | 長文件分塊策略 |
+
+---
+
+## 測試版：智慧記憶 v1.1.0
+
+> 狀態：Beta（測試版）——透過 `npm i memory-lancedb-pro@beta` 安裝。使用 `latest` 的穩定版使用者不受影響。
+
+| 功能 | 說明 |
+|------|------|
+| **智慧擷取** | LLM 驅動的 6 類擷取，支援 L0/L1/L2 中繼資料。停用時回退到正則模式。 |
+| **生命週期評分** | Weibull 衰減整合到檢索中——高頻和高重要性記憶排名更高。 |
+| **層級管理** | 三級系統（核心 → 工作 → 外圍），自動晉升/降級。 |
+
+回饋：[GitHub Issues](https://github.com/CortexReach/memory-lancedb-pro/issues) · 回退：`npm i memory-lancedb-pro@latest`
+
+---
+
+## 依賴
+
+| 套件 | 用途 |
+| --- | --- |
+| `@lancedb/lancedb` ≥0.26.2 | 向量資料庫（ANN + FTS） |
+| `openai` ≥6.21.0 | OpenAI 相容 Embedding API 客戶端 |
+| `@sinclair/typebox` 0.34.48 | JSON Schema 類型定義 |
+
+---
+
+## Contributors
+
+故障排除
+ +### "Cannot mix BigInt and other types"（LanceDB / Apache Arrow） + +在 LanceDB 0.26+ 上，某些數值欄位可能以 `BigInt` 形式回傳。升級到 **memory-lancedb-pro >= 1.0.14**——外掛現在會在運算前使用 `Number(...)` 進行類型轉換。 + +
+
memory-pro OAuth complete
", + "You can close this window and return to your terminal.
", + "", + ].join(""); +} + +function buildErrorHtml(message: string): string { + return [ + "", + "", + "memory-pro OAuth failed
", + `${message}
`, + "", + ].join(""); +} + +function decodeJwtPayload(token: string): Record