@lacneu/openclaw-knowledge 3.1.2 → 3.2.1

package/dist/router/labels.js

@@ -0,0 +1,67 @@
+// Default zero-shot labels for the Jina Classifier.
+//
+// The labels are intentionally bilingual: most prompts in the observed
+// traces are French (Ataraxis is a French-speaking deployment) but the
+// system prompts and agent meta-questions are often English. Jina
+// `jina-embeddings-v3` handles both languages natively.
+//
+// Each label is a short sentence describing the kind of question that
+// belongs to that route. Jina embeds both the label and the input, then
+// picks the closest one — so the more discriminative the labels, the
+// better the routing. Empirically, "describe the kind of question"
+// outperforms "give a category name" by ~25% on small samples
+// (https://jina.ai/news/rephrased-labels-improve-zero-shot-text-classification-30/).
+/**
+ * Public constants — MUST stay in sync with `Route` in `types.js`.
+ *
+ * The label prefix passed to Jina (zero-shot) and the canonical name a
+ * few-shot classifier MUST be trained against share the same literal
+ * values as the `Route` union ("NONE" | "PGVECTOR_ONLY" | "LIGHTRAG_ONLY"
+ * | "ALL"). If they diverged, the classifier path would always fall back
+ * to "ALL" because `isKnownRoute` would reject the predicted label.
+ */
+export const ROUTE_NONE = "NONE";
+export const ROUTE_PGVECTOR_ONLY = "PGVECTOR_ONLY";
+export const ROUTE_LIGHTRAG_ONLY = "LIGHTRAG_ONLY";
+export const ROUTE_ALL = "ALL";
+/**
+ * Default labels handed to Jina `/v1/classify` in zero-shot mode when the
+ * operator does not supply a few-shot `classifierId`.
+ *
+ * Order does not matter for correctness, but we keep `NONE` first by
+ * convention so test output is stable.
+ */
+export const DEFAULT_ROUTER_LABELS = [
+    // NONE — agent meta, smalltalk, test pings
+    `${ROUTE_NONE}: meta-question about the agent itself, session identifier, system test, simple greeting, weather, or trivial smalltalk that does not depend on the knowledge base`,
+    // PGVECTOR_ONLY — single-document factual lookup
+    `${ROUTE_PGVECTOR_ONLY}: factual lookup that can be answered by a single document excerpt — version numbers, file names, dates, configuration values, raw quotes`,
+    // LIGHTRAG_ONLY — entity-relation traversal
+    `${ROUTE_LIGHTRAG_ONLY}: knowledge graph question about entities and their relationships — which client, which coach, which mission, which programme links to which livrable`,
+    // ALL — broad / synthesizing / unclear
+    `${ROUTE_ALL}: broad synthesis, multi-hop reasoning, audit, comparison, or any question whose scope is unclear and benefits from both vector search and knowledge graph context`,
+];
+/**
+ * The label names that the classifier may legitimately return.
+ * Used by the defensive parser to refuse hallucinated classes.
+ */
+export const ROUTER_LABEL_NAMES = [
+    ROUTE_NONE,
+    ROUTE_PGVECTOR_ONLY,
+    ROUTE_LIGHTRAG_ONLY,
+    ROUTE_ALL,
+];
+/**
+ * Extract the route name from a full label string (the part before the
+ * colon). Returns `null` when the label is malformed.
+ *
+ * @internal exported for unit testing
+ */
+export function extractRouteFromLabel(label) {
+    const colonIndex = label.indexOf(":");
+    if (colonIndex <= 0)
+        return null;
+    const name = label.slice(0, colonIndex).trim();
+    return name.length > 0 ? name : null;
+}
+//# sourceMappingURL=labels.js.map

package/dist/router/labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.js","sourceRoot":"","sources":["../../src/router/labels.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,kEAAkE;AAClE,wDAAwD;AACxD,EAAE;AACF,sEAAsE;AACtE,wEAAwE;AACxE,qEAAqE;AACrE,mEAAmE;AACnE,8DAA8D;AAC9D,qFAAqF;AAErF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC;AACjC,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAC;AACnD,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAC;AACnD,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,2CAA2C;IAC3C,GAAG,UAAU,oKAAoK;IAEjL,iDAAiD;IACjD,GAAG,mBAAmB,2IAA2I;IAEjK,4CAA4C;IAC5C,GAAG,mBAAmB,uJAAuJ;IAE7K,uCAAuC;IACvC,GAAG,SAAS,oKAAoK;CACjL,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAsB;IACnD,UAAU;IACV,mBAAmB;IACnB,mBAAmB;IACnB,SAAS;CACV,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACjC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/C,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACvC,CAAC"}

package/dist/router/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The four mutually exclusive routes the router can pick.
+ *
+ *   - `NONE`            — skip every source. Used for heartbeats, cron,
+ *                          memory triggers, agent meta-questions, system
+ *                          tests. Saves the cost of an irrelevant retrieval.
+ *   - `PGVECTOR_ONLY`   — vector search only (no graph). Cheap factual
+ *                          lookups: file names, version numbers, simple
+ *                          excerpts.
+ *   - `LIGHTRAG_ONLY`   — knowledge graph only (no vectors). Multi-hop
+ *                          reasoning, entity-relationship queries.
+ *   - `ALL`             — both sources in parallel. The current default
+ *                          behavior; preserved when the router is disabled.
+ */
+export type Route = "NONE" | "PGVECTOR_ONLY" | "LIGHTRAG_ONLY" | "ALL";
+/** Source of a router decision — used in logs to trace the reasoning path. */
+export type RouterReason = "router_disabled" | "heuristic_trigger" | "heuristic_meta" | "heuristic_short" | "heuristic_keyword" | "classifier_hit" | "classifier_fallback" | "classifier_error";
+export interface RouterDecision {
+    route: Route;
+    reason: RouterReason;
+    /** Confidence in [0, 1] when the classifier produced a score, else null. */
+    score: number | null;
+}

package/dist/router/types.js

@@ -0,0 +1,7 @@
+// Router types — shared by heuristic + classifier paths.
+//
+// The router decides which knowledge sources should be queried for a given
+// user turn. The decision is consumed by the `before_prompt_build` handler
+// to gate calls to pgvector and LightRAG.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/router/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/router/types.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,0CAA0C"}

package/dist/tracing/events.d.ts

@@ -0,0 +1,83 @@
+import type { Route, RouterReason } from "../router/types.js";
+/**
+ * Minimal logger surface used by this module. Matches the relevant subset of
+ * `PluginLogger` from the OpenClaw SDK so it can be unit-tested without
+ * importing the full SDK type graph.
+ */
+export interface TracingLogger {
+    info: (message: string) => void;
+    debug?: (message: string) => void;
+}
+/**
+ * Marker prefix for every structured line emitted by this module. Pick a
+ * value that is unlikely to clash with other plugins and stable across
+ * versions — log scrapers and Opik rules depend on it.
+ */
+export declare const EVENT_PREFIX = "[knowledge.event]";
+export interface RouterEvent {
+    type: "router";
+    route: Route;
+    reason: RouterReason;
+    score: number | null;
+    queryLength: number;
+    trigger?: string;
+}
+export interface PgvectorEvent {
+    type: "pgvector";
+    collections: string[];
+    rawCount: number;
+    rerankedCount: number | null;
+    topScore: number | null;
+    durationMs: number;
+}
+export interface LightRAGEvent {
+    type: "lightrag";
+    mode: string;
+    contextChars: number;
+    truncatedChars: number;
+    durationMs: number;
+}
+export interface JinaUsageEvent {
+    type: "jina";
+    endpoint: "classify" | "rerank";
+    model: string;
+    durationMs: number;
+    inputCount: number;
+}
+export interface CooldownEvent {
+    type: "cooldown";
+    scope: "global" | "router" | "pgvector_reranker";
+    consecutiveErrors: number;
+}
+export type KnowledgeEvent = RouterEvent | PgvectorEvent | LightRAGEvent | JinaUsageEvent | CooldownEvent;
+/**
+ * Emit a structured event line through `logger.info`.
+ *
+ * Never throws. If JSON serialization or the logger itself fails (e.g.
+ * upstream broke the contract), we silently swallow — the plugin must keep
+ * working even if tracing breaks.
+ */
+export declare function emitEvent(logger: TracingLogger, event: KnowledgeEvent): void;
+/**
+ * Optional debug-level emission of turn metadata for correlation.
+ *
+ * What goes into the log line:
+ *   - `runId`: the OpenClaw SDK's runId for this agent turn (or
+ *              `"unknown"` when the SDK did not supply one). This is the
+ *              ONLY correlation key we expose — it is non-query-derived
+ *              by construction, so it cannot be dictionary-recovered
+ *              from the log line.
+ *   - `qlen`:  character length of the query (a count, not content).
+ *
+ * What does NOT go in: any portion of the query text, AND no hash of it.
+ * An earlier iteration of this plugin emitted `SHA-256(query)` truncated
+ * to 12 hex chars under the assumption it was "non-reversible". Code
+ * review (2026-05-23) correctly pointed out that for short or low-entropy
+ * prompts (the hook accepts ≥ 3 chars), the hash is dictionary-recoverable
+ * offline. We removed the hash entirely and rely on `runId` instead.
+ *
+ * Operators who want CONTENT correlation across turns must instrument
+ * Opik / LangFuse at the SDK layer with their own keyed scheme (HMAC
+ * with a deployment secret); the plugin will not do it for them.
+ */
+export declare function emitTurnMetadata(logger: TracingLogger, runId: string | undefined, queryLength: number): void;

package/dist/tracing/events.js

@@ -0,0 +1,86 @@
+// Structured event emission for downstream observability tools.
+//
+// The plugin already runs inside an OpenClaw deployment that includes Opik
+// (https://www.comet.com/docs/opik/) for tracing — but the plugin itself
+// MUST NOT depend on the Opik SDK directly. Two reasons:
+//
+//   1. Deps. The plugin proudly ships with a single runtime dep (`pg`).
+//      Adding `opik` would force every consumer to install it.
+//   2. Coupling. Operators may swap Opik for LangFuse or pure OTLP. The
+//      plugin should not care.
+//
+// Solution: emit structured JSON lines through OpenClaw's logger. The
+// upstream gateway already forwards `logger.info(...)` to Opik (when
+// configured) and to stdout in any case. A grep-friendly prefix
+// (`[knowledge.event]`) lets a downstream scraper or Opik rule pick the
+// records out without ambiguity.
+//
+// Privacy invariant: NO event in this module ever logs the raw user
+// query, query excerpts, retrieved chunk content, OR ANY HASH OF THEM.
+// We log metadata only (lengths, scores, counts, durations) plus the
+// `runId` provided by the OpenClaw SDK when turn-level correlation is
+// needed. The runId is non-query-derived by construction, so it cannot
+// be reversed offline against a dictionary of likely prompts.
+//
+// The events module is intentionally tiny and synchronous — emitting a log
+// line must NEVER throw, NEVER consume noticeable CPU, and NEVER hold the
+// agent turn open.
+/**
+ * Marker prefix for every structured line emitted by this module. Pick a
+ * value that is unlikely to clash with other plugins and stable across
+ * versions — log scrapers and Opik rules depend on it.
+ */
+export const EVENT_PREFIX = "[knowledge.event]";
+// ---------------------------------------------------------------------------
+// Emitters
+// ---------------------------------------------------------------------------
+/**
+ * Emit a structured event line through `logger.info`.
+ *
+ * Never throws. If JSON serialization or the logger itself fails (e.g.
+ * upstream broke the contract), we silently swallow — the plugin must keep
+ * working even if tracing breaks.
+ */
+export function emitEvent(logger, event) {
+    try {
+        const payload = JSON.stringify(event);
+        logger.info(`${EVENT_PREFIX} ${payload}`);
+    }
+    catch {
+        // intentional swallow — tracing must never crash the plugin
+    }
+}
+/**
+ * Optional debug-level emission of turn metadata for correlation.
+ *
+ * What goes into the log line:
+ *   - `runId`: the OpenClaw SDK's runId for this agent turn (or
+ *              `"unknown"` when the SDK did not supply one). This is the
+ *              ONLY correlation key we expose — it is non-query-derived
+ *              by construction, so it cannot be dictionary-recovered
+ *              from the log line.
+ *   - `qlen`:  character length of the query (a count, not content).
+ *
+ * What does NOT go in: any portion of the query text, AND no hash of it.
+ * An earlier iteration of this plugin emitted `SHA-256(query)` truncated
+ * to 12 hex chars under the assumption it was "non-reversible". Code
+ * review (2026-05-23) correctly pointed out that for short or low-entropy
+ * prompts (the hook accepts ≥ 3 chars), the hash is dictionary-recoverable
+ * offline. We removed the hash entirely and rely on `runId` instead.
+ *
+ * Operators who want CONTENT correlation across turns must instrument
+ * Opik / LangFuse at the SDK layer with their own keyed scheme (HMAC
+ * with a deployment secret); the plugin will not do it for them.
+ */
+export function emitTurnMetadata(logger, runId, queryLength) {
+    if (!logger.debug)
+        return;
+    try {
+        const id = runId && runId.length > 0 ? runId : "unknown";
+        logger.debug(`${EVENT_PREFIX} turn.metadata runId=${id} qlen=${queryLength}`);
+    }
+    catch {
+        // swallow — tracing must never crash the plugin
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/tracing/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/tracing/events.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,2EAA2E;AAC3E,yEAAyE;AACzE,yDAAyD;AACzD,EAAE;AACF,wEAAwE;AACxE,+DAA+D;AAC/D,wEAAwE;AACxE,+BAA+B;AAC/B,EAAE;AACF,sEAAsE;AACtE,qEAAqE;AACrE,gEAAgE;AAChE,wEAAwE;AACxE,iCAAiC;AACjC,EAAE;AACF,oEAAoE;AACpE,uEAAuE;AACvE,qEAAqE;AACrE,sEAAsE;AACtE,uEAAuE;AACvE,8DAA8D;AAC9D,EAAE;AACF,2EAA2E;AAC3E,0EAA0E;AAC1E,mBAAmB;AAcnB;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAqDhD,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,MAAqB,EAAE,KAAqB;IACpE,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACtC,MAAM,CAAC,IAAI,CAAC,GAAG,YAAY,IAAI,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,4DAA4D;IAC9D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAqB,EACrB,KAAyB,EACzB,WAAmB;IAEnB,IAAI,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO;IAC1B,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACzD,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,wBAAwB,EAAE,SAAS,WAAW,EAAE,CAAC,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,gDAAgD;IAClD,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -1,3 +1,25 @@
+import type { RerankerModel } from "./jina/types.js";
+/**
+ * Subset of `PluginHookAgentContext` from the OpenClaw plugin SDK that this
+ * plugin actually consumes. Declared locally to keep the test suite free of
+ * SDK runtime imports.
+ *
+ * Fields beyond this subset (workspaceDir, modelProviderId, ...) are
+ * deliberately omitted — the handler does not depend on them.
+ *
+ * @see https://github.com/openclaw/openclaw plugin-sdk types.d.ts
+ */
+export interface PluginHookAgentContext {
+    /** What initiated this agent run. */
+    trigger?: "user" | "heartbeat" | "cron" | "memory" | string;
+    /** Channel-derived sender id. The plugin currently only uses `"cli"`. */
+    messageProvider?: string;
+    channelId?: string;
+    agentId?: string;
+    sessionId?: string;
+    sessionKey?: string;
+    runId?: string;
+}
 /**
  * Runtime configuration as it appears in `plugins.entries.openclaw-knowledge.config`.
  * All fields are optional — defaults are applied in {@link resolveConfig}.
@@ -16,6 +38,30 @@ export interface KnowledgePluginConfig {
     lightragQueryMode?: LightRAGQueryMode;
     lightragMaxChars?: number;
     lightragEnabled?: boolean;
+    jina?: JinaPluginConfig;
+}
+export interface JinaPluginConfig {
+    /** Jina API key. Required for `router.mode=jina-classifier` or `pgvectorReranker.enabled`. Supports `${ENV_VAR}` substitution. */
+    apiKey?: string;
+    router?: RouterPluginConfig;
+    pgvectorReranker?: PgvectorRerankerPluginConfig;
+}
+export interface RouterPluginConfig {
+    enabled?: boolean;
+    mode?: "heuristic" | "jina-classifier";
+    /**
+     * Optional pre-trained Jina classifier_id. When set, the router calls
+     * `/v1/classify` with this ID (few-shot mode). Train it out-of-band via
+     * `POST /v1/train` — the plugin does NOT implement training.
+     */
+    classifierId?: string;
+}
+export interface PgvectorRerankerPluginConfig {
+    enabled?: boolean;
+    /** Reranker model. Default: `jina-reranker-v2-base-multilingual` (best FR coverage). */
+    model?: RerankerModel;
+    /** Cap on results returned post-rerank. Default: `5`. */
+    topN?: number;
 }
 export type LightRAGQueryMode = "naive" | "local" | "global" | "hybrid";
 /**
@@ -36,6 +82,13 @@ export interface ResolvedKnowledgeConfig {
     lightragQueryMode: LightRAGQueryMode;
     lightragMaxChars: number;
     lightragEnabled: boolean;
+    jinaApiKey: string;
+    routerEnabled: boolean;
+    routerMode: "heuristic" | "jina-classifier";
+    routerClassifierId: string;
+    pgvectorRerankerEnabled: boolean;
+    pgvectorRerankerModel: RerankerModel;
+    pgvectorRerankerTopN: number;
 }
 /**
  * One search hit from the PostgreSQL `knowledge_vectors` table, after score
@@ -85,9 +138,16 @@ export interface PgvectorRow {
 }
 /**
  * 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.
+ *
+ * As of v3.2.1, `prompt` is the PRIMARY source for the user query — it is
+ * the raw user text surfaced by the SDK, distinct from `messages` which may
+ * aggregate the full conversation window (with summaries, system prompt
+ * fragments, etc.). The handler reads `prompt` first; `messages` remains
+ * as a legacy fallback for SDK versions that do not populate it.
  */
 export interface BeforePromptBuildEvent {
+    /** Raw user prompt for this turn. SDK >= 2026.5.0. */
+    prompt?: string;
     messages?: PromptMessage[];
 }
 export interface PromptMessage {

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "id": "openclaw-knowledge",
   "name": "Knowledge Base",
-  "description": "Multi-source knowledge search (pgvector + LightRAG) — injects relevant documents and knowledge graph context before each turn via the before_prompt_build hook",
-  "version": "3.1.2",
+  "description": "Multi-source knowledge search (pgvector + LightRAG) with optional Jina-powered router & reranker — injects relevant documents and knowledge graph context before each turn via the before_prompt_build hook",
+  "version": "3.2.1",
   "activation": {
     "onStartup": true
   },
@@ -34,7 +34,7 @@
         "minimum": 1,
         "maximum": 100,
         "default": 5,
-        "description": "Maximum number of results returned per collection"
+        "description": "Maximum number of results returned per collection (raw recall stage)"
       },
       "scoreThreshold": {
         "type": "number",
@@ -76,6 +76,63 @@
       "lightragEnabled": {
         "type": "boolean",
         "description": "Disable LightRAG search while keeping pgvector. Defaults to true when lightragUrl is set."
+      },
+      "jina": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "Optional Jina-powered enhancements: router (skip irrelevant retrievals) and pgvector reranker (re-order vector results by cross-encoder relevance).",
+        "properties": {
+          "apiKey": {
+            "type": "string",
+            "description": "Jina API key shared by router and reranker. Required when router.mode=jina-classifier or pgvectorReranker.enabled. Supports ${ENV_VAR} substitution."
+          },
+          "router": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Adaptive routing: classify each user turn and skip retrieval when irrelevant.",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": false,
+                "description": "Enable the router. When false (default), every eligible turn calls every configured source — pre-3.2.0 behavior."
+              },
+              "mode": {
+                "type": "string",
+                "enum": ["heuristic", "jina-classifier"],
+                "default": "heuristic",
+                "description": "heuristic: zero-cost regex + trigger rules only (safe start). jina-classifier: same heuristics first, then Jina /v1/classify for ambiguous queries."
+              },
+              "classifierId": {
+                "type": "string",
+                "description": "Optional pre-trained Jina classifier_id (few-shot mode). Train it out-of-band via POST /v1/train then paste the ID here. When omitted, the router uses zero-shot with built-in labels."
+              }
+            }
+          },
+          "pgvectorReranker": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Re-order pgvector results with a Jina cross-encoder. Boosts precision when topK candidates contain noise.",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": false,
+                "description": "Enable cross-encoder rerank on pgvector results. Requires jina.apiKey."
+              },
+              "model": {
+                "type": "string",
+                "default": "jina-reranker-v2-base-multilingual",
+                "description": "Jina reranker model. v2-base-multilingual is recommended for French content (v3 is English-biased)."
+              },
+              "topN": {
+                "type": "number",
+                "minimum": 1,
+                "maximum": 100,
+                "default": 5,
+                "description": "Max number of results returned after rerank. Recommendation: keep topK ≥ topN × 2 so the cross-encoder has room to re-order."
+              }
+            }
+          }
+        }
       }
     },
     "required": []
@@ -105,7 +162,7 @@
     "topK": {
       "label": "Top-K per collection",
       "advanced": true,
-      "help": "Maximum number of results returned per collection (default: 5)"
+      "help": "Maximum number of results returned per collection (default: 5). When the reranker is enabled, recommended ≥ 2× rerank topN."
     },
     "scoreThreshold": {
       "label": "Score threshold",
@@ -147,6 +204,42 @@
       "label": "Enable LightRAG source",
       "advanced": true,
       "help": "Disable LightRAG while keeping pgvector. Defaults to true when lightragUrl is set."
+    },
+    "jina.apiKey": {
+      "label": "Jina API Key",
+      "placeholder": "${JINA_API_KEY}",
+      "sensitive": true,
+      "help": "Shared by router and reranker. Use ${JINA_API_KEY} for env var substitution."
+    },
+    "jina.router.enabled": {
+      "label": "Enable router",
+      "advanced": true,
+      "help": "Adaptive routing that skips retrieval on heartbeats and meta-questions. Default: false (pre-3.2.0 behavior)."
+    },
+    "jina.router.mode": {
+      "label": "Router mode",
+      "advanced": true,
+      "help": "heuristic: zero-cost rules only. jina-classifier: heuristics + Jina /v1/classify fallback."
+    },
+    "jina.router.classifierId": {
+      "label": "Few-shot classifier ID",
+      "advanced": true,
+      "help": "Optional. When set, the router uses your pre-trained classifier instead of zero-shot labels."
+    },
+    "jina.pgvectorReranker.enabled": {
+      "label": "Enable pgvector reranker",
+      "advanced": true,
+      "help": "Cross-encoder re-ordering of pgvector results. Requires Jina API key."
+    },
+    "jina.pgvectorReranker.model": {
+      "label": "Reranker model",
+      "advanced": true,
+      "help": "Default: jina-reranker-v2-base-multilingual (best for French)."
+    },
+    "jina.pgvectorReranker.topN": {
+      "label": "Reranker top-N",
+      "advanced": true,
+      "help": "Max results returned after rerank. Keep topK ≥ topN × 2."
     }
   }
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@lacneu/openclaw-knowledge",
-  "version": "3.1.2",
+  "version": "3.2.1",
   "type": "module",
-  "description": "Multi-source knowledge plugin for OpenClaw — pgvector + LightRAG injection via before_prompt_build hook",
+  "description": "Multi-source knowledge plugin for OpenClaw — pgvector + LightRAG injection with optional Jina-powered router & reranker, via before_prompt_build hook",
   "license": "MIT",
   "author": "Olivier Neu",
   "homepage": "https://github.com/OlivierNeu/openclaw-knowledge-plugin#readme",
@@ -40,7 +40,7 @@
     "build:test": "tsc -p tsconfig.test-build.json",
     "clean": "rm -rf dist dist-test",
     "typecheck": "tsc -p tsconfig.test.json",
-    "test": "npm run build:test && node --test dist-test/test/*.test.js",
+    "test": "npm run build:test && node --test $(find dist-test/test -name '*.test.js' -print)",
     "prepublishOnly": "npm run clean && npm run build"
   },
   "openclaw": {