# https://github.com/CortexReach/memory-lancedb-pro Project Manual

Generated at: 2026-06-26 22:04:38 UTC

## Table of Contents

- [Overview, Installation & Plugin Architecture](#page-overview)
- [Storage, Embedding & Hybrid Retrieval](#page-storage-retrieval)
- [Memory Intelligence, Extraction & Lifecycle](#page-intelligence-lifecycle)
- [Operations, CLI, Tooling & Common Failure Modes](#page-operations-failures)

<a id='page-overview'></a>

## Overview, Installation & Plugin Architecture

### Related Pages

Related topics: [Storage, Embedding & Hybrid Retrieval](#page-storage-retrieval), [Memory Intelligence, Extraction & Lifecycle](#page-intelligence-lifecycle), [Operations, CLI, Tooling & Common Failure Modes](#page-operations-failures)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)
- [openclaw.plugin.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/openclaw.plugin.json)
- [index.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/index.ts)
- [README.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/README.md)
- [CHANGELOG-v1.1.0.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/CHANGELOG-v1.1.0.md)
- [src/llm-client.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/llm-client.ts)
- [examples/new-session-distill/README.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/examples/new-session-distill/README.md)
</details>

# Overview, Installation & Plugin Architecture

## 1. Purpose and Scope

`memory-lancedb-pro` is an OpenClaw memory plugin that provides long-term, hybrid retrieval (vector + BM25) with cross-encoder reranking, multi-scope isolation, long-context chunking, and a management CLI. The published description frames it as an "OpenClaw enhanced LanceDB memory plugin" that exposes both typed tools (`memory_recall`, `memory_store`, `memory_forget`) and a CLI surface (`memory-pro stats`, `memory-pro search`) on top of a single LanceDB store at `memories.lance` [Source: [package.json:2-3](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)].

The plugin is loaded by OpenClaw as an **extension**, registers lifecycle hooks for prompt building and post-turn capture, and ships native binaries for every supported Node platform.

## 2. Plugin Manifest and Distribution

The npm package is shipped as an ESM module (`"type": "module"`) with `dist/index.js` as both `main` and the OpenClaw extension entry point [Source: [package.json:4-8](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)]. The OpenClaw discovery block lives in the same `package.json`:

```json
"openclaw": {
  "extensions": ["./dist/index.js"]
}
```

Source: [package.json:27-31](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)

A separate `openclaw.plugin.json` file is published alongside it so OpenClaw can validate the manifest, and `scripts/version` keeps both files synchronized: `node scripts/sync-plugin-version.mjs openclaw.plugin.json package.json && git add openclaw.plugin.json` [Source: [package.json:88-89](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)]. The published file list (`dist/**/*`, `openclaw.plugin.json`, README and CHANGELOG) confirms that the artifact users receive is the compiled output of `src/` [Source: [package.json:15-23](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)].

## 3. Runtime Dependencies and Platform Support

The plugin depends on `@lancedb/lancedb ^0.26.2`, `apache-arrow 18.1.0`, `openai ^6.21.0`, `proper-lockfile ^4.1.2`, `@sinclair/typebox 0.34.48`, and `json5 ^2.2.3` [Source: [package.json:9-15](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)]. Because LanceDB is a native module, per-architecture binaries are listed under `optionalDependencies` for darwin-arm64/x64, linux-arm64-gnu/x64-gnu, and win32-x64-msvc [Source: [package.json:32-39](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)]. An optional `ioredis ^5.11.1` enables the Redis-backed distributed lock proposed for high-concurrency deployments [Source: [package.json:40](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json); [issue #659](https://github.com/CortexReach/memory-lancedb-pro/issues/659)].

## 4. Plugin Architecture

At runtime the plugin splits into four cooperating layers registered from `index.ts`:

```mermaid
flowchart LR
  Host[OpenClaw Host] -->|hooks| Reg[index.ts<br/>registerPlugin]
  Reg --> Tools["Tools:<br/>memory_recall / store / forget"]
  Reg --> Hooks["Hooks:<br/>before_prompt_build / agent_end"]
  Reg --> CLI["CLI:<br/>memory-pro stats / search / import"]
  Tools --> Core["Core<br/>(retriever, extractor, embedder)"]
  Hooks --> Core
  CLI --> Core
  Core --> LLM["LLM client<br/>(src/llm-client.ts)"]
  Core --> LanceDB[("LanceDB<br/>memories.lance")]
  LLM -.uses.-> HostModel["Host model catalog?<br/>see issue #901"]
  LanceDB -.optional.-> RedisLock["Redis distributed lock<br/>see issue #659"]
```

The hook surface is what makes the plugin conversational. The `v1.1.0-beta.10` release migrated the legacy `before_agent_start` hook to `before_prompt_build` with explicit priority ordering (auto-recall=10, invariants=12, derived=15), eliminating OpenClaw 2026.3+ deprecation warnings. Post-turn capture is implemented through the `agent_end` typed hook [Source: [CHANGELOG-v1.1.0.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/CHANGELOG-v1.1.0.md)].

## 5. Installation Paths and Known Failure Modes

The plugin supports two install topologies, and they do not behave identically:

| Topology | Layout | Notes |
|---|---|---|
| **Bundled** | Shipped inside the OpenClaw distribution | All typed hooks including `agent_end` fire reliably. |
| **External** | `~/.openclaw/workspace/plugins/memory-lancedb-pro` | Reported regression where `agent_end` is blocked and data stays in-memory, never flushing to `memories.lance`. Source: [issue #850](https://github.com/CortexReach/memory-lancedb-pro/issues/850). |

Three additional install-time hazards recur in community reports:

- **Dreaming setting ignored.** Selecting "Dreaming" in the OpenClaw config UI has no effect on `memory-lancedb-pro` v1.1.0-beta.10 ([issue #565](https://github.com/CortexReach/memory-lancedb-pro/issues/565)).
- **Dynamic `require()` in ESM.** The v1.1.0-beta.10 tag reintroduced a CommonJS `require()` inside an ESM module, breaking `memory-pro stats`, `memory-pro search`, and the recall/store/forget tools on macOS/Linux ([issue #900](https://github.com/CortexReach/memory-lancedb-pro/issues/900)).
- **Stale shipped `dist/`.** `npm run build` rewrites committed dist files because the shipped builds miss the `process.report.excludeNetwork` hang guard and the rerank `top_n` cap ([issue #890](https://github.com/CortexReach/memory-lancedb-pro/issues/890)).

For gateway operators, the recommended safety net is a non-blocking distillation worker driven by the `command:new` hook. The bundled `examples/new-session-distill` enqueues a small JSON task file when the user types `/new`, then a user-level systemd service runs a Gemini Map-Reduce pass and writes high-signal lessons back via `openclaw memory-pro import` [Source: [examples/new-session-distill/README.md:1-19](https://github.com/CortexReach/memory-lancedb-pro/blob/main/examples/new-session-distill/README.md)]. This decouples persistence from the `agent_end` hook, which is known to be skipped on SIGTERM restarts ([issue #435](https://github.com/CortexReach/memory-lancedb-pro/issues/435)).

## 6. Build, Test, and Verification

`npm run build` compiles `src/` to `dist/` via `tsc -p tsconfig.json` [Source: [package.json:75](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)]. `npm run verify-package-runtime` rebuilds and runs `scripts/verify-package-runtime.mjs`, and `prepack` is wired to that same script so the published artifact is always self-checked [Source: [package.json:76-78](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)]. Tests are grouped into CI slices (`cli-smoke`, `core-regression`, `storage-and-schema`, `llm-clients-and-auth`, `packaging-and-workflow`) via `scripts/run-ci-tests.mjs`, and benchmark harnesses target LoCoMo and LongMemEval under `benchmark/run.ts` [Source: [package.json:67-85](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)].

## See Also

- Hybrid Retrieval, Rerank & Long-Context Chunking
- Multi-Scope Isolation and Cross-Process Locking
- Reflection Pipeline and Lifecycle Hooks
- LLM Client, Tool Surface, and CLI Reference

---

<a id='page-storage-retrieval'></a>

## Storage, Embedding & Hybrid Retrieval

### Related Pages

Related topics: [Overview, Installation & Plugin Architecture](#page-overview), [Memory Intelligence, Extraction & Lifecycle](#page-intelligence-lifecycle), [Operations, CLI, Tooling & Common Failure Modes](#page-operations-failures)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/store.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/store.ts)
- [src/embedder.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/embedder.ts)
- [src/retriever.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/retriever.ts)
- [src/scopes.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/scopes.ts)
- [src/identity-addressing.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/identity-addressing.ts)
- [src/adaptive-retrieval.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/adaptive-retrieval.ts)
- [package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)
</details>

# Storage, Embedding & Hybrid Retrieval

## Overview

`memory-lancedb-pro` (v1.1.0-beta.11) is an OpenClaw memory plugin whose retrieval pipeline is built on three cooperating layers: a LanceDB storage layer, an OpenAI-compatible embedding client, and a hybrid retriever that fuses vector search with BM25 lexical scoring, optionally reranked by a cross-encoder model. The combination allows the plugin to recall memories by semantic similarity, exact keyword match, and refined relevance ranking, while keeping per-agent and per-session data strictly isolated through a scope-addressing layer.

Source: [package.json:1-30]()

## LanceDB Storage Layer

The storage layer wraps the `@lancedb/lancedb` JavaScript client (v0.26.2) and the `apache-arrow` (v18.1.0) table format, exposing a narrow API for opening tables, appending records, querying by vector, and performing filtered scans. Persistence is file-based: a single `memories.lance` directory holds one or more Lance tables whose rows represent memory items.

Key responsibilities of `src/store.ts`:

- **Table lifecycle** — Open or create Lance tables on plugin registration; lazily initialize schema when the directory is empty.
- **Schema management** — Define typed columns (id, text, vector, scope, metadata, timestamps) consistent with the Arrow schema expected by Lance.
- **Atomic writes** — Bulk inserts go through a transactional path so partial failures do not corrupt the table.
- **Cross-process locking** — `proper-lockfile` (v4.1.2) serializes concurrent writers from multiple agent processes; community issue #659 proposes a Redis-backed alternative for high-concurrency hosts but the default remains file-based.

Scope isolation is implemented in `src/scopes.ts`. Each memory record carries a `scope` field composed of an agent id, session id, and optional team id. Queries always pass a scope predicate so that one agent can never read another agent's memories. Identity helpers in `src/identity-addressing.ts` resolve symbolic address tokens (e.g., `agent:alpha`, `team:dev`) into canonical scope strings before they reach the store.

Source: [src/store.ts:1-40](), [src/scopes.ts:1-30](), [src/identity-addressing.ts:1-25](), [package.json:60-70]()

## Embedding Pipeline

`src/embedder.ts` produces dense vector representations for both stored text and incoming queries. The module is intentionally OpenAI-protocol-compatible and accepts a configurable `baseURL`, which lets it target OpenRouter, Azure OpenAI, or any drop-in proxy.

The embedder:

- Validates that `embedding.apiKey` is present (either inline or via `OPENAI_API_KEY`) and throws an explicit error otherwise.
- Respects a maximum input length (`embedder-max-input-chars`) to avoid 400 errors on large chunks.
- Splits long inputs into overlapping chunks before encoding when `chunking.enabled` is true.
- Returns 1536-dimensional vectors by default for `text-embedding-3-small`, but the dimension is inferred dynamically from the upstream response.

A known limitation surfaced in community issue #901 is that the LLM completion lane inside the same plugin builds a minimal request in `src/llm-client.ts` and posts directly to `llm.baseURL`, bypassing the host's model catalog. The embedder itself does not have this issue because it is only invoked with a single embedding model name. Operators using OpenRouter-style routing for chat completions should be aware that the two lanes are independent.

Source: [src/embedder.ts:1-50]()

## Hybrid Retrieval

`src/retriever.ts` is the runtime entry point for every memory lookup triggered by the `memory_recall` tool or the auto-recall hook. It performs a three-stage pipeline: candidate generation by vector + BM25, optional cross-encoder rerank, and scope-filtered output. The end-to-end flow is shown below.

```mermaid
flowchart LR
  Q[User Query] --> A[Adaptive Gate]
  A -- "short / command" --> S[Skip]
  A -- "normal" --> V[Vector Search]
  A -- "normal" --> B[BM25 Search]
  V --> F[Fuse top-N]
  B --> F
  F --> R{Rerank enabled?}
  R -- yes --> X[Cross-Encoder Rerank]
  R -- no  --> O[Scope Filter & Output]
  X --> O
  O --> M[Memory Items]
```

**Stage 1 — Candidate generation.** Vector and BM25 searches run in parallel against the same scope predicate. The vector branch uses the embedding produced by `src/embedder.ts`; the BM25 branch uses an in-memory inverted index built from the current table snapshot. Each branch returns its top-k candidates.

**Stage 2 — Fusion.** The two candidate lists are merged using reciprocal-rank fusion (RRF). RRF is preferred over score normalization because BM25 and cosine scores live on incompatible scales.

**Stage 3 — Rerank (optional).** When `rerank.enabled` is true, the fused list is sent to a cross-encoder endpoint and the top-n are re-ordered. Community issue #890 flagged a regression where the rerank top-n cap was missing from shipped `dist/` builds, causing oversized payloads; operators on the published package should rebuild from source or upgrade past the fix.

**Adaptive gating.** `src/adaptive-retrieval.ts` wraps the retriever with a cheap pre-check. Trivial messages (single-word commands, system acknowledgements) bypass the network round-trip entirely. This is the mechanism that v1.1.0-beta.10 fixed for short-message false negatives.

Source: [src/retriever.ts:1-80](), [src/adaptive-retrieval.ts:1-45](), [package.json:55-75]()

## Known Failure Modes

| Symptom | Root Cause | Reference |
|---|---|---|
| `Dynamic require not supported` on macOS/Linux | ESM/CJS interop regression in v1.1.0-beta.10 | Issue #900 |
| Backup `TypeError [ERR_INVALID_ARG_TYPE]` | `api.resolvePath` semantics changed in OpenClaw 2026.4.29 | Issue #731 |
| Bulk-store tests fail in CI | `bulkStore` refactor in PR #669 changed return contract | Issue #679 |
| Duplicate memories accumulate | No similarity-based dedup before insert | Issue #30 |

When debugging retrieval quality, first verify that the embedder dimension matches the table schema; a mismatch between stored vector size and query vector size is the most common silent failure mode.

## See Also

- Hook lifecycle and `before_prompt_build` migration (v1.1.0-beta.10)
- Reflection pipeline and resolution mechanism (Issue #447)
- CLI commands (`memory-pro stats`, `memory-pro search`, `memory-pro import`)
- New Session Distillation example ([examples/new-session-distill/README.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/examples/new-session-distill/README.md))

---

<a id='page-intelligence-lifecycle'></a>

## Memory Intelligence, Extraction & Lifecycle

### Related Pages

Related topics: [Overview, Installation & Plugin Architecture](#page-overview), [Storage, Embedding & Hybrid Retrieval](#page-storage-retrieval), [Operations, CLI, Tooling & Common Failure Modes](#page-operations-failures)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/smart-extractor.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/smart-extractor.ts)
- [src/extraction-prompts.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/extraction-prompts.ts)
- [src/decay-engine.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/decay-engine.ts)
- [src/tier-manager.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/tier-manager.ts)
- [src/reflection-store.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/reflection-store.ts)
- [src/reflection-event-store.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/reflection-event-store.ts)
- [src/llm-client.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/llm-client.ts)
- [src/bulk-store.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/bulk-store.ts)
- [examples/new-session-distill/README.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/examples/new-session-distill/README.md)
- [package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)
</details>

# Memory Intelligence, Extraction & Lifecycle

## Overview

`memory-lancedb-pro` is an OpenClaw memory plugin that turns agent conversations into long-term, queryable knowledge. Beyond raw storage, it ships a full **intelligence pipeline** that decides *what* to write, *how long* it lives, and *when* it should re-surface. This page documents that pipeline: smart extraction, reflection, tiering, and decay.

The lifecycle runs end-to-end inside a single conversation:

1. The hook layer (`agent_end`, `before_prompt_build`) buffers raw text.
2. `smart-extractor.ts` filters the buffer through LLM prompts defined in `extraction-prompts.ts`.
3. Surviving candidates are normalized, deduped (see issue [#30](https://github.com/CortexReach/memory-lancedb-pro/issues/30)), and bulk-written by `bulk-store.ts`.
4. `tier-manager.ts` assigns a tier; `decay-engine.ts` schedules expiration.
5. `reflection-store.ts` / `reflection-event-store.ts` track derived "lessons" that are re-injected on future sessions.

Source: [package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)

## Smart Extractor

The extractor (`src/smart-extractor.ts`) is the gatekeeper. It receives the conversation buffer, applies scope filters (`smart-extractor-scope-filter.test.mjs`), and asks the LLM — via `src/llm-client.ts` — to identify stable, re-usable facts. The prompt contract lives in `extraction-prompts.ts`, which encodes rules such as "ignore transient greetings" and "prefer user-stated preferences over inferred ones."

Two structural details are worth noting:

- **Scope isolation.** The extractor only operates on rows whose `scope` matches the active agent. This is the regression tested by `test/smart-extractor-scope-filter.test.mjs` and is critical when multiple OpenClaw agents share one LanceDB directory.
- **Bulk write refactor.** PR #669 replaced per-row inserts with a single `bulkStore()` call (`src/bulk-store.ts`). The refactor broke branch coverage in `test/smart-extractor-branches.mjs` (issue [#679](https://github.com/CortexReach/memory-lancedb-pro/issues/679)), which is why that test has been flaky on CI since the change.

Community caveat: the extractor's LLM lane builds its own OpenAI-compatible client (see issue [#901](https://github.com/CortexReach/memory-lancedb-pro/issues/901)). It posts directly to `llm.baseURL`, so provider-routing features such as OpenRouter fallback configured at the host level are *not* honored.

Source: [src/smart-extractor.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/smart-extractor.ts), [src/extraction-prompts.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/extraction-prompts.ts), [src/bulk-store.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/bulk-store.ts)

## Reflection, Tiering & Decay

After extraction, memories enter the lifecycle managed by three cooperating modules:

| Module | Responsibility |
| --- | --- |
| `src/tier-manager.ts` | Assigns tiers (e.g., `preference`, `fact`, `invariant`) and embeds tier rules into metadata. |
| `src/decay-engine.ts` | Computes `expiresAt` based on tier + access counts; sweeps expired rows on a schedule. |
| `src/reflection-store.ts` / `src/reflection-event-store.ts` | Stores derived "reflection" lessons and the events that produced them, so they can be re-injected on future sessions. |

### Known reflection pathologies

The reflection pipeline is **unidirectional**: `extract → store → decay → inject`. There is no resolve/invalidate path — once a reflection item is written, it surfaces in every new session until `maxAgeDays` expires (default **45 days** for invariants). This is tracked in issue [#447](https://github.com/CortexReach/memory-lancedb-pro/issues/447).

A second pathology, issue [#382](https://github.com/CortexReach/memory-lancedb-pro/issues/382), is the *self-trigger loop*: after a session's reflections are injected, the extractor treats them as fresh input and can emit 3–4 near-duplicate reflections for the same session. Until the loop is closed upstream, operators are advised to keep `memory-reflection.maxAgeDays` low and to review reflection growth via the CLI.

A community-requested feature, "Dreaming" (issue [#565](https://github.com/CortexReach/memory-lancedb-pro/issues/565)), is **not** supported by `memory-lancedb-pro` — the plugin does not expose a dreaming toggle in the OpenClaw config UI as of v1.1.0-beta.11.

```mermaid
flowchart LR
  A[Conversation Buffer] --> B[smart-extractor.ts]
  B --> C{Scope Filter}
  C -- match --> D[LLM Prompts]
  D --> E[bulk-store.ts]
  E --> F[tier-manager.ts]
  F --> G[(LanceDB)]
  G --> H[decay-engine.ts]
  G --> I[reflection-store.ts]
  I --> J[Next Session Inject]
  J -. self-trigger .-> B
```

Source: [src/tier-manager.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/tier-manager.ts), [src/decay-engine.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/decay-engine.ts), [src/reflection-store.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/reflection-store.ts), [src/reflection-event-store.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/src/reflection-event-store.ts)

## Operational Guidance

- **Cold-start distillation.** The `examples/new-session-distill/` recipe pairs `command:new` with a systemd worker that runs Map-Reduce over the session JSONL, then imports atomic lessons via `openclaw memory-pro import`. This avoids blocking `/new` on a synchronous LLM call inside the plugin ([examples/new-session-distill/README.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/examples/new-session-distill/README.md)).
- **Reflection hygiene.** Because reflection items have no resolve path, periodically prune them with the CLI or by lowering `maxAgeDays` for the `invariant` tier.
- **Dedup before store.** Issue [#30](https://github.com/CortexReach/memory-lancedb-pro/issues/30) requests similarity-based dedup inside `memory_store`; until merged, callers should pre-filter near-duplicate candidates when ingesting large corpora.
- **Concurrency.** Under high concurrent writes, `proper-lockfile` is the default; issue [#659](https://github.com/CortexReach/memory-lancedb-pro/issues/659) proposes a Redis-backed lock for multi-process hosts.

## See Also

- Hook lifecycle & CLI surface (companion wiki page)
- LanceDB storage schema & backup (`runBackup()`)
- LLM client configuration & provider routing caveats (issue [#901](https://github.com/CortexReach/memory-lancedb-pro/issues/901))

---

<a id='page-operations-failures'></a>

## Operations, CLI, Tooling & Common Failure Modes

### Related Pages

Related topics: [Overview, Installation & Plugin Architecture](#page-overview), [Storage, Embedding & Hybrid Retrieval](#page-storage-retrieval), [Memory Intelligence, Extraction & Lifecycle](#page-intelligence-lifecycle)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)
- [examples/new-session-distill/README.md](https://github.com/CortexReach/memory-lancedb-pro/blob/main/examples/new-session-distill/README.md)
- [scripts/run-ci-tests.mjs](https://github.com/CortexReach/memory-lancedb-pro/blob/main/scripts/run-ci-tests.mjs)
- [scripts/verify-package-runtime.mjs](https://github.com/CortexReach/memory-lancedb-pro/blob/main/scripts/verify-package-runtime.mjs)
- [scripts/sync-plugin-version.mjs](https://github.com/CortexReach/memory-lancedb-pro/blob/main/scripts/sync-plugin-version.mjs)
- [scripts/verify-ci-test-manifest.mjs](https://github.com/CortexReach/memory-lancedb-pro/blob/main/scripts/verify-ci-test-manifest.mjs)
- [benchmark/run.ts](https://github.com/CortexReach/memory-lancedb-pro/blob/main/benchmark/run.ts)
- [test/cli-smoke.mjs](https://github.com/CortexReach/memory-lancedb-pro/blob/main/test/cli-smoke.mjs)
- [test/openclaw-host-functional.mjs](https://github.com/CortexReach/memory-lancedb-pro/blob/main/test/openclaw-host-functional.mjs)
</details>

# Operations, CLI, Tooling & Common Failure Modes

`memory-lancedb-pro` ships as an OpenClaw extension whose day‑to‑day operation is exercised through three layers: the runtime plugin entry (`dist/index.js`), a CLI surface (the `memory-pro` family of commands and auxiliary `scripts/*.mjs` helpers), and a TypeScript build pipeline. The `package.json` `"scripts"` block is the authoritative map of every operator‑facing entry point — `npm test`, the grouped CI runners, the `verify-package-runtime` gate, and the benchmark drivers all live there.

## CLI & Management Tooling

The plugin's CLI is exposed to operators as `memory-pro …` subcommands (e.g. `memory-pro stats`, `memory-pro search`, `memory-pro import`), and as tool calls (`memory_recall`, `memory_store`, `memory_forget`) inside an OpenClaw session. The CLI is registered from the bundled entry declared in [package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json) at `openclaw.extensions: "./dist/index.js"`. A CLI smoke pass is runnable in isolation via `npm run test:cli-smoke`, which delegates to [scripts/run-ci-tests.mjs](https://github.com/CortexReach/memory-lancedb-pro/blob/main/scripts/run-ci-tests.mjs) under the `--group cli-smoke` flag. Companion suites are grouped into `core-regression`, `storage-and-schema`, `llm-clients-and-auth`, and `packaging-and-workflow`, and the manifest consistency between those groups and the npm scripts is enforced by [scripts/verify-ci-test-manifest.mjs](https://github.com/CortexReach/memory-lancedb-pro/blob/main/scripts/verify-ci-test-manifest.mjs).

Two example artifacts round out the operator workflow:

- `examples/new-session-distill/README.md` documents a **non‑blocking** `/new` distillation pipeline (systemd worker + JSONL inbox + `openclaw memory-pro import`) that is recommended over blocking in‑hook extraction.
- `benchmark/run.ts` provides the `npm run bench`, `bench:locomo`, and `bench:longmemeval` drivers, used to compare retrieval quality after configuration changes.

## Build, Verify & Release Operations

The release pipeline is codified in [package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json):

| Script | Purpose |
| --- | --- |
| `npm run build` | `tsc -p tsconfig.json` — TypeScript compile to `dist/` |
| `npm run verify-package-runtime` | Build + runtime smoke (calls [scripts/verify-package-runtime.mjs](https://github.com/CortexReach/memory-lancedb-pro/blob/main/scripts/verify-package-runtime.mjs)) |
| `npm run prepack` | Runs `verify-package-runtime` before publishing |
| `npm run version` | Invokes [scripts/sync-plugin-version.mjs](https://github.com/CortexReach/memory-lancedb-pro/blob/main/scripts/sync-plugin-version.mjs) to keep `openclaw.plugin.json` aligned with `package.json` and stages the manifest for commit |

The bundled `dist/**/*` plus `openclaw.plugin.json`, README, CHANGELOG, `docs/**/*.md`, and `skills/**/*.md` are the only artifacts included in the published tarball (`package.json` `"files"`). Operators reproducing CI locally should run `npm ci && npm run build && npm run verify-package-runtime` end‑to‑end.

## Common Failure Modes

Operational history on the `master` and `v1.1.0-beta.10` lines surfaces a recurring set of failure shapes that operators should recognise and preempt:

**1. ESM/CJS interop regression on macOS/Linux.** A CommonJS `require()` call reintroduced into an ESM module breaks `memory-pro stats`, `memory-pro search`, and every `memory_recall/store/forget` tool call on macOS/Linux because dynamic `require()` is not supported in pure ESM contexts. Symptom: `Dynamic require not supported`. Mitigation: track the post‑`v1.1.0-beta.10` fix and run [test/cli-smoke.mjs](https://github.com/CortexReach/memory-lancedb-pro/blob/main/test/cli-smoke.mjs) before deploying.

**2. Stale committed `dist`.** Rebuilding from a clean checkout mutates committed dist files; shipped binaries miss runtime guards such as the `process.report.excludeNetwork` hang guard and the rerank `top_n` cap. Operators should treat `npm run build` as mandatory after every pull and never trust a dist artifact older than the corresponding `src/` commit.

**3. `agent_end` never fires.** When the OpenClaw gateway receives `SIGTERM`, the `agent_end` typed hook does not run for active sessions, so conversation data buffered in memory is **lost on restart**. Additionally, when the plugin is installed as an **external (non‑bundled)** extension under `~/.openclaw/workspace/plugins/memory-lancedb-pro`, `agent_end` is blocked entirely, leaving writes stuck in RAM until the gateway shuts down gracefully. Mitigations reported in the issue tracker include adopting the `/new` distillation example, which decouples persistence from `agent_end` by writing JSONL and running an out‑of‑band importer.

**4. Backup crash on `runBackup()`.** On OpenClaw `2026.4.29`, `runBackup()` fails with `TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string or an instance of Buffer or URL. Received undefined`. The cause is a double‑invocation of `api.resolvePath` returning `undefined` on the second call, after which `mkdir` receives `undefined`. Pinning OpenClaw or guarding `mkdir(undefined)` upstream is the recommended workaround.

**5. LLM completion lane bypasses the host model catalog.** `createApiKeyClient` in `src/llm-client.ts` builds a minimal OpenAI chat‑completions payload and POSTs directly to the configured `llm.baseURL`, which means provider routing configured on the host (OpenRouter, fallbacks, aliases) is ignored. Operators who rely on OpenRouter routing must route the lane through the host catalog or run a transparent proxy.

**6. Lock contention under high concurrency.** When `captureAssistant=true` and `sessionMemory.enabled=true`, simultaneous agent calls contend on a file lock and can stall. The tracked proposal replaces the file lock with a Redis distributed lock (`ioredis` is an optional dependency in [package.json](https://github.com/CortexReach/memory-lancedb-pro/blob/main/package.json)). [test/cross-process-lock.test.mjs](https://github.com/CortexReach/memory-lancedb-pro/blob/main/test/cross-process-lock.test.mjs) exercises the new path.

**7. Dreaming settings are not wired.** Toggling the OpenClaw "Dreaming" toggle has no effect — `memory-lancedb-pro` does not consume that setting.

**8. Reflection self‑trigger loop.** The reflection pipeline can emit near‑identical reflection items for the same session because there is no resolve → invalidate → suppress path; items persist until `maxAgeDays` (default 45 for invariants) naturally expires.

**9. CI breakages from refactors.** PR #669's `bulkStore` refactor regressed `test/smart-extractor-branches.mjs` at line 497, taking the `core-regression` group red. Run [scripts/run-ci-tests.mjs](https://github.com/CortexReach/memory-lancedb-pro/blob/main/scripts/run-ci-tests.mjs) `--group core-regression` locally before pushing.

**10. Verbose logging in CLI mode.** Dual‑memory hints and rerank cost advisories bypass the existing `isCliMode() ? debug : info` convention and repeat on every registration/CLI invocation; route them through the same helper before shipping.

## Operator Playbook

1. `npm ci && npm run verify-package-runtime` — confirms build + runtime match the published behavior.
2. `npm run test:cli-smoke` — fast loop that exercises `memory-pro …` commands.
3. `npm run test:openclaw-host` — runs [test/openclaw-host-functional.mjs](https://github.com/CortexReach/memory-lancedb-pro/blob/main/test/openclaw-host-functional.mjs) against a live OpenClaw host.
4. `npm run bench:locomo` / `bench:longmemeval` — regression‑aware quality checks after any retrieval change.
5. For session durability, prefer the `examples/new-session-distill/` worker over relying on `agent_end`.
6. Audit stale `dist/` and ESM/CJS hygiene after every release; rebuild before deploying.

## See Also

- Architecture & Hybrid Retrieval
- Reflection Pipeline & Lifecycle
- Hook Migration Guide (OpenClaw 2026.3+)
- Backup, Restore & Disaster Recovery

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: CortexReach/memory-lancedb-pro

Summary: Found 18 structured pitfall item(s), including 9 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/435

## 2. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/813

## 3. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/679

## 4. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/900

## 5. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/565

## 6. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/447

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/382

## 8. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/901

## 9. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/850

## 10. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/890

## 11. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/CortexReach/memory-lancedb-pro

## 12. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/CortexReach/memory-lancedb-pro

## 13. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/CortexReach/memory-lancedb-pro

## 14. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/CortexReach/memory-lancedb-pro

## 15. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/888

## 16. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/CortexReach/memory-lancedb-pro/issues/659

## 17. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/CortexReach/memory-lancedb-pro

## 18. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/CortexReach/memory-lancedb-pro

<!-- canonical_name: CortexReach/memory-lancedb-pro; human_manual_source: deepwiki_human_wiki -->