Plugin Memory Lancedb

README

# memory-lancedb-ttt

TTT's custom OpenClaw memory plugin — LanceDB-backed semantic memory + fleet reindex + nightly
"dreaming" consolidation, with per-agent isolation.

Install into your OpenClaw extensions directory (`~/.openclaw/extensions/memory-lancedb/`) and load
it as a plugin. Built for local/self-hosted embedding endpoints (OpenAI-compatible).

## Layout
- `index.ts` — the plugin (tools, reindex, dreaming, search). Imports `./config.js` (built from `config.ts`).
- `config.ts` — config schema + `vectorDimsForModel` etc.
- `openclaw.plugin.json`, `package.json`, `tsconfig.json`, `openclaw-plugin-sdk.d.ts` — plugin manifest/types.
- `dist/` (gitignored) — esbuild bundle the gateway actually loads.
- `node_modules/` (gitignored).

## Build & load
No build script in `package.json` (tsconfig is `noEmit`); `dist` is an esbuild bundle:
```bash
cd ~/.openclaw/extensions/memory-lancedb
esbuild index.ts --bundle --packages=external --format=esm --platform=node --target=es2022 \
  --outfile=dist/index.js
# gated gateway restart to load:
systemctl --user restart openclaw-gateway.service
```

## Serving dependencies
- **Embeddings**: local `Qwen3-Embedding-0.6B` via vLLM on `:8081`, **1024-dim**. The model is **not
  matryoshka** → `embed()` must NOT send the `dimensions` request param (HTTP 400). Table dim is set
  from `config.embedding.dimensions` independently.
- Config: `plugins.entries.memory-lancedb-ttt.config.embedding` (model/baseUrl/dimensions/apiKey).

## Key design notes / fixes (2026-06-24 → 26)
- **Reindex resolves ALL workspaces** via `resolveAllWorkspaceEntries` (was `api.resolvePath`→undefined→0 files).
- **O(1) reindex scan**: preload all `chunk_hash`es into a Set once + batched `table.add()`, bypassing the
  per-chunk DB existence query AND `store()`'s near-dedup vector search — those made a full reindex exceed
  the gateway's ~390 s stuck-session watchdog (`abort_embedded_run`). `await db.ensureInitialized()` before
  direct table access (table is lazy-init).
- **Silent-failure guard**: reindex throws if `embedFailures > 0 && chunks == 0` (embedder down) → cron run
  errors + pages, instead of a misleading "Reindexed: 0 chunks … ok".
- **`search()` fails closed**: returns `[]` when `agentId` is missing (was fail-open to the global index).
- **Per-agent isolation is by QUERY** (`agent_id = '<caller>' OR scope != ''`), not by index membership;
  reindexed chunks are `scope=""` so each agent only sees its own. Sensitive agents are still indexed (safe);
  `canCrossPollinate` only governs dreaming cross-pollination.