seekx-openclaw 0.3.0

package/openclaw.plugin.json

@@ -0,0 +1,86 @@
+{
+  "id": "seekx",
+  "name": "seekx",
+  "description": "Local-first hybrid search memory backend: BM25 + vector + rerank + CJK",
+  "version": "0.1.0",
+  "kind": "memory",
+  "skills": ["skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "dbPath": {
+        "type": "string"
+      },
+      "paths": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["name", "path"],
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string"
+            },
+            "pattern": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "apiKey": {
+        "type": "string"
+      },
+      "baseUrl": {
+        "type": "string"
+      },
+      "embedModel": {
+        "type": "string"
+      },
+      "rerankModel": {
+        "type": "string"
+      },
+      "expandModel": {
+        "type": "string"
+      },
+      "searchLimit": {
+        "type": "number"
+      },
+      "refreshIntervalMs": {
+        "type": "number"
+      },
+      "includeOpenClawMemory": {
+        "type": "boolean"
+      }
+    }
+  },
+  "uiHints": {
+    "apiKey": {
+      "label": "API key",
+      "sensitive": true,
+      "help": "API key for embedding/reranking/expansion. Inherits from ~/.seekx/config.yml if unset."
+    },
+    "baseUrl": {
+      "label": "API base URL",
+      "placeholder": "https://api.siliconflow.cn/v1",
+      "help": "OpenAI-compatible API base URL."
+    },
+    "embedModel": {
+      "label": "Embedding model",
+      "placeholder": "BAAI/bge-large-zh-v1.5"
+    },
+    "rerankModel": {
+      "label": "Reranking model",
+      "placeholder": "BAAI/bge-reranker-v2-m3",
+      "help": "Omit to disable reranking."
+    },
+    "expandModel": {
+      "label": "Query expansion model",
+      "placeholder": "Qwen/Qwen3-8B",
+      "help": "Omit to disable query expansion."
+    }
+  }
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "seekx-openclaw",
+  "version": "0.3.0",
+  "description": "OpenClaw memory backend: hybrid BM25 + vector search with reranking and CJK support",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": { ".": "./src/index.ts" },
+  "files": ["src", "skills", "openclaw.plugin.json"],
+  "openclaw": {
+    "extensions": ["./src/index.ts"],
+    "install": { "minHostVersion": ">=2026.4.0" }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test test/"
+  },
+  "dependencies": {
+    "seekx-core": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=22",
+    "bun": ">=1.1.0"
+  }
+}

package/skills/install/SKILL.md

@@ -0,0 +1,346 @@
+# Skill: Install seekx memory backend for OpenClaw
+
+> **This skill is self-contained and agent-executable.**
+> It can be fetched from a public URL and run by any capable agent
+> (Cursor, Claude Desktop, OpenClaw agent, etc.) — even before the plugin
+> is installed.
+>
+> How to invoke: tell your agent:
+> "Fetch and follow this skill: https://raw.githubusercontent.com/seekx/seekx/main/packages/openclaw-plugin/skills/install/SKILL.md"
+
+---
+
+## What this skill does
+
+Installs the `seekx-openclaw` plugin into the user's OpenClaw gateway,
+configures an embedding/reranking provider, and verifies the setup end-to-end.
+
+After completion:
+- `memory_search` and `memory_get` route through seekx's search pipeline
+- OpenClaw's memory files are indexed automatically
+- Any extra directories the user specified are indexed and watched
+- Vector search, reranking, and query expansion are enabled only when the
+  necessary models and runtime support are available; otherwise seekx
+  degrades safely to BM25-only mode
+
+---
+
+## Execution steps
+
+Work through the steps below **in order**. At each step, run the command or
+collect the answer before proceeding to the next.
+
+---
+
+### Step 1 — Verify OpenClaw is installed
+
+```bash
+openclaw --version
+```
+
+If the command is not found, tell the user:
+
+> OpenClaw is not installed. Install it first:
+> `npm install -g openclaw@latest`
+> Then re-run this skill.
+
+Stop here if OpenClaw is not present.
+
+---
+
+### Step 2 — Install the seekx plugin
+
+```bash
+openclaw plugins install seekx-openclaw
+```
+
+If this fails with a "not found" error, try the npm fallback:
+
+```bash
+npm install -g seekx-openclaw
+```
+
+Then register it as a local plugin:
+
+```bash
+openclaw plugins install -l "$(npm root -g)/seekx-openclaw"
+```
+
+Confirm it loaded:
+
+```bash
+openclaw plugins list | grep seekx
+```
+
+---
+
+### Step 3 — Choose a provider (guided)
+
+Ask the user the following questions **one at a time, in order**.
+Collect all answers before writing any config.
+
+---
+
+#### Question A — API key source
+
+> Do you have an API key from a cloud provider, or do you prefer to run
+> everything locally with Ollama?
+
+Offer these options:
+
+| Option | When to choose |
+|---|---|
+| **SiliconFlow** | Best for Chinese/Japanese/Korean text; supports reranking; low cost; requires a free account at siliconflow.cn |
+| **OpenAI** | Best for English; widely used; does not support reranking via this plugin |
+| **Ollama** | Fully local, no API key, no internet required; pull models first |
+| **Other / Custom** | You have an OpenAI-compatible endpoint (Jina, Together, Groq, self-hosted, etc.) |
+
+Record the user's choice as `PROVIDER`.
+
+---
+
+#### Question B — API key (skip if Ollama)
+
+If `PROVIDER` is **SiliconFlow**:
+
+> Please provide your SiliconFlow API key.
+> (Get one free at https://cloud.siliconflow.cn — click "API Keys" after signing in.)
+
+If `PROVIDER` is **OpenAI**:
+
+> Please provide your OpenAI API key.
+> (Find it at https://platform.openai.com/api-keys)
+
+If `PROVIDER` is **Other / Custom**:
+
+> Please provide:
+> 1. Your API base URL (must end with `/v1`, e.g. `https://api.example.com/v1`)
+> 2. Your API key
+
+Record as `API_KEY` and `BASE_URL`.
+
+If `PROVIDER` is **Ollama**:
+- Set `API_KEY = "ollama"` (placeholder, Ollama ignores it)
+- Set `BASE_URL = "http://localhost:11434/v1"`
+- Tell the user to pull the embedding model first:
+  ```bash
+  ollama pull nomic-embed-text
+  ```
+
+---
+
+#### Question C — Enable query expansion? (optional)
+
+> seekx can generate 2–3 variant phrasings of your query before searching,
+> which improves recall — especially for vague or short queries.
+>
+> This uses one extra LLM call per search (~50–200 ms extra latency).
+>
+> Would you like to enable query expansion? (Recommended: yes)
+
+If yes, record `EXPAND_MODEL` using this table:
+
+| Provider | Recommended expand model |
+|---|---|
+| SiliconFlow | `Qwen/Qwen3-8B` |
+| OpenAI | `gpt-4o-mini` |
+| Ollama | Any chat model the user has pulled (e.g. `llama3.2`, `qwen2.5`) |
+| Custom | Ask the user for a model name |
+
+If no, set `EXPAND_MODEL = null`.
+
+---
+
+#### Question D — Extra directories (optional)
+
+> Would you like to index any of your own directories (notes, docs, etc.)
+> in addition to OpenClaw's built-in memory files?
+>
+> If yes, list them. For each, provide:
+> - A short name (e.g. `notes`, `docs`, `brain`)
+> - The full path (e.g. `~/notes` or `/Users/me/Documents/notes`)
+
+Collect as a list of `{ name, path }` pairs.
+If the user says no or skips, use an empty list.
+
+---
+
+### Step 4 — Build the configuration
+
+Using the answers collected above, assemble the `pluginConfig` object.
+
+**For SiliconFlow:**
+
+```json
+{
+  "apiKey":       "<API_KEY>",
+  "baseUrl":      "https://api.siliconflow.cn/v1",
+  "embedModel":   "BAAI/bge-large-zh-v1.5",
+  "rerankModel":  "BAAI/bge-reranker-v2-m3",
+  "expandModel":  "<EXPAND_MODEL or omit>",
+  "paths":        []
+}
+```
+
+**For OpenAI:**
+
+```json
+{
+  "apiKey":      "<API_KEY>",
+  "baseUrl":     "https://api.openai.com/v1",
+  "embedModel":  "text-embedding-3-small",
+  "expandModel": "<EXPAND_MODEL or omit>",
+  "paths":       []
+}
+```
+
+(Omit `rerankModel` — OpenAI does not expose a reranking endpoint.)
+
+**For Ollama:**
+
+```json
+{
+  "apiKey":     "ollama",
+  "baseUrl":    "http://localhost:11434/v1",
+  "embedModel": "nomic-embed-text",
+  "expandModel": "<EXPAND_MODEL or omit>",
+  "paths":      []
+}
+```
+
+**For Custom:**
+
+```json
+{
+  "apiKey":      "<API_KEY>",
+  "baseUrl":     "<BASE_URL>",
+  "embedModel":  "<ask user>",
+  "rerankModel": "<ask user, or omit>",
+  "expandModel": "<EXPAND_MODEL or omit>",
+  "paths":       []
+}
+```
+
+If the user provided extra directories, populate `paths`:
+
+```json
+"paths": [
+  { "name": "notes", "path": "~/notes" },
+  { "name": "docs",  "path": "~/projects/docs" }
+]
+```
+
+---
+
+### Step 5 — Write the OpenClaw config
+
+Read the current config file:
+
+```bash
+cat ~/.openclaw/openclaw.json
+```
+
+If the file does not exist, start with `{}`.
+
+Merge the following into the config (do not overwrite unrelated fields):
+
+```json5
+{
+  "plugins": {
+    "slots": {
+      "memory": "seekx"          // makes seekx the exclusive memory backend
+    },
+    "entries": {
+      "seekx": {
+        "enabled": true,
+        "config": {
+          // paste the pluginConfig object assembled in Step 4
+        }
+      }
+    }
+  }
+}
+```
+
+Write the merged result back to `~/.openclaw/openclaw.json`.
+
+After writing, validate the file is parseable:
+
+```bash
+node -e "JSON.parse(require('fs').readFileSync(process.env.HOME + '/.openclaw/openclaw.json', 'utf8'))" \
+  && echo "valid JSON" || echo "PARSE ERROR — do not restart yet"
+```
+
+Stop and show the error if parsing fails.
+
+---
+
+### Step 6 — Restart the gateway
+
+```bash
+openclaw gateway restart
+```
+
+Wait 3 seconds, then check that the gateway is running:
+
+```bash
+openclaw gateway status
+```
+
+---
+
+### Step 7 — Verify
+
+```bash
+openclaw status
+```
+
+Confirm the `Memory` row contains `plugin seekx`.
+
+Interpret the row as follows:
+- `N files · N chunks · plugin seekx` → installation and indexing are working
+- `0 files · 0 chunks · plugin seekx` right after restart → the initial index
+  may still be warming up; wait 15 seconds and run `openclaw status` again
+- `plugin seekx · vector off` → valid BM25-only mode; vector search is not
+  active because no embedding model is configured or `sqlite-vec` is unavailable
+
+If the user already has memory files and an active OpenClaw agent session,
+optionally ask a memory-backed question through the agent to confirm end-to-end
+retrieval. Do not instruct the user to run `openclaw memory ...`; current
+OpenClaw versions expose memory backend state through `openclaw status`.
+
+---
+
+### Step 8 — Report to the user
+
+Tell the user:
+
+> seekx is now your OpenClaw memory backend.
+>
+> - OpenClaw's memory files (`MEMORY.md`, `memory/**/*.md`) are indexed automatically.
+> - [If extra directories were configured] Your extra directories are indexed and watched for changes.
+> - `memory_search` and `memory_get` now use seekx's search pipeline: BM25 by default, plus vector/rerank/expansion when configured and available.
+>
+> To check status at any time: `openclaw status`
+> To add more directories later: edit `~/.openclaw/openclaw.json` → `plugins.entries.seekx.config.paths`
+
+---
+
+## Troubleshooting
+
+**`openclaw plugins install` hangs or fails**
+→ Try `openclaw plugins install seekx-openclaw --force`
+→ Or use the npm fallback path in Step 2.
+
+**`openclaw status` does not show `plugin seekx` in the Memory row**
+→ Check that `plugins.slots.memory` is `"seekx"` (not `"memory-core"` or missing).
+→ Run `openclaw plugins list` and confirm seekx is listed as enabled.
+
+**Status shows `plugin seekx · vector off`**
+→ This is expected when no embedding model is configured, the API credentials are missing, or `sqlite-vec` cannot load.
+→ BM25 search still works; seekx is installed correctly.
+
+**API key error / 401 from provider**
+→ Double-check the key and baseUrl.
+→ For SiliconFlow: the key starts with `sk-` and was copied from the API Keys page.
+→ Re-run Step 5 with corrected values and restart the gateway.

package/skills/search/SKILL.md

@@ -0,0 +1,152 @@
+# Skill: Using seekx memory search in OpenClaw
+
+seekx is installed as the OpenClaw memory backend.
+`memory_search` and `memory_get` now route through seekx's search pipeline:
+BM25 full-text by default, with vector kNN, cross-encoder reranking, and query
+expansion enabled when the required models and runtime support are available.
+
+---
+
+## When to call `memory_search`
+
+**Call proactively** before answering any query that might be answered by
+stored context. Do not wait for the user to ask you to search — search first.
+
+Call `memory_search` when the user's message involves:
+
+- People (colleagues, contacts, companies, relationships)
+- Past decisions, meetings, or discussions
+- Projects, codebases, or technical systems the user has documented
+- Concepts, definitions, or domain knowledge the user has written down
+- Anything the user might have noted in `MEMORY.md` or a notes directory
+
+**Do not call** `memory_search` for:
+- General knowledge questions (use your built-in knowledge)
+- Queries where the user has provided all the context inline
+- Purely computational tasks (math, code generation from scratch)
+
+---
+
+## How to search
+
+Use natural language queries, not keywords. When configured, seekx handles
+query expansion and semantic matching internally; otherwise it falls back to
+BM25-only search.
+
+Good queries:
+```
+memory_search("Alice's role at Acme Corp and her preferred communication style")
+memory_search("why we chose PostgreSQL over MySQL for the billing service")
+memory_search("架构评审会议上的决定")
+```
+
+Less effective (but still works):
+```
+memory_search("Alice Acme")
+memory_search("PostgreSQL MySQL")
+```
+
+---
+
+## Search options
+
+```typescript
+memory_search(query: string, opts?: {
+  limit?: number;       // default: 6; increase for broad topics, decrease for precision
+  collection?: string;  // restrict to a named collection (see below)
+})
+```
+
+---
+
+## Scoping to a collection
+
+If you know which directory the relevant content lives in, scope the search
+to avoid noise from unrelated collections.
+
+```
+memory_search("API authentication flow", { collection: "docs" })
+memory_search("John Smith", { collection: "notes" })
+```
+
+Collection names come from:
+- `plugins.entries.seekx.config.paths[].name` in `~/.openclaw/openclaw.json`
+- the built-in collection name `openclaw-memory` for OpenClaw's own memory files
+
+Use `openclaw status` to confirm that seekx is active and that aggregate file
+and chunk counts are non-zero after indexing.
+
+---
+
+## Retrieving a full document
+
+Search results include a `path` field (absolute filesystem path).
+Use `memory_get` to read the full file content when:
+- You need more context than the snippet provides
+- The user asks you to read a specific file from memory
+- You want to check if a document has been updated since the snippet was indexed
+
+```
+memory_get("/Users/me/notes/people/alice.md")
+```
+
+Prefer paths that came from `memory_search` results. seekx only returns content
+for files inside indexed collections; paths outside indexed scope resolve to an
+empty string.
+
+For readable indexed paths, `memory_get` reads the live file from disk rather
+than the indexed snapshot, so it returns the current version.
+
+---
+
+## Interpreting results
+
+Each result contains:
+- `path` — source file (absolute path)
+- `content` — the matched text excerpt
+- `score` — relevance score (0–1); above 0.5 is a strong match
+- `collection` — which indexed directory the file is from
+
+If scores are all below 0.2, the query likely didn't match well.
+Try rephrasing with more context, or check that the relevant files are in
+an indexed collection (configured `paths[].name` or the built-in
+`openclaw-memory` collection). `openclaw status` can confirm that the backend
+is active and that indexing has completed.
+
+---
+
+## When search returns no results
+
+Possible causes and actions:
+
+| Cause | What to do |
+|---|---|
+| Initial indexing not finished (gateway just started) | Wait 15–30 seconds and retry |
+| The content is not in any indexed collection | Tell the user the content is not indexed; suggest adding the directory |
+| Query is too specific / uses exact names | Rephrase with context ("the meeting about X" instead of "X meeting notes") |
+| Files use an unindexed extension | Only `*.md`, `*.txt`, `*.markdown` are indexed by default |
+
+---
+
+## CJK queries
+
+Queries in Chinese, Japanese, or Korean work natively.
+seekx uses Jieba-based tokenization for CJK text, which is superior to the
+trigram approach used by OpenClaw's built-in backend.
+
+```
+memory_search("用户增长策略讨论")
+memory_search("技術的な決定の理由")
+```
+
+---
+
+## Combining with your own reasoning
+
+After retrieving memory results, synthesize them with your own knowledge.
+Cite the source file path so the user knows where the information came from.
+
+Example response pattern:
+> Based on your notes (`~/notes/projects/acme.md`), the Acme project's API
+> uses JWT tokens with a 24-hour expiry. The authentication flow is described
+> in the architecture document (`~/projects/docs/auth.md`).

package/src/config.ts

@@ -0,0 +1,118 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadConfig, type ResolvedConfig, type ServiceEndpoint } from "seekx-core";
+
+export interface ExtraPath {
+  name: string;
+  path: string;
+  pattern?: string;
+}
+
+/** Raw shape of what OpenClaw puts in pluginConfig. */
+export interface RawPluginConfig {
+  dbPath?: string;
+  paths?: unknown;
+  apiKey?: string;
+  baseUrl?: string;
+  embedModel?: string;
+  rerankModel?: string;
+  expandModel?: string;
+  searchLimit?: number;
+  refreshIntervalMs?: number;
+  includeOpenClawMemory?: boolean;
+}
+
+export interface SeekxPluginConfig {
+  dbPath: string;
+  extraPaths: ExtraPath[];
+  embed: ServiceEndpoint;
+  rerank: ServiceEndpoint | null;
+  expand: ServiceEndpoint | null;
+  searchLimit: number;
+  refreshIntervalMs: number;
+  includeOpenClawMemory: boolean;
+}
+
+function normalizeExtraPaths(paths: unknown): ExtraPath[] {
+  if (paths == null) return [];
+  if (!Array.isArray(paths)) {
+    throw new Error("Invalid plugin config: paths must be an array of { name, path, pattern? }");
+  }
+
+  return paths.map((entry, index) => {
+    if (!entry || typeof entry !== "object") {
+      throw new Error(`Invalid plugin config: paths[${index}] must be an object`);
+    }
+
+    const { name, path, pattern } = entry as {
+      name?: unknown;
+      path?: unknown;
+      pattern?: unknown;
+    };
+
+    if (typeof name !== "string" || name.trim() === "") {
+      throw new Error(`Invalid plugin config: paths[${index}].name must be a non-empty string`);
+    }
+    if (typeof path !== "string" || path.trim() === "") {
+      throw new Error(`Invalid plugin config: paths[${index}].path must be a non-empty string`);
+    }
+    if (pattern != null && typeof pattern !== "string") {
+      throw new Error(`Invalid plugin config: paths[${index}].pattern must be a string`);
+    }
+
+    return {
+      name: name.trim(),
+      path: path.trim(),
+      ...(pattern ? { pattern } : {}),
+    };
+  });
+}
+
+/**
+ * Merge the OpenClaw plugin config with the seekx config file.
+ *
+ * Precedence (high → low):
+ *   1. pluginConfig fields  (plugins.entries.seekx.config in openclaw.json)
+ *   2. ~/.seekx/config.yml  (seekx's own config file)
+ *   3. Built-in defaults
+ *
+ * @param raw - Raw plugin config from OpenClaw.
+ * @param loadConfigFn - Injectable config loader; defaults to the real
+ *   loadConfig() so production code needs no changes. Tests pass a stub.
+ */
+export function resolvePluginConfig(
+  raw: RawPluginConfig,
+  loadConfigFn: () => ResolvedConfig | null = loadConfig,
+): SeekxPluginConfig {
+  const base: ResolvedConfig | null = loadConfigFn();
+
+  const baseUrl = raw.baseUrl ?? base?.embed.baseUrl ?? "";
+  const apiKey = raw.apiKey ?? base?.embed.apiKey ?? "";
+  const embedModel = raw.embedModel ?? base?.embed.model ?? "";
+  const rerankModel = raw.rerankModel ?? base?.rerank?.model ?? null;
+  const expandModel = raw.expandModel ?? base?.expand?.model ?? null;
+
+  const embed: ServiceEndpoint = { baseUrl, apiKey, model: embedModel };
+
+  // For rerank and expand, if plugin config specifies a model name, build the
+  // endpoint using the same baseUrl/apiKey (they share the same provider).
+  // Otherwise fall back to the full endpoint from ~/.seekx/config.yml.
+  const rerank: ServiceEndpoint | null = rerankModel
+    ? { baseUrl, apiKey, model: rerankModel }
+    : (base?.rerank ?? null);
+
+  const expand: ServiceEndpoint | null = expandModel
+    ? { baseUrl, apiKey, model: expandModel }
+    : (base?.expand ?? null);
+
+  return {
+    dbPath: raw.dbPath ?? join(homedir(), ".seekx", "openclaw.db"),
+    extraPaths: normalizeExtraPaths(raw.paths),
+    embed,
+    rerank,
+    expand,
+    searchLimit: raw.searchLimit ?? 6,
+    refreshIntervalMs: raw.refreshIntervalMs ?? 300_000,
+    includeOpenClawMemory: raw.includeOpenClawMemory ?? true,
+  };
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { resolvePluginConfig, type RawPluginConfig } from "./config.ts";
+import { SeekxLifecycle } from "./lifecycle.ts";
+import { buildMemorySearchManager } from "./runtime.ts";
+
+export default definePluginEntry({
+  id: "seekx",
+  name: "seekx",
+  description: "Local-first hybrid search memory backend: BM25 + vector + rerank + CJK",
+  kind: "memory",
+
+  register(api) {
+    const raw = (api.pluginConfig ?? {}) as RawPluginConfig;
+    const config = resolvePluginConfig(raw);
+    const lifecycle = new SeekxLifecycle(config);
+
+    // Start eagerly so the initial index is underway before the first
+    // memory_search call arrives. start() is non-blocking; indexing runs
+    // in the background.
+    void lifecycle.start();
+
+    api.registerMemoryRuntime({
+      getMemorySearchManager: () => buildMemorySearchManager(lifecycle),
+      resolveMemoryBackendConfig: (rawCfg: unknown) =>
+        resolvePluginConfig(rawCfg as RawPluginConfig),
+    });
+
+    // Register a background service so OpenClaw calls stop() on shutdown,
+    // giving the watcher and database a chance to close cleanly.
+    // id is required by the real OpenClawPluginService type.
+    api.registerService({
+      id: "seekx-lifecycle",
+      stop: () => lifecycle.stop(),
+    } as Parameters<typeof api.registerService>[0]);
+  },
+});

package/src/lifecycle.ts

@@ -0,0 +1,203 @@
+import { mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import {
+  openDatabase,
+  loadSqliteVec,
+  Store,
+  SeekxClient,
+  Watcher,
+  indexDirectory,
+  type Database,
+  type CollectionWatch,
+} from "seekx-core";
+import { type SeekxPluginConfig } from "./config.ts";
+
+/** Collection name for OpenClaw's built-in memory files. */
+const OPENCLAW_MEMORY_COLLECTION = "openclaw-memory";
+
+/**
+ * Absolute path to OpenClaw's default agent workspace, which contains
+ * MEMORY.md and the memory/ daily-note tree.
+ */
+function openClawMemoryPath(): string {
+  return `${homedir()}/.openclaw/workspace`;
+}
+
+export class SeekxLifecycle {
+  readonly config: SeekxPluginConfig;
+  db!: Database;
+  store!: Store;
+  client: SeekxClient | null = null;
+  private watcher: Watcher | null = null;
+  private refreshTimer: ReturnType<typeof setInterval> | null = null;
+  private startPromise: Promise<void> | null = null;
+  private stopPromise: Promise<void> | null = null;
+  private initialIndexPromise: Promise<void> = Promise.resolve();
+  private indexQueue: Promise<void> = Promise.resolve();
+  private stopping = false;
+  private readonly shutdown = () => void this.stop();
+
+  constructor(config: SeekxPluginConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Open the database, register collections, run initial background indexing,
+   * and start the file watcher. Idempotent — safe to call multiple times.
+   */
+  async start(): Promise<void> {
+    if (this.startPromise) return this.startPromise;
+    this.stopping = false;
+    this.stopPromise = null;
+    this.startPromise = this._start();
+    return this.startPromise;
+  }
+
+  async waitForSearchReady(): Promise<void> {
+    await this.start();
+    await this.initialIndexPromise;
+  }
+
+  async resolveReadablePath(path: string): Promise<string | null> {
+    await this.start();
+    const normalizedPath = resolve(path);
+    for (const collection of this.store.listCollections()) {
+      if (this.store.findDocumentByPath(collection.name, normalizedPath)) {
+        return normalizedPath;
+      }
+    }
+    return null;
+  }
+
+  /** Queue a full incremental index pass and wait for completion. */
+  async _runFullIndex(): Promise<void> {
+    await this.start();
+    await this.queueFullIndex();
+  }
+
+  private async _start(): Promise<void> {
+    // Ensure the database directory exists before opening.
+    const dbDir = dirname(this.config.dbPath);
+    if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
+
+    this.db = await openDatabase(this.config.dbPath);
+    const vecLoaded = await loadSqliteVec(this.db);
+    this.store = new Store(this.db, vecLoaded);
+
+    // Wire the store's LLM cache into the client so expand/rerank responses
+    // are persisted across gateway restarts (TTL 1 hour).
+    const llmCache = {
+      get: (key: string) => this.store.getCachedLLM(key),
+      set: (key: string, value: string, ttlSec?: number) =>
+        this.store.setCachedLLM(key, value, ttlSec),
+    };
+
+    const { embed, rerank, expand } = this.config;
+    this.client =
+      embed.baseUrl && embed.model
+        ? new SeekxClient(embed, rerank, expand, llmCache)
+        : null;
+
+    // Register OpenClaw's own memory files as a collection.
+    if (this.config.includeOpenClawMemory) {
+      const memPath = openClawMemoryPath();
+      if (existsSync(memPath)) {
+        this.store.addCollection({
+          name: OPENCLAW_MEMORY_COLLECTION,
+          path: memPath,
+          pattern: "**/*.md",
+        });
+      }
+    }
+
+    // Register user-configured extra paths.
+    for (const ep of this.config.extraPaths) {
+      const absPath = ep.path.replace(/^~/, homedir());
+      if (!existsSync(absPath)) continue;
+      this.store.addCollection({
+        name: ep.name,
+        path: absPath,
+        ...(ep.pattern ? { pattern: ep.pattern } : {}),
+      });
+    }
+
+    const collectionWatches: CollectionWatch[] = this.store
+      .listCollections()
+      .map((c) => ({ collection: c.name, rootPath: c.path }));
+
+    this.watcher = new Watcher(this.store, this.client, collectionWatches, {
+      debounceMs: 1000,
+    });
+    this.watcher.start();
+
+    // The plugin keeps its own index database by default, so collection sync
+    // via a separate seekx CLI process is not a supported workflow.
+    if (this.config.refreshIntervalMs > 0) {
+      this.refreshTimer = setInterval(() => {
+        void this.queueFullIndex();
+      }, this.config.refreshIntervalMs);
+    }
+
+    process.once("SIGTERM", this.shutdown);
+    process.once("exit", this.shutdown);
+
+    // Startup stays non-blocking for plugin activation, but searches wait for
+    // this initial pass so they do not incorrectly return an empty result set
+    // before the first index has been built.
+    this.initialIndexPromise = this.queueFullIndex();
+  }
+
+  private queueFullIndex(): Promise<void> {
+    if (this.stopping) return Promise.resolve();
+    const run = this.indexQueue.then(async () => {
+      if (this.stopping) return;
+      await this.runFullIndexNow();
+    });
+    this.indexQueue = run.catch(() => {});
+    return run;
+  }
+
+  /** Run incremental indexing across all registered collections immediately. */
+  private async runFullIndexNow(): Promise<void> {
+    const collections = this.store.listCollections();
+    for (const col of collections) {
+      if (this.stopping) break;
+      try {
+        await indexDirectory(
+          this.store,
+          this.client,
+          col.name,
+          col.path,
+          col.pattern,
+          col.ignore_json ? (JSON.parse(col.ignore_json) as string[]) : [],
+        );
+      } catch (err) {
+        console.error(`[seekx-openclaw] indexDirectory error for "${col.name}": ${err}`);
+      }
+    }
+  }
+
+  async stop(): Promise<void> {
+    if (this.stopPromise) return this.stopPromise;
+    if (!this.startPromise) return;
+
+    this.stopping = true;
+    this.stopPromise = (async () => {
+      if (this.refreshTimer !== null) {
+        clearInterval(this.refreshTimer);
+        this.refreshTimer = null;
+      }
+      await this.watcher?.stop();
+      this.watcher = null;
+      await this.indexQueue.catch(() => {});
+      this.store?.close();
+      this.client = null;
+      process.off("SIGTERM", this.shutdown);
+      process.off("exit", this.shutdown);
+      this.startPromise = null;
+    })();
+
+    return this.stopPromise;
+  }
+}

package/src/openclaw-sdk.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Type stubs for the OpenClaw plugin SDK.
+ *
+ * These declarations cover the narrow surface used by this plugin.
+ * The actual types are provided at runtime by the installed openclaw package.
+ * Generated from docs.openclaw.ai/plugins/sdk-overview (2026-04).
+ */
+
+declare module "openclaw/plugin-sdk/plugin-entry" {
+  export interface MemorySearchResult {
+    path: string;
+    content: string;
+    score: number;
+    collection?: string;
+    title?: string | null;
+  }
+
+  export interface MemorySearchOpts {
+    limit?: number;
+    collection?: string;
+  }
+
+  /**
+   * Subset of MemoryProviderStatus returned by the real OpenClaw SDK.
+   * `status()` is called synchronously by OpenClaw's status scanner.
+   */
+  export interface BackendStatus {
+    backend: string;
+    provider?: string;
+    dbPath?: string;
+    /** Document (file) count — maps to MemoryProviderStatus.files. */
+    files?: number;
+    chunks?: number;
+    /** Legacy alias kept for backward compat with older test assertions. */
+    documents?: number;
+    embeddedChunks?: number;
+    vectorSearchAvailable?: boolean;
+    embedModel?: string | null;
+    collections?: Array<{ name: string; path: string; docCount: number }>;
+    vector?: { enabled: boolean; available?: boolean };
+    custom?: Record<string, unknown>;
+  }
+
+  /**
+   * The interface OpenClaw calls when memory_search / memory_get fire.
+   * Inferred from Honcho plugin source and openclaw/plugin-sdk/memory-host-search.
+   */
+  export interface MemorySearchManager {
+    search(query: string, opts: MemorySearchOpts): Promise<MemorySearchResult[]>;
+    readFile(path: string): Promise<string>;
+    /** Synchronous — called without await by OpenClaw's status scanner. */
+    status(): BackendStatus;
+    probeEmbeddingAvailability(): Promise<boolean>;
+    probeVectorAvailability(): Promise<boolean>;
+  }
+
+  /**
+   * Shape passed to api.registerMemoryRuntime().
+   * Legacy-compatible API; registerMemoryCapability() is preferred
+   * but its interface is not yet publicly documented (2026-04).
+   */
+  export interface MemoryRuntimeRegistration {
+    getMemorySearchManager(): { manager: MemorySearchManager };
+    resolveMemoryBackendConfig(raw: unknown): unknown;
+  }
+
+  export interface PluginServiceContext {}
+
+  export interface PluginService {
+    /** Unique service identifier required by OpenClaw's service registry. */
+    id: string;
+    start?: (ctx: PluginServiceContext) => Promise<void> | void;
+    stop?: (ctx: PluginServiceContext) => Promise<void> | void;
+  }
+
+  export interface PluginLogger {
+    debug(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+  }
+
+  export interface OpenClawPluginApi {
+    /** Plugin id as declared in openclaw.plugin.json. */
+    id: string;
+    /** Plugin-specific config from plugins.entries.<id>.config. */
+    pluginConfig: Record<string, unknown>;
+    /** Scoped logger. */
+    logger: PluginLogger;
+
+    /**
+     * Register a memory runtime adapter (legacy-compatible exclusive slot).
+     * Sets this plugin as the active memory backend.
+     */
+    registerMemoryRuntime(registration: MemoryRuntimeRegistration): void;
+
+    /**
+     * Register a long-lived background service.
+     * stop() is called on gateway shutdown, giving the service a chance
+     * to flush and close resources.
+     */
+    registerService(service: PluginService): void;
+  }
+
+  export interface DefinePluginEntryOptions {
+    /** Must match the id in openclaw.plugin.json. */
+    id: string;
+    name: string;
+    description: string;
+    /** Set to "memory" to participate in plugins.slots.memory. */
+    kind?: string;
+    register(api: OpenClawPluginApi): void;
+  }
+
+  export function definePluginEntry(opts: DefinePluginEntryOptions): unknown;
+}

package/src/runtime.ts

@@ -0,0 +1,141 @@
+import { readFileSync } from "node:fs";
+import { hybridSearch } from "seekx-core";
+import type {
+  MemorySearchManager,
+  MemorySearchResult,
+  MemorySearchOpts,
+} from "openclaw/plugin-sdk/plugin-entry";
+import type { SeekxLifecycle } from "./lifecycle.ts";
+import { readPersistedSeekxStatusSync } from "./status-db.ts";
+
+type StatusSnapshot = {
+  totalDocuments: number;
+  totalChunks: number;
+  embeddedChunks: number;
+  vectorSearchAvailable: boolean;
+  embedModel: string | null;
+  collections: Array<{
+    name: string;
+    path: string;
+    docCount: number;
+  }>;
+};
+
+function buildStatusResponse(lc: SeekxLifecycle, snapshot: StatusSnapshot) {
+  return {
+    backend: "seekx" as const,
+    provider: "seekx",
+    dbPath: lc.config.dbPath,
+    files: snapshot.totalDocuments,
+    chunks: snapshot.totalChunks,
+    vector: {
+      enabled: snapshot.vectorSearchAvailable,
+      available: snapshot.vectorSearchAvailable,
+    },
+    custom: {
+      embeddedChunks: snapshot.embeddedChunks,
+      embedModel: snapshot.embedModel,
+      collections: snapshot.collections.map((c) => ({
+        name: c.name,
+        path: c.path,
+        docCount: c.docCount,
+      })),
+    },
+  };
+}
+
+/**
+ * Build the MemorySearchManager that OpenClaw's runtime calls for
+ * memory_search and memory_get tool invocations.
+ *
+ * Precondition: lc.start() must have been called before any method fires.
+ */
+export function buildMemorySearchManager(lc: SeekxLifecycle): { manager: MemorySearchManager } {
+  const manager: MemorySearchManager = {
+    /**
+     * memory_search implementation.
+     *
+     * Routes through seekx's full hybrid pipeline:
+     *   query expansion → BM25 + vector kNN → RRF fusion → cross-encoder rerank
+     *
+     * Each stage degrades gracefully when the required service is unavailable:
+     *   - no expand model → original query only
+     *   - no embed / sqlite-vec → BM25-only
+     *   - no rerank model → RRF-ranked order used directly
+     */
+    async search(query: string, opts: MemorySearchOpts): Promise<MemorySearchResult[]> {
+      await lc.waitForSearchReady();
+      const limit = opts.limit ?? lc.config.searchLimit;
+      const { results } = await hybridSearch(lc.store, lc.client, query, {
+        limit,
+        mode: "hybrid",
+        useExpand: lc.config.expand !== null,
+        useRerank: lc.config.rerank !== null,
+        minResultScore: 0.01,
+        ...(opts.collection ? { collections: [opts.collection] } : {}),
+      });
+
+      return results.map((r) => ({
+        path: r.file,
+        content: r.snippet,
+        score: r.score,
+        collection: r.collection,
+        title: r.title ?? null,
+      }));
+    },
+
+    /**
+     * memory_get implementation.
+     *
+     * Reads the live file from disk rather than the indexed snapshot, ensuring
+     * the agent always sees the current version of a document.
+     * Returns an empty string if the file has been deleted since indexing.
+     */
+    async readFile(path: string): Promise<string> {
+      const readablePath = await lc.resolveReadablePath(path);
+      if (!readablePath) return "";
+      try {
+        return readFileSync(readablePath, "utf-8");
+      } catch {
+        return "";
+      }
+    },
+
+    /**
+     * status() is called SYNCHRONOUSLY by OpenClaw's status scanner.
+     *
+     * Field names follow MemoryProviderStatus (the real SDK type):
+     *   - files  → document count
+     *   - chunks → chunk count
+     *
+     * When the lifecycle has not yet completed start() (fresh process, status
+     * probe runs before the DB is open), fall back to a direct SQLite read of
+     * the persisted index state.
+     */
+    status() {
+      const snapshot = lc.store?.getStatus() ?? readPersistedSeekxStatusSync(lc.config.dbPath);
+      if (!snapshot) {
+        return {
+          backend: "seekx" as const,
+          provider: "seekx",
+          dbPath: lc.config.dbPath,
+          files: 0,
+          chunks: 0,
+        };
+      }
+      return buildStatusResponse(lc, snapshot);
+    },
+
+    async probeEmbeddingAvailability(): Promise<boolean> {
+      await lc.start();
+      return lc.client !== null;
+    },
+
+    async probeVectorAvailability(): Promise<boolean> {
+      await lc.start();
+      return lc.store.getStatus().vectorSearchAvailable;
+    },
+  };
+
+  return { manager };
+}

package/src/status-db.ts

@@ -0,0 +1,178 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+type SqliteStatement = {
+  get(...params: unknown[]): unknown;
+  all(...params: unknown[]): unknown;
+};
+
+type SqliteDatabase = {
+  prepare(sql: string): SqliteStatement;
+  close(): void;
+};
+
+type BetterSqlite3Ctor = new (
+  path: string,
+  options?: {
+    readonly?: boolean;
+    fileMustExist?: boolean;
+    timeout?: number;
+  },
+) => SqliteDatabase;
+
+type BunSqliteCtor = new (
+  path: string,
+  options?: {
+    readonly?: boolean;
+    create?: boolean;
+  },
+) => {
+  query(sql: string): SqliteStatement;
+  close(): void;
+};
+
+export interface PersistedSeekxStatus {
+  totalDocuments: number;
+  totalChunks: number;
+  embeddedChunks: number;
+  vectorSearchAvailable: boolean;
+  embedModel: string | null;
+  collections: Array<{
+    name: string;
+    path: string;
+    docCount: number;
+    chunkCount: number;
+  }>;
+}
+
+function toNumber(value: unknown): number {
+  if (typeof value === "number") return value;
+  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "string") {
+    const parsed = Number.parseInt(value, 10);
+    return Number.isNaN(parsed) ? 0 : parsed;
+  }
+  return 0;
+}
+
+function readTableNames(db: SqliteDatabase): Set<string> {
+  const rows = db
+    .prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
+    .all() as Array<{ name?: unknown }>;
+  return new Set(
+    rows
+      .map((row) => row.name)
+      .filter((name): name is string => typeof name === "string" && name.length > 0),
+  );
+}
+
+function readMetaValue(db: SqliteDatabase, key: string): string | null {
+  const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key) as { value?: unknown } | null;
+  return typeof row?.value === "string" ? row.value : null;
+}
+
+function isBunRuntime(): boolean {
+  return typeof (process.versions as { bun?: string }).bun === "string";
+}
+
+function openReadonlyDatabase(dbPath: string): SqliteDatabase {
+  if (isBunRuntime()) {
+    const { Database } = require("bun:sqlite") as { Database: BunSqliteCtor };
+    const db = new Database(dbPath, { readonly: true, create: false });
+    return {
+      prepare(sql: string) {
+        return db.query(sql);
+      },
+      close() {
+        db.close();
+      },
+    };
+  }
+
+  const coreRequire = createRequire(require.resolve("seekx-core"));
+  const BetterSqlite3 = coreRequire("better-sqlite3") as BetterSqlite3Ctor;
+  return new BetterSqlite3(dbPath, {
+    readonly: true,
+    fileMustExist: true,
+    timeout: 1000,
+  });
+}
+
+/**
+ * Read persisted seekx index status directly from SQLite without constructing
+ * Store. This is used by short-lived OpenClaw CLI probes where lifecycle.start()
+ * has not finished yet, but the gateway has already indexed content.
+ */
+export function readPersistedSeekxStatusSync(dbPath: string): PersistedSeekxStatus | null {
+  if (!existsSync(dbPath)) return null;
+
+  let db: SqliteDatabase | null = null;
+  try {
+    db = openReadonlyDatabase(dbPath);
+
+    const tables = readTableNames(db);
+    const hasCoreTables =
+      tables.has("collections") && tables.has("documents") && tables.has("chunks");
+    if (!hasCoreTables) return null;
+
+    const totalDocuments = toNumber(
+      (db.prepare("SELECT COUNT(*) AS n FROM documents").get() as { n?: unknown } | null)?.n,
+    );
+    const totalChunks = toNumber(
+      (db.prepare("SELECT COUNT(*) AS n FROM chunks").get() as { n?: unknown } | null)?.n,
+    );
+
+    let embeddedChunks = 0;
+    if (tables.has("vec_chunks")) {
+      try {
+        embeddedChunks = toNumber(
+          (db.prepare("SELECT COUNT(*) AS n FROM vec_chunks").get() as { n?: unknown } | null)?.n,
+        );
+      } catch {
+        embeddedChunks = 0;
+      }
+    }
+
+    const embedModel = tables.has("meta") ? readMetaValue(db, "embed_model") : null;
+    const embedDim = tables.has("meta") ? readMetaValue(db, "embed_dim") : null;
+    const vectorSearchAvailable = tables.has("vec_chunks") && embedDim !== null;
+
+    const collections = db
+      .prepare(
+        `SELECT c.name, c.path,
+                COUNT(DISTINCT d.id) AS doc_count,
+                COUNT(ch.id) AS chunk_count
+         FROM collections c
+         LEFT JOIN documents d ON d.collection = c.name
+         LEFT JOIN chunks ch ON ch.doc_id = d.id
+         GROUP BY c.name
+         ORDER BY c.name`,
+      )
+      .all() as Array<{
+      name?: unknown;
+      path?: unknown;
+      doc_count?: unknown;
+      chunk_count?: unknown;
+    }>;
+
+    return {
+      totalDocuments,
+      totalChunks,
+      embeddedChunks,
+      vectorSearchAvailable,
+      embedModel,
+      collections: collections.map((row) => ({
+        name: typeof row.name === "string" ? row.name : "",
+        path: typeof row.path === "string" ? row.path : "",
+        docCount: toNumber(row.doc_count),
+        chunkCount: toNumber(row.chunk_count),
+      })),
+    };
+  } catch {
+    return null;
+  } finally {
+    db?.close();
+  }
+}