@lacneu/openclaw-knowledge 3.1.0

package/dist/embeddings.js

@@ -0,0 +1,33 @@
+// Gemini embedding client for query vectors.
+//
+// We deliberately hit the *native* `embedContent` endpoint rather than the
+// OpenAI-compatible one, because the OpenAI endpoint does not support
+// multimodal inputs and we want to stay in the same embedding space as the
+// n8n ingestion pipeline (which uses the native endpoint with images/audio).
+const GEMINI_EMBED_URL = "https://generativelanguage.googleapis.com/v1beta/" +
+    "models/gemini-embedding-2-preview:embedContent";
+/**
+ * Embed a text query via Gemini Embedding 2 Preview.
+ * Uses the same model as n8n document ingestion so that query vectors and
+ * stored chunks live in the same 3072-dimensional space.
+ *
+ * @throws Error on any non-OK HTTP response, with the first 200 chars of the
+ *         error body for debugging.
+ */
+export async function embedQuery(text, geminiApiKey) {
+    const url = `${GEMINI_EMBED_URL}?key=${geminiApiKey}`;
+    const resp = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            content: { parts: [{ text }] },
+        }),
+    });
+    if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(`Gemini embedding failed (${resp.status}): ${body.slice(0, 200)}`);
+    }
+    const data = (await resp.json());
+    return data.embedding.values;
+}
+//# sourceMappingURL=embeddings.js.map

package/dist/embeddings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.js","sourceRoot":"","sources":["../src/embeddings.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,EAAE;AACF,2EAA2E;AAC3E,sEAAsE;AACtE,2EAA2E;AAC3E,6EAA6E;AAE7E,MAAM,gBAAgB,GACpB,mDAAmD;IACnD,gDAAgD,CAAC;AAMnD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAAY,EACZ,YAAoB;IAEpB,MAAM,GAAG,GAAG,GAAG,gBAAgB,QAAQ,YAAY,EAAE,CAAC;IAEtD,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAC5B,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;YACnB,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;SAC/B,CAAC;KACH,CAAC,CAAC;IAEH,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QACb,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,4BAA4B,IAAI,CAAC,MAAM,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAClE,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAA4B,CAAC;IAC5D,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;AAC/B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import type { OpenClawPluginApi, PluginLogger } from "openclaw/plugin-sdk/plugin-entry";
+import type { BeforePromptBuildEvent, BeforePromptBuildResult, PgPoolLike, ResolvedKnowledgeConfig } from "./types.js";
+export { resolveEnv, resolveConfig } from "./config.js";
+export { embedQuery } from "./embeddings.js";
+export { searchCollection, formatPgvectorResults } from "./pgvector.js";
+export { queryLightRAG, truncateLightRAG, formatLightRAGResults } from "./lightrag.js";
+export type { BeforePromptBuildEvent, BeforePromptBuildResult, KnowledgePluginConfig, LightRAGQueryMode, PgPoolLike, PgvectorResult, PgvectorRow, PromptContentPart, PromptMessage, ResolvedKnowledgeConfig, } from "./types.js";
+interface HookHandlerDeps {
+    config: ResolvedKnowledgeConfig;
+    pool: PgPoolLike | null;
+    logger: PluginLogger;
+}
+/**
+ * Build the `before_prompt_build` handler bound to a specific plugin state.
+ * Kept as a pure factory so the handler can be unit-tested with fake deps.
+ */
+export declare function createBeforePromptBuildHandler(deps: HookHandlerDeps): (event: BeforePromptBuildEvent) => Promise<BeforePromptBuildResult | undefined>;
+/**
+ * Register the plugin against a minimal shape-compatible subset of the
+ * OpenClaw plugin API. Returns nothing; side effects are setting a hook and
+ * logging the initial status.
+ */
+export declare function registerKnowledgePlugin(api: OpenClawPluginApi): void;
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema;
+    register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
+} & Pick<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition, "kind" | "reload" | "nodeHostCommands" | "securityAuditCollectors">;
+export default _default;

package/dist/index.js

@@ -0,0 +1,239 @@
+// openclaw-knowledge — Multi-source knowledge plugin for OpenClaw
+//
+// Queries two knowledge sources in parallel and injects relevant context
+// into the agent's system prompt via `appendSystemContext`:
+//   1. PostgreSQL pgvector — semantic vector search on document embeddings
+//   2. LightRAG — knowledge graph with entity/relation multi-hop search
+//
+// Hook: before_prompt_build (requires OpenClaw >= v2026.3.7)
+// Depends on: pg (node-postgres)
+//
+// This is the canonical entry point for the plugin. Helpers live in sibling
+// modules (`config.ts`, `embeddings.ts`, `pgvector.ts`, `lightrag.ts`) so the
+// business logic can be unit-tested without instantiating the full SDK.
+import pg from "pg";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { resolveConfig } from "./config.js";
+import { embedQuery } from "./embeddings.js";
+import { searchCollection, formatPgvectorResults } from "./pgvector.js";
+import { queryLightRAG, formatLightRAGResults } from "./lightrag.js";
+// Re-export helpers so the test suite can import them directly without
+// duplicating imports from every submodule.
+export { resolveEnv, resolveConfig } from "./config.js";
+export { embedQuery } from "./embeddings.js";
+export { searchCollection, formatPgvectorResults } from "./pgvector.js";
+export { queryLightRAG, truncateLightRAG, formatLightRAGResults } from "./lightrag.js";
+// ---------------------------------------------------------------------------
+// Hook handler factory
+//
+// Extracted from `register` so tests can exercise the handler directly
+// without mocking the full plugin API surface.
+// ---------------------------------------------------------------------------
+const MAX_CONSECUTIVE_ERRORS = 3;
+const COOLDOWN_MS = 5 * 60 * 1000;
+const MIN_QUERY_LENGTH = 3;
+/**
+ * Build the `before_prompt_build` handler bound to a specific plugin state.
+ * Kept as a pure factory so the handler can be unit-tested with fake deps.
+ */
+export function createBeforePromptBuildHandler(deps) {
+    const { config, pool, logger } = deps;
+    // Per-instance state: consecutive failure counter and cooldown deadline.
+    // Closed-over so two registrations of the hook never share state.
+    let consecutiveErrors = 0;
+    let cooldownUntil = 0;
+    return async function beforePromptBuild(event) {
+        if (!config.enabled)
+            return undefined;
+        // Cooldown after repeated failures: skip silently until the deadline
+        // passes, then reset the counter and resume normal operation.
+        if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+            if (Date.now() < cooldownUntil)
+                return undefined;
+            consecutiveErrors = 0;
+            logger.info("openclaw-knowledge: resuming after cooldown");
+        }
+        const query = extractQueryFromMessages(event.messages);
+        if (!query || query.trim().length < MIN_QUERY_LENGTH)
+            return undefined;
+        try {
+            const tasks = [];
+            if (config.pgvectorEnabled && pool) {
+                tasks.push(runPgvectorSource(pool, query, config));
+            }
+            if (config.lightragEnabled) {
+                tasks.push(runLightRAGSource(query, config));
+            }
+            const settled = await Promise.allSettled(tasks);
+            const sections = [];
+            let failedSources = 0;
+            for (const result of settled) {
+                if (result.status === "rejected") {
+                    failedSources++;
+                    const reason = result.reason;
+                    logger.error(`openclaw-knowledge: source failed — ${reason?.message ?? String(result.reason)}`);
+                    continue;
+                }
+                const section = renderSection(result.value, config, logger);
+                if (section)
+                    sections.push(section);
+            }
+            // If every source we launched failed, treat the turn as a failure for
+            // cooldown tracking. A partial failure is fine — the other source's
+            // context is better than nothing.
+            if (failedSources > 0 && failedSources === tasks.length) {
+                consecutiveErrors++;
+                if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+                    cooldownUntil = Date.now() + COOLDOWN_MS;
+                    logger.error(`openclaw-knowledge: ${consecutiveErrors} consecutive errors — cooling down 5 min`);
+                }
+                return undefined;
+            }
+            consecutiveErrors = 0;
+            if (sections.length === 0)
+                return undefined;
+            return {
+                appendSystemContext: [
+                    "",
+                    "## Relevant Knowledge Base",
+                    "Use this information to answer the user's question accurately.",
+                    "Always cite the source document name when using this information.",
+                    "",
+                    ...sections,
+                ].join("\n"),
+            };
+        }
+        catch (err) {
+            // Catch-all: an unexpected crash must never propagate to the agent.
+            consecutiveErrors++;
+            const message = err instanceof Error ? err.message : String(err);
+            if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+                cooldownUntil = Date.now() + COOLDOWN_MS;
+                logger.error(`openclaw-knowledge: ${consecutiveErrors} consecutive errors — cooling down 5 min: ${message}`);
+            }
+            else {
+                logger.error(`openclaw-knowledge: ${message}`);
+            }
+            return undefined;
+        }
+    };
+}
+/**
+ * Extract the most recent user message text. OpenClaw surfaces two content
+ * shapes: a plain string, or an array of typed content parts (multi-modal).
+ */
+function extractQueryFromMessages(messages) {
+    if (!Array.isArray(messages) || messages.length === 0)
+        return "";
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (!msg || msg.role !== "user")
+            continue;
+        if (typeof msg.content === "string") {
+            return msg.content;
+        }
+        if (Array.isArray(msg.content)) {
+            return msg.content
+                .filter((p) => p.type === "text" && typeof p.text === "string")
+                .map((p) => p.text)
+                .join(" ");
+        }
+        return "";
+    }
+    return "";
+}
+async function runPgvectorSource(pool, query, config) {
+    const vector = await embedQuery(query, config.geminiApiKey);
+    const searches = config.collections.map((col) => searchCollection(pool, col, vector, config.topK, config.scoreThreshold));
+    const allResults = (await Promise.all(searches)).flat();
+    allResults.sort((a, b) => b.score - a.score);
+    return { source: "pgvector", data: allResults };
+}
+async function runLightRAGSource(query, config) {
+    const context = await queryLightRAG(config.lightragUrl, config.lightragApiKey, query, config.lightragQueryMode);
+    return { source: "lightrag", data: context };
+}
+function renderSection(result, config, logger) {
+    if (result.source === "pgvector") {
+        const formatted = formatPgvectorResults(result.data, config.maxInjectChars);
+        if (!formatted)
+            return null;
+        const topScore = result.data[0]?.score?.toFixed(2) ?? "n/a";
+        logger.info(`openclaw-knowledge: pgvector — ${result.data.length} result(s) (top: ${topScore})`);
+        return "### Document Search Results (pgvector)\n" + formatted;
+    }
+    if (result.source === "lightrag") {
+        const formatted = formatLightRAGResults(result.data, config.lightragMaxChars);
+        if (!formatted)
+            return null;
+        logger.info(`openclaw-knowledge: LightRAG — ${formatted.truncated.length}/${formatted.originalLength} chars (truncated from ${formatted.originalLength})`);
+        return "### Knowledge Graph Context (LightRAG)\n" + formatted.truncated;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Plugin registration helper
+//
+// Exposed so tests can exercise the full wiring (including api.on) without
+// going through `definePluginEntry`, which is tied to the SDK runtime.
+// ---------------------------------------------------------------------------
+/**
+ * Register the plugin against a minimal shape-compatible subset of the
+ * OpenClaw plugin API. Returns nothing; side effects are setting a hook and
+ * logging the initial status.
+ */
+export function registerKnowledgePlugin(api) {
+    const rawConfig = (api.pluginConfig ?? {});
+    const config = resolveConfig(rawConfig);
+    if (!config.pgvectorEnabled && !config.lightragEnabled) {
+        api.logger.warn("openclaw-knowledge: neither pgvector nor LightRAG configured — plugin disabled");
+        return;
+    }
+    // Only instantiate the pg pool when pgvector is actually in play. Booting
+    // a pool with no valid connection string would keep the plugin disabled
+    // anyway and leak sockets on hot-reload.
+    let pool = null;
+    if (config.pgvectorEnabled) {
+        const realPool = new pg.Pool({
+            connectionString: config.postgresUrl,
+            max: 3,
+            idleTimeoutMillis: 30000,
+        });
+        realPool.on("error", (err) => {
+            api.logger.error(`openclaw-knowledge: pool error — ${err.message}`);
+        });
+        pool = realPool;
+    }
+    const sources = [];
+    if (config.pgvectorEnabled) {
+        sources.push(`pgvector (${config.collections.join(", ")})`);
+    }
+    if (config.lightragEnabled) {
+        sources.push(`LightRAG (${config.lightragQueryMode})`);
+    }
+    api.logger.info(`openclaw-knowledge: ready — sources: ${sources.join(" + ")}`);
+    const handler = createBeforePromptBuildHandler({
+        config,
+        pool,
+        logger: api.logger,
+    });
+    // The SDK's `api.on<K>` signature is strongly typed per hook name, so we
+    // use a cast here to bridge our structural handler type with the precise
+    // `PluginHookHandlerMap["before_prompt_build"]` expected signature.
+    // The handler itself is fully type-safe on its own contract (see
+    // {@link createBeforePromptBuildHandler}).
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    api.on("before_prompt_build", handler);
+}
+// ---------------------------------------------------------------------------
+// Canonical plugin entry
+// ---------------------------------------------------------------------------
+export default definePluginEntry({
+    id: "openclaw-knowledge",
+    name: "Knowledge Base",
+    description: "Multi-source knowledge search for OpenClaw (pgvector + LightRAG)",
+    register(api) {
+        registerKnowledgePlugin(api);
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lightrag.d.ts

@@ -0,0 +1,28 @@
+import type { LightRAGQueryMode } from "./types.js";
+/**
+ * Query a LightRAG server for context relevant to `query`.
+ *
+ * Modes:
+ * - `naive`  — simple vector similarity on chunks
+ * - `local`  — entity-neighbourhood traversal
+ * - `global` — community summaries
+ * - `hybrid` — local + global (recommended default)
+ *
+ * @throws Error on any non-OK HTTP response, with the first 200 chars of the
+ *         error body for debugging.
+ */
+export declare function queryLightRAG(url: string, apiKey: string, query: string, mode?: LightRAGQueryMode): Promise<string>;
+/**
+ * Truncate text to `maxChars` without cutting mid-sentence when possible.
+ * Falls back to a raw character cut if no sentence boundary is found in the
+ * second half of the allowed window.
+ */
+export declare function truncateLightRAG(text: string, maxChars: number): string;
+/**
+ * Convenience wrapper used by the hook handler: trim the context, truncate
+ * it to the configured budget, and return `null` if nothing remains.
+ */
+export declare function formatLightRAGResults(rawContext: string, maxChars: number): {
+    truncated: string;
+    originalLength: number;
+} | null;

package/dist/lightrag.js

@@ -0,0 +1,69 @@
+// LightRAG query client.
+//
+// LightRAG is a knowledge graph server built on Neo4j + a vector store. We
+// call its `/query` endpoint with `only_need_context=true` so it returns the
+// assembled context text WITHOUT running its own LLM synthesis — we only need
+// the raw context to feed back into OpenClaw's agent.
+/**
+ * Query a LightRAG server for context relevant to `query`.
+ *
+ * Modes:
+ * - `naive`  — simple vector similarity on chunks
+ * - `local`  — entity-neighbourhood traversal
+ * - `global` — community summaries
+ * - `hybrid` — local + global (recommended default)
+ *
+ * @throws Error on any non-OK HTTP response, with the first 200 chars of the
+ *         error body for debugging.
+ */
+export async function queryLightRAG(url, apiKey, query, mode = "hybrid") {
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    if (apiKey)
+        headers["X-API-Key"] = apiKey;
+    const resp = await fetch(`${url}/query`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            query,
+            mode,
+            only_need_context: true,
+            stream: false,
+        }),
+    });
+    if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(`LightRAG query failed (${resp.status}): ${body.slice(0, 200)}`);
+    }
+    const data = (await resp.json());
+    return data.response ?? "";
+}
+/**
+ * Truncate text to `maxChars` without cutting mid-sentence when possible.
+ * Falls back to a raw character cut if no sentence boundary is found in the
+ * second half of the allowed window.
+ */
+export function truncateLightRAG(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    const truncated = text.slice(0, maxChars);
+    const lastPeriod = truncated.lastIndexOf(".");
+    return lastPeriod > maxChars * 0.5
+        ? truncated.slice(0, lastPeriod + 1)
+        : truncated;
+}
+/**
+ * Convenience wrapper used by the hook handler: trim the context, truncate
+ * it to the configured budget, and return `null` if nothing remains.
+ */
+export function formatLightRAGResults(rawContext, maxChars) {
+    const context = rawContext.trim();
+    if (context.length === 0)
+        return null;
+    return {
+        truncated: truncateLightRAG(context, maxChars),
+        originalLength: context.length,
+    };
+}
+//# sourceMappingURL=lightrag.js.map

package/dist/lightrag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lightrag.js","sourceRoot":"","sources":["../src/lightrag.ts"],"names":[],"mappings":"AAAA,yBAAyB;AACzB,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,8EAA8E;AAC9E,sDAAsD;AAQtD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAW,EACX,MAAc,EACd,KAAa,EACb,OAA0B,QAAQ;IAElC,MAAM,OAAO,GAA2B;QACtC,cAAc,EAAE,kBAAkB;KACnC,CAAC;IACF,IAAI,MAAM;QAAE,OAAO,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC;IAE1C,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,GAAG,QAAQ,EAAE;QACvC,MAAM,EAAE,MAAM;QACd,OAAO;QACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;YACnB,KAAK;YACL,IAAI;YACJ,iBAAiB,EAAE,IAAI;YACvB,MAAM,EAAE,KAAK;SACd,CAAC;KACH,CAAC,CAAC;IAEH,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QACb,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,0BAA0B,IAAI,CAAC,MAAM,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAChE,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAA4B,CAAC;IAC5D,OAAO,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,QAAgB;IAC7D,IAAI,IAAI,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEzC,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC1C,MAAM,UAAU,GAAG,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9C,OAAO,UAAU,GAAG,QAAQ,GAAG,GAAG;QAChC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,GAAG,CAAC,CAAC;QACpC,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,UAAkB,EAClB,QAAgB;IAEhB,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;IAClC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEtC,OAAO;QACL,SAAS,EAAE,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC;QAC9C,cAAc,EAAE,OAAO,CAAC,MAAM;KAC/B,CAAC;AACJ,CAAC"}

package/dist/pgvector.d.ts

@@ -0,0 +1,21 @@
+import type { PgPoolLike, PgvectorResult } from "./types.js";
+/**
+ * Search a single collection in `knowledge_vectors` using cosine similarity.
+ *
+ * Score filtering is performed in JS after the query rather than in SQL so
+ * the HNSW index can handle `ORDER BY ... <=> ... LIMIT $3` efficiently
+ * (a WHERE clause on the computed score would defeat the index).
+ *
+ * On any database error we swallow the exception and return an empty array —
+ * the plugin must never block the agent, so a DB hiccup degrades gracefully.
+ */
+export declare function searchCollection(pool: PgPoolLike, collection: string, vector: number[], topK: number, scoreThreshold: number): Promise<PgvectorResult[]>;
+/**
+ * Format pgvector results for injection into the system prompt.
+ * Respects a character budget so we never blow the context window with a
+ * single oversized chunk — entries are appended whole until the budget is hit.
+ *
+ * Returns `null` when there is nothing useful to inject so the caller can
+ * easily skip empty sections.
+ */
+export declare function formatPgvectorResults(results: PgvectorResult[], maxChars: number): string | null;

package/dist/pgvector.js

@@ -0,0 +1,81 @@
+// PostgreSQL / pgvector search helpers.
+//
+// The HNSW index for our 3072-dimensional embeddings is built on
+// `halfvec(3072)` because pgvector's HNSW implementation caps at 2000 dims
+// for the native `vector` type. Both the column cast and the query parameter
+// cast must match, otherwise the planner falls back to a sequential scan.
+const SEARCH_SQL = `SELECT file_name, mime_type, text, file_id, source, owner,
+              chunk_index, total_chunks, timestamp_start, timestamp_end,
+              embedded_at,
+              1 - (embedding::halfvec(3072) <=> $1::halfvec(3072)) AS score
+       FROM knowledge_vectors
+       WHERE collection = $2
+       ORDER BY embedding::halfvec(3072) <=> $1::halfvec(3072)
+       LIMIT $3`;
+/**
+ * Search a single collection in `knowledge_vectors` using cosine similarity.
+ *
+ * Score filtering is performed in JS after the query rather than in SQL so
+ * the HNSW index can handle `ORDER BY ... <=> ... LIMIT $3` efficiently
+ * (a WHERE clause on the computed score would defeat the index).
+ *
+ * On any database error we swallow the exception and return an empty array —
+ * the plugin must never block the agent, so a DB hiccup degrades gracefully.
+ */
+export async function searchCollection(pool, collection, vector, topK, scoreThreshold) {
+    const vectorStr = `[${vector.join(",")}]`;
+    try {
+        const result = await pool.query(SEARCH_SQL, [vectorStr, collection, topK]);
+        // pg returns numeric columns as strings by default, so parse the score.
+        return result.rows
+            .map((row) => ({
+            collection,
+            score: parseFloat(row.score),
+            file_name: row.file_name ?? null,
+            mime_type: row.mime_type ?? null,
+            text: row.text ?? null,
+            file_id: row.file_id ?? null,
+            source: row.source ?? null,
+            owner: row.owner ?? null,
+            chunk_index: row.chunk_index ?? null,
+            total_chunks: row.total_chunks ?? null,
+            timestamp_start: row.timestamp_start ?? null,
+            timestamp_end: row.timestamp_end ?? null,
+        }))
+            .filter((row) => row.score >= scoreThreshold);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Format pgvector results for injection into the system prompt.
+ * Respects a character budget so we never blow the context window with a
+ * single oversized chunk — entries are appended whole until the budget is hit.
+ *
+ * Returns `null` when there is nothing useful to inject so the caller can
+ * easily skip empty sections.
+ */
+export function formatPgvectorResults(results, maxChars) {
+    if (results.length === 0)
+        return null;
+    let output = "";
+    for (const r of results) {
+        const lines = [
+            `[${r.collection}] ${r.file_name ?? "unknown"} (score: ${r.score.toFixed(2)})`,
+        ];
+        if (r.timestamp_start) {
+            lines.push(`Segment: ${r.timestamp_start} - ${r.timestamp_end ?? ""}`);
+        }
+        if (r.text) {
+            lines.push(`Content: ${r.text}`);
+        }
+        lines.push(""); // blank line separator between entries
+        const entry = lines.join("\n");
+        if (output.length + entry.length > maxChars)
+            break;
+        output += entry;
+    }
+    return output;
+}
+//# sourceMappingURL=pgvector.js.map

package/dist/pgvector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pgvector.js","sourceRoot":"","sources":["../src/pgvector.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,EAAE;AACF,iEAAiE;AACjE,2EAA2E;AAC3E,6EAA6E;AAC7E,0EAA0E;AAI1E,MAAM,UAAU,GAAG;;;;;;;gBAOH,CAAC;AAEjB;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAgB,EAChB,UAAkB,EAClB,MAAgB,EAChB,IAAY,EACZ,cAAsB;IAEtB,MAAM,SAAS,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAE1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;QAE3E,wEAAwE;QACxE,OAAO,MAAM,CAAC,IAAI;aACf,GAAG,CAAC,CAAC,GAAgB,EAAkB,EAAE,CAAC,CAAC;YAC1C,UAAU;YACV,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC;YAC5B,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,IAAI;YAChC,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,IAAI;YAChC,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,IAAI;YACtB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,IAAI;YAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI;YAC1B,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,IAAI;YACxB,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,IAAI;YACpC,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,IAAI;YACtC,eAAe,EAAE,GAAG,CAAC,eAAe,IAAI,IAAI;YAC5C,aAAa,EAAE,GAAG,CAAC,aAAa,IAAI,IAAI;SACzC,CAAC,CAAC;aACF,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,IAAI,cAAc,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAyB,EACzB,QAAgB;IAEhB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEtC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,KAAK,GAAa;YACtB,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,SAAS,IAAI,SAAS,YAAY,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;SAC/E,CAAC;QAEF,IAAI,CAAC,CAAC,eAAe,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,eAAe,MAAM,CAAC,CAAC,aAAa,IAAI,EAAE,EAAE,CAAC,CAAC;QACzE,CAAC;QAED,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;YACX,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACnC,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,uCAAuC;QACvD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAE/B,IAAI,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,QAAQ;YAAE,MAAM;QACnD,MAAM,IAAI,KAAK,CAAC;IAClB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Runtime configuration as it appears in `plugins.entries.openclaw-knowledge.config`.
+ * All fields are optional — defaults are applied in {@link resolveConfig}.
+ */
+export interface KnowledgePluginConfig {
+    enabled?: boolean;
+    geminiApiKey?: string;
+    postgresUrl?: string;
+    collections?: string[];
+    topK?: number;
+    scoreThreshold?: number;
+    maxInjectChars?: number;
+    pgvectorEnabled?: boolean;
+    lightragUrl?: string;
+    lightragApiKey?: string;
+    lightragQueryMode?: LightRAGQueryMode;
+    lightragMaxChars?: number;
+    lightragEnabled?: boolean;
+}
+export type LightRAGQueryMode = "naive" | "local" | "global" | "hybrid";
+/**
+ * Fully resolved plugin configuration after defaults, env substitution, and
+ * derivation of the pgvector/lightrag enabled flags from presence of secrets.
+ */
+export interface ResolvedKnowledgeConfig {
+    enabled: boolean;
+    geminiApiKey: string;
+    postgresUrl: string;
+    collections: string[];
+    topK: number;
+    scoreThreshold: number;
+    maxInjectChars: number;
+    pgvectorEnabled: boolean;
+    lightragUrl: string;
+    lightragApiKey: string;
+    lightragQueryMode: LightRAGQueryMode;
+    lightragMaxChars: number;
+    lightragEnabled: boolean;
+}
+/**
+ * One search hit from the PostgreSQL `knowledge_vectors` table, after score
+ * parsing and filtering.
+ */
+export interface PgvectorResult {
+    collection: string;
+    score: number;
+    file_name: string | null;
+    mime_type: string | null;
+    text: string | null;
+    file_id: string | null;
+    source: string | null;
+    owner: string | null;
+    chunk_index: number | null;
+    total_chunks: number | null;
+    timestamp_start: string | null;
+    timestamp_end: string | null;
+}
+/**
+ * Minimal `pg.Pool` surface that {@link searchCollection} actually uses.
+ * Declared locally so helpers can be unit-tested without a real database
+ * and without pulling `@types/pg` into the test graph.
+ */
+export interface PgPoolLike {
+    query(sql: string, params: unknown[]): Promise<{
+        rows: PgvectorRow[];
+    }>;
+}
+/**
+ * Raw row shape returned by the pgvector SQL query. `score` comes back as a
+ * string because pg returns numeric values as strings by default.
+ */
+export interface PgvectorRow {
+    file_name?: string | null;
+    mime_type?: string | null;
+    text?: string | null;
+    file_id?: string | null;
+    source?: string | null;
+    owner?: string | null;
+    chunk_index?: number | null;
+    total_chunks?: number | null;
+    timestamp_start?: string | null;
+    timestamp_end?: string | null;
+    embedded_at?: string | null;
+    score: string;
+}
+/**
+ * Shape of the `before_prompt_build` event payload as consumed by this plugin.
+ * We only rely on `messages`; the SDK may add other fields that we ignore.
+ */
+export interface BeforePromptBuildEvent {
+    messages?: PromptMessage[];
+}
+export interface PromptMessage {
+    role?: string;
+    content?: string | PromptContentPart[];
+}
+export interface PromptContentPart {
+    type?: string;
+    text?: string;
+}
+/**
+ * Return value honoured by OpenClaw when a `before_prompt_build` handler wants
+ * to append extra text to the agent's system prompt.
+ */
+export interface BeforePromptBuildResult {
+    appendSystemContext: string;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+// Type definitions for the openclaw-knowledge plugin.
+//
+// Kept separate from the entry point so that tests and helper modules can
+// import them without pulling in the full plugin registration code.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,EAAE;AACF,0EAA0E;AAC1E,oEAAoE"}