@lacneu/openclaw-knowledge 3.1.0

package/CHANGELOG.md

@@ -0,0 +1,159 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [3.1.0] - 2026-04-10
+
+### Changed
+- **Distribution migrated to npm as `@lacneu/openclaw-knowledge`.** The plugin
+  is now published to the public npm registry under the `lacneu` organization
+  and installs via the official OpenClaw CLI:
+  ```bash
+  openclaw plugins install @lacneu/openclaw-knowledge
+  openclaw plugins update  @lacneu/openclaw-knowledge
+  ```
+  OpenClaw tracks the install under `plugins.installs`, so `openclaw plugins update`
+  works out of the box — no custom deployment script required.
+- `package.json` renamed to the scoped package `@lacneu/openclaw-knowledge`
+  and now declares `publishConfig.access: "public"`, a narrow `files` allowlist
+  (dist, manifest, README, CHANGELOG, LICENSE), `repository`, `homepage`, `bugs`
+  and `keywords` metadata for discoverability on npmjs.com.
+- GitHub Actions release workflow now runs `npm publish --access public` via
+  **npm Trusted Publishing (OIDC)** — no `NPM_TOKEN` secret needed. The workflow
+  requests an OIDC token from GitHub, exchanges it for a short-lived npm
+  credential scoped to this repo + workflow, and ships a provenance statement
+  with every release (automatic with Trusted Publishing, `--provenance` flag no
+  longer needed). No bundled tarball artifact — the GitHub Release is still
+  created for changelog visibility but carries no files.
+- **Full migration to TypeScript + the official OpenClaw plugin SDK.** The plugin now
+  uses `definePluginEntry` from `openclaw/plugin-sdk/plugin-entry` as the canonical
+  entry point, replacing the bare `{ id, name, register }` object export.
+- Source code is split into focused modules under `src/`:
+  `index.ts` (entry + hook wiring), `config.ts` (resolveEnv + defaults),
+  `embeddings.ts` (Gemini client), `pgvector.ts` (PostgreSQL search + formatter),
+  `lightrag.ts` (LightRAG client + truncation), `types.ts` (shared interfaces).
+- Tests migrated to TypeScript under `test/*.test.ts` using `node:test`.
+  Coverage trimmed to 56 tests after removing legacy-shape test cases.
+- Business logic is **unchanged**: same hook (`before_prompt_build`), same output
+  format (`### Document Search Results` + `### Knowledge Graph Context`), same
+  parallel execution via `Promise.allSettled`, same cooldown (3 errors → 5 min),
+  same Gemini native `embedContent` endpoint, same `halfvec(3072)` SQL cast.
+- Current plugin configurations (Olivier and Jerome instances) continue to work
+  without any changes — all config keys and defaults are preserved. The breaking
+  changes below are limited to internal types and legacy input shapes that were
+  defensive cruft, not fields used by active deployments.
+
+### Added
+- `tsconfig.json` with strict mode (`noImplicitAny`, `noUnusedLocals`,
+  `noUnusedParameters`, `noImplicitReturns`, `noFallthroughCasesInSwitch`).
+- `tsconfig.test.json` and `tsconfig.test-build.json` for typecheck and test compilation.
+- `npm run build`, `npm run typecheck`, `npm run clean` scripts.
+- `@types/node`, `@types/pg`, `typescript`, and `openclaw` (for SDK types) as
+  `devDependencies`.
+- Release workflow now runs `npm run typecheck`, `npm run build`, then prunes to
+  production dependencies before bundling. The release tarball ships the compiled
+  `dist/` directory rather than raw source.
+- CI workflow runs typecheck, tests, and build on Node.js 22 and 24.
+
+### Removed (BREAKING)
+- `index.js` and `index.test.js` at the repository root (replaced by `src/` and `test/`).
+- Legacy message shapes in `extractQueryFromMessages`: the `sender` field (alias
+  for `role`), the `"human"` role alias, and the `{text: "..."}` fallback form
+  are no longer recognized. Only the canonical `{role, content}` shape is accepted,
+  where `content` is a `string` or an array of `{type, text}` parts.
+- Legacy LightRAG response shapes in `queryLightRAG`: plain string responses and
+  `{context: ...}` payloads are no longer normalized. Only the current
+  `{response: string}` shape is supported (LightRAG 1.4.x+).
+- `PromptMessage.sender`, `PromptMessage.text`, and the `[key: string]: unknown`
+  index signatures on `PromptMessage` and `PromptContentPart` are removed from
+  the exported types. Strict structural typing only.
+- `truncateLightRAG(text: string | null | undefined, ...)` tightened to
+  `truncateLightRAG(text: string, ...)`. Callers must pre-check for non-empty.
+- `resolveConfig(raw: KnowledgePluginConfig | null | undefined)` tightened to
+  `resolveConfig(cfg?: KnowledgePluginConfig)`. Pass `{}` or no argument instead
+  of `null` / `undefined`.
+- `PgvectorRow.score` type tightened from `string | number` to `string` (matches
+  actual `pg` driver behaviour for numeric columns).
+
+### Previous [Unreleased] entries (now folded into this TS migration)
+- `package.json` now declares `openclaw.compat.pluginApi` and `openclaw.compat.minGatewayVersion`
+  so OpenClaw can validate compatibility before loading the plugin.
+- Full `uiHints` coverage in `openclaw.plugin.json` for every config field (labels, placeholders,
+  `sensitive: true` on secrets, `advanced: true` on tuning knobs).
+- JSON Schema constraints in `configSchema`: `default`, `minimum`/`maximum` on numeric fields,
+  `enum` on `lightragQueryMode`, explicit `default` on `enabled`, `topK`, `scoreThreshold`,
+  `maxInjectChars`, `lightragMaxChars`, `lightragQueryMode` and `collections`.
+- Manifest `description` updated to explicitly mention the `before_prompt_build` hook.
+- `peerDependencies.openclaw` bumped to `>=2026.3.7` to match the hook requirement already
+  stated in the README.
+
+## [3.0.4] - 2026-04-10
+
+### Fixed
+- Release tarball now bundles `node_modules` with the `pg` dependency, eliminating
+  the need for `npm install` at deployment time. Previously, runtime `npm install`
+  would silently fail on Docker installations with tmpfs cache conflicts, leaving
+  the plugin unable to load (`Cannot find module 'pg'`).
+
+### Changed
+- `update-knowledge-plugin.sh` simplified: no longer runs `npm install` on target
+  containers, only verifies that bundled dependencies are present.
+
+## [1.2.0] - 2026-03-30
+
+### Changed
+- Reverted hook from `before_prompt_build` back to `before_agent_start` for broader compatibility.
+- Changed context injection from `appendSystemContext` to `prependContext` with `<relevant-documents>` tagging.
+- Added logic to prevent memory pollution by `autoCapture`.
+
+### Fixed
+- Release workflow now stamps version from tag into `package.json` and `openclaw.plugin.json` before building artifact.
+- Improved logging: removed noisy event keys log, added query length and preview logging.
+
+## [1.1.2] - 2026-03-30
+
+### Fixed
+- Enhanced logging in `before_prompt_build` hook: capture event keys and improve query handling logic.
+
+## [1.1.1] - 2026-03-30
+
+### Changed
+- Stabilized hook naming: renamed from `before_agent_start` to `before_prompt_build`.
+- Updated test cases to reflect new hook names.
+- Streamlined query handling and improved context injection logic.
+
+## [1.1.0] - 2026-03-30
+
+### Changed
+- Switched hook from `before_agent_start` to `before_prompt_build`.
+- Changed injection mechanism from `prependContext` to `appendSystemContext` for system prompt handling.
+- Expanded README with installation and update guidance.
+
+## [1.0.0] - 2026-03-30
+
+### Added
+- Multi-collection Qdrant vector search via `before_agent_start` hook.
+- Query embedding using Gemini Embedding 2 Preview (3072 dimensions, cross-modal compatible).
+- Parallel search across multiple Qdrant collections.
+- Results sorted by similarity score, injected as `<relevant-documents>` block via `prependContext`.
+- Environment variable substitution in config values (`${VAR_NAME}` syntax).
+- Configurable score threshold, top-K, max injection size, and per-instance collection list.
+- Fail-safe error handling: errors never block the agent.
+- Cooldown mechanism: pauses 5 minutes after 3 consecutive failures.
+- Unit tests (26 tests) using Node.js built-in test runner (`node:test`).
+- CI workflow: tests on Node.js 18, 20, and 22.
+- Release workflow: creates GitHub Release with tarball on tag push.
+- Architecture, lifecycle, and sequence diagrams in `schemas/`.
+
+[Unreleased]: https://github.com/OlivierNeu/openclaw-knowledge-plugin/compare/v3.1.0...HEAD
+[3.1.0]: https://github.com/OlivierNeu/openclaw-knowledge-plugin/compare/v1.2.0...v3.1.0
+[1.2.0]: https://github.com/OlivierNeu/openclaw-knowledge-plugin/compare/v1.1.2...v1.2.0
+[1.1.2]: https://github.com/OlivierNeu/openclaw-knowledge-plugin/compare/v1.1.1...v1.1.2
+[1.1.1]: https://github.com/OlivierNeu/openclaw-knowledge-plugin/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/OlivierNeu/openclaw-knowledge-plugin/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/OlivierNeu/openclaw-knowledge-plugin/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OlivierNeu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,424 @@
+# openclaw-knowledge-plugin
+
+> **Dual-source knowledge injection plugin for OpenClaw**
+> Automatically enriches agent prompts with relevant context from your document knowledge base,
+> combining **pgvector semantic search** and **LightRAG knowledge graph** in a single hook.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![OpenClaw](https://img.shields.io/badge/OpenClaw-%E2%89%A5v2026.3.7-blue)](https://github.com/openclaw/openclaw)
+[![npm version](https://img.shields.io/npm/v/@lacneu/openclaw-knowledge.svg)](https://www.npmjs.com/package/@lacneu/openclaw-knowledge)
+
+---
+
+## Overview
+
+`openclaw-knowledge` is an OpenClaw plugin that automatically injects relevant
+documents and knowledge graph context into every agent turn. It hooks into
+`before_prompt_build` and queries **two complementary sources in parallel**:
+
+| Source | Technology | What it provides |
+|--------|------------|------------------|
+| **pgvector** | PostgreSQL + `pgvector` extension | Semantic vector search on document chunks (cosine similarity on 3072-dim embeddings) |
+| **LightRAG** | Neo4j + PostgreSQL | Knowledge graph with entity/relation multi-hop traversal |
+
+Both sources run **in parallel** via `Promise.allSettled`, so a failure in one
+source doesn't block the other. Results are merged and injected into the agent's
+system prompt via `appendSystemContext`.
+
+---
+
+## Why two sources?
+
+Vector search and knowledge graphs answer different kinds of questions:
+
+- **Vector search** finds passages that are **semantically similar** to the query.
+  Good for "What did the meeting say about pricing?" — matches embeddings.
+- **Knowledge graph** finds entities and **their relationships**.
+  Good for "Which clients work in the insurance sector?" — traverses entity links.
+
+Running both gives the agent both capabilities simultaneously, without requiring
+the LLM to decide which to use.
+
+---
+
+## Architecture
+
+![System architecture](schemas/system-architecture.png)
+
+The plugin is the **query layer** of a larger knowledge pipeline:
+
+1. **Ingestion (background, via n8n):** Google Drive documents are polled,
+   OCR'd via Mistral, embedded via Gemini, and stored in PostgreSQL (`pgvector`)
+   and Neo4j (LightRAG knowledge graph).
+2. **Query (real-time, via this plugin):** Every user message triggers a
+   parallel search in both sources, results are formatted and prepended to
+   the agent's prompt.
+
+The plugin does **not** handle ingestion — that's the responsibility of the n8n
+ETL pipeline. This plugin only reads from the existing data stores.
+
+---
+
+## Query lifecycle
+
+![Runtime sequence](schemas/runtime-sequence.png)
+
+Every user message triggers the following sequence:
+
+1. OpenClaw fires `before_prompt_build` with the user's prompt
+2. The plugin checks its **cooldown state** (pauses 5 min after 3 consecutive errors)
+3. Query text is extracted and validated (≥ 3 characters)
+4. **In parallel** (`Promise.allSettled`):
+   - **pgvector path:** embed query via Gemini → SQL search on `knowledge_vectors`
+   - **LightRAG path:** POST `/query` with `mode=hybrid` to the LightRAG server
+5. Results are merged and truncated to `maxInjectChars`
+6. Formatted blocks (`### Document Search Results` + `### Knowledge Graph Context`)
+   are injected via `appendSystemContext`
+7. The agent receives the enriched prompt and generates its response
+
+---
+
+## Decision flow
+
+![Plugin lifecycle](schemas/plugin-lifecycle-flowchart.png)
+
+The plugin implements several safeguards to ensure it never blocks the agent:
+
+| Safeguard | Purpose |
+|-----------|---------|
+| **Cooldown** (3 errors → 5 min pause) | Avoid log spam and unnecessary API calls during outages |
+| **Query length check** (≥ 3 chars) | Skip meaningless searches |
+| **`Promise.allSettled`** for sources | A failure in one source doesn't affect the other |
+| **Silent error handling** | Errors are logged but never thrown to the agent |
+| **Gracefull degradation** | If both sources fail, the agent runs as if the plugin weren't there |
+
+---
+
+## Installation
+
+### Requirements
+
+- OpenClaw ≥ `v2026.3.7` (for `before_prompt_build` hook)
+- PostgreSQL with `pgvector` extension
+- LightRAG server (optional — plugin works with pgvector alone)
+- Gemini API key (for query embedding)
+
+### Install via OpenClaw CLI (recommended)
+
+The plugin is published on npm as `@lacneu/openclaw-knowledge`. Use the
+official `openclaw plugins` commands — install, update, list, inspect all
+work out of the box:
+
+```bash
+# Install (pulls the latest version from npm)
+openclaw plugins install @lacneu/openclaw-knowledge
+
+# Inspect the installed version and manifest
+openclaw plugins inspect @lacneu/openclaw-knowledge
+
+# Update to the latest published version
+openclaw plugins update @lacneu/openclaw-knowledge
+
+# List everything installed
+openclaw plugins list
+```
+
+OpenClaw tracks the install source under `plugins.installs` in your
+configuration, so subsequent `update` calls know where to fetch new versions
+from.
+
+### Configuration
+
+Add to your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "allow": ["openclaw-knowledge", "hindsight-openclaw", "telegram"],
+    "entries": {
+      "openclaw-knowledge": {
+        "enabled": true,
+        "config": {
+          "geminiApiKey": "${GEMINI_API_KEY}",
+          "postgresUrl": "postgresql://user:${POSTGRES_PASSWORD}@postgresql:5432/knowledge",
+          "collections": ["knowledge_alice"],
+          "topK": 5,
+          "scoreThreshold": 0,
+          "maxInjectChars": 4000,
+          "lightragUrl": "http://lightrag:9621",
+          "lightragApiKey": "${LIGHTRAG_API_KEY}",
+          "lightragQueryMode": "hybrid",
+          "lightragMaxChars": 4000
+        }
+      }
+    }
+  }
+}
+```
+
+Then restart the gateway:
+
+```bash
+openclaw gateway restart
+```
+
+---
+
+## Configuration reference
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `enabled` | boolean | `true` | Master switch for the plugin |
+| **pgvector source** | | | |
+| `geminiApiKey` | string | — | Gemini API key for query embedding (supports `${ENV_VAR}`) |
+| `postgresUrl` | string | — | PostgreSQL connection URL (supports `${ENV_VAR}`) |
+| `collections` | string[] | `["knowledge_default"]` | Collections to search in `knowledge_vectors` table |
+| `topK` | number | `5` | Max results per collection |
+| `scoreThreshold` | number | `0.3` | Minimum cosine similarity (0–1) |
+| `maxInjectChars` | number | `4000` | Character budget for pgvector results |
+| `pgvectorEnabled` | boolean | `true` if `geminiApiKey` set | Disable pgvector while keeping LightRAG |
+| **LightRAG source** | | | |
+| `lightragUrl` | string | — | LightRAG server base URL |
+| `lightragApiKey` | string | — | LightRAG API key (supports `${ENV_VAR}`) |
+| `lightragQueryMode` | string | `"hybrid"` | Query mode: `naive`, `local`, `global`, `hybrid` |
+| `lightragMaxChars` | number | `4000` | Character budget for LightRAG context |
+| `lightragEnabled` | boolean | `true` if `lightragUrl` set | Disable LightRAG while keeping pgvector |
+
+### LightRAG query modes
+
+| Mode | Description | Best for |
+|------|-------------|----------|
+| `naive` | Simple vector similarity on chunks | Fast, basic keyword matching |
+| `local` | Entity neighborhood traversal | Questions about a specific entity |
+| `global` | Community summaries | Broad, overview questions |
+| `hybrid` | Combines local + global | **Recommended for most cases** |
+
+---
+
+## Data model
+
+### pgvector: `knowledge_vectors` table
+
+The plugin expects a PostgreSQL table with this structure:
+
+```sql
+CREATE TABLE knowledge_vectors (
+  id SERIAL PRIMARY KEY,
+  collection TEXT NOT NULL,
+  file_name TEXT,
+  mime_type TEXT,
+  text TEXT,
+  file_id TEXT,
+  source TEXT,
+  owner TEXT,
+  chunk_index INTEGER,
+  total_chunks INTEGER,
+  timestamp_start TEXT,
+  timestamp_end TEXT,
+  embedded_at TIMESTAMPTZ,
+  embedding vector(3072) NOT NULL
+);
+
+CREATE INDEX idx_knowledge_vectors_hnsw
+  ON knowledge_vectors
+  USING hnsw ((embedding::halfvec(3072)) halfvec_cosine_ops);
+```
+
+**Important:** The HNSW index must use `halfvec(3072)` because pgvector's HNSW
+index has a 2000-dimension limit for the native `vector` type. `halfvec`
+supports up to 4000 dimensions. The plugin query casts both the column and the
+parameter accordingly.
+
+### Embeddings
+
+- **Model:** `gemini-embedding-2-preview` via the native Gemini API
+- **Dimensions:** 3072
+- **Distance metric:** cosine similarity
+- **Query endpoint:** the plugin uses the **native** `embedContent` endpoint
+  (not the OpenAI-compatible one), because the native endpoint supports
+  multimodal embedding at ingestion time while still working for text queries.
+
+### LightRAG query
+
+The plugin sends a POST request:
+
+```http
+POST /query HTTP/1.1
+X-API-Key: <lightragApiKey>
+Content-Type: application/json
+
+{
+  "query": "<user message>",
+  "mode": "hybrid",
+  "only_need_context": true
+}
+```
+
+`only_need_context: true` tells LightRAG to return the retrieved context
+**without** running the final LLM synthesis — the plugin only needs the
+raw context to inject into the agent's prompt.
+
+---
+
+## Multi-tenant support
+
+Each OpenClaw instance can configure its own set of collections:
+
+```json
+// Alice's instance
+"collections": ["knowledge_alice", "knowledge_shared"]
+
+// Bob's instance
+"collections": ["knowledge_bob", "knowledge_shared"]
+```
+
+All instances can share the same PostgreSQL database — isolation is done
+at the collection level. LightRAG, however, uses one instance per tenant
+(workspace isolation is not yet exposed in the plugin).
+
+---
+
+## Example output
+
+When the agent receives a user message, it sees something like this in its system prompt:
+
+```
+<existing system prompt>
+
+### Document Search Results (pgvector)
+
+[knowledge_alice] Contrat_Acme_Corp.pdf (score: 0.92, chunk 2/5)
+Service agreement between Alice Consulting and Acme Corp. Duration: 6 months,
+daily rate: 1500 EUR, start date: 2026-01-15, deliverables: strategy workshops,
+CODIR alignment sessions, monthly follow-ups...
+
+[knowledge_shared] Pricing_Grid_2026.pdf (score: 0.87, chunk 1/1)
+Standard pricing grid: senior consulting 1500 EUR/day, junior 900 EUR/day,
+workshops 3500 EUR/day flat...
+
+### Knowledge Graph Context (LightRAG)
+
+Entity: Acme Corp (Organization)
+  Relationships:
+  - Acme Corp → client_of → Alice Consulting (since 2026-01-15)
+  - Acme Corp → subject_of → Contrat_Acme_Corp.pdf
+  - Acme Corp → operates_in → Insurance sector
+  - Acme Corp → represented_by → Thomas Martin (Contact)
+
+User: What were the terms of the Acme contract?
+```
+
+The LLM can now cite both the vector search hits (specific text passages) and
+the knowledge graph entities (relationships and structure) to produce a
+grounded answer.
+
+---
+
+## Relationship with Hindsight
+
+This plugin **complements** [Hindsight](https://github.com/vectorize-io/hindsight)
+(the memory plugin) without conflict:
+
+| | Hindsight | openclaw-knowledge |
+|---|-----------|-------------------|
+| **Purpose** | Conversational memory | Document knowledge (RAG) |
+| **Source** | Facts extracted from chats | Documents from Google Drive |
+| **Storage** | PostgreSQL (Hindsight schema) | PostgreSQL (`knowledge_vectors`) + Neo4j |
+| **Trigger** | `auto-recall` on every message | `before_prompt_build` on every message |
+| **Injection block** | `<relevant-memories>` | `### Document Search Results` + `### Knowledge Graph Context` |
+| **OpenClaw slot** | `memory` (exclusive) | None (coexists freely) |
+
+Both run on every user message. The agent receives **both** blocks, giving it
+conversational memory AND document knowledge simultaneously.
+
+---
+
+## Development
+
+This plugin is written in **TypeScript** and builds against the official
+OpenClaw plugin SDK (`openclaw/plugin-sdk/plugin-entry`).
+
+### Project layout
+
+```
+openclaw-knowledge-plugin/
+├── src/                       # TypeScript source
+│   ├── index.ts               # Entry point (definePluginEntry + register)
+│   ├── config.ts              # resolveEnv + default resolution
+│   ├── embeddings.ts          # Gemini embedContent client
+│   ├── pgvector.ts            # PostgreSQL search + result formatter
+│   ├── lightrag.ts            # LightRAG client + truncation
+│   └── types.ts               # Shared interfaces
+├── test/                      # TypeScript test suites (node:test)
+├── dist/                      # Compiled JS + .d.ts (gitignored)
+├── tsconfig.json              # Strict TS config for src
+├── tsconfig.test.json         # Typecheck (src + test)
+├── tsconfig.test-build.json   # Compile tests to dist-test/ for node:test
+├── openclaw.plugin.json       # Plugin manifest (config schema + uiHints)
+└── package.json
+```
+
+### Build and test
+
+```bash
+# Install dev dependencies (includes the openclaw SDK for types, ~200 MB)
+npm install
+
+# Strict type check (src + tests)
+npm run typecheck
+
+# Run the full test suite (compiles tests then runs node:test)
+npm test
+
+# Compile TS → dist/
+npm run build
+
+# Clean build output
+npm run clean
+```
+
+### Release process
+
+1. Update `CHANGELOG.md` with the new version (add a `## [x.y.z] - YYYY-MM-DD` section)
+2. Commit the changelog update
+3. Create and push a git tag:
+   ```bash
+   git tag v3.1.0
+   git push origin v3.1.0
+   ```
+4. GitHub Actions will automatically:
+   - Run `npm run typecheck`, `npm test`, `npm run build` on Node.js 24
+   - Stamp the version from the tag into `package.json` and `openclaw.plugin.json`
+   - Compile TypeScript (`npm run build`)
+   - **Publish `@olivierneu/openclaw-knowledge` to npm** (public access)
+   - Create a GitHub Release with changelog notes extracted from `CHANGELOG.md`
+
+#### Required GitHub secret
+
+The workflow needs an `NPM_TOKEN` secret. Because the npm account has 2FA
+enabled with a security key, the token **must** be an **Automation token**
+(not a regular Publish token), because automation tokens bypass 2FA for CI/CD.
+
+Generate it on npm: *Access Tokens → Generate New Token → Classic Token →
+Automation*, then add it under GitHub repo *Settings → Secrets and variables
+→ Actions* as `NPM_TOKEN`.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Solution |
+|---------|-------|----------|
+| `Cannot find module 'pg'` | Old release (pre-v3.0.4) without bundled deps | Upgrade to v3.0.4+ |
+| `neither pgvector nor LightRAG configured — plugin disabled` | No `geminiApiKey` and no `lightragUrl` | Configure at least one source |
+| `pgvector — source failed: Gemini embedding failed (429)` | Gemini quota exceeded | Check Gemini API quotas or back off |
+| `LightRAG query failed (401)` | Wrong or missing `lightragApiKey` | Verify the header `X-API-Key` is accepted |
+| `LightRAG query failed (503)` | LightRAG server down | Check LightRAG container status |
+| Plugin loads but no context injected | `scoreThreshold` too high | Lower to `0` to see all matches |
+| Plugin enters 5-min cooldown | 3 consecutive errors on all sources | Check logs, fix the underlying issue |
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+import type { KnowledgePluginConfig, ResolvedKnowledgeConfig } from "./types.js";
+/**
+ * Expand `${VAR_NAME}` patterns in a config string against `process.env`.
+ * Non-string values are returned untouched so the helper can be used on any
+ * raw config field without type narrowing at the call site. Missing env vars
+ * become empty strings to avoid leaking `undefined` into downstream code.
+ */
+export declare function resolveEnv<T>(value: T): T;
+/**
+ * Apply defaults and env substitution to the raw plugin config. A source is
+ * enabled when its credentials are present, unless the user explicitly toggles
+ * `pgvectorEnabled`/`lightragEnabled` off.
+ */
+export declare function resolveConfig(cfg?: KnowledgePluginConfig): ResolvedKnowledgeConfig;

package/dist/config.js

@@ -0,0 +1,51 @@
+// Plugin configuration helpers.
+//
+// These helpers are the only place that touches `process.env`, keeping the
+// rest of the plugin easy to test with deterministic values.
+/**
+ * Expand `${VAR_NAME}` patterns in a config string against `process.env`.
+ * Non-string values are returned untouched so the helper can be used on any
+ * raw config field without type narrowing at the call site. Missing env vars
+ * become empty strings to avoid leaking `undefined` into downstream code.
+ */
+export function resolveEnv(value) {
+    if (typeof value !== "string")
+        return value;
+    return value.replace(/\$\{(\w+)\}/g, (_, name) => {
+        return process.env[name] ?? "";
+    });
+}
+const DEFAULT_POSTGRES_URL = "postgresql://openclaw:@postgresql:5432/knowledge";
+const DEFAULT_COLLECTIONS = ["knowledge_default"];
+const DEFAULT_TOP_K = 5;
+const DEFAULT_SCORE_THRESHOLD = 0.3;
+const DEFAULT_MAX_INJECT_CHARS = 4000;
+const DEFAULT_LIGHTRAG_MODE = "hybrid";
+const DEFAULT_LIGHTRAG_MAX_CHARS = 4000;
+/**
+ * Apply defaults and env substitution to the raw plugin config. A source is
+ * enabled when its credentials are present, unless the user explicitly toggles
+ * `pgvectorEnabled`/`lightragEnabled` off.
+ */
+export function resolveConfig(cfg = {}) {
+    const geminiApiKey = resolveEnv(cfg.geminiApiKey ?? "");
+    const postgresUrl = resolveEnv(cfg.postgresUrl ?? DEFAULT_POSTGRES_URL);
+    const lightragUrl = resolveEnv(cfg.lightragUrl ?? "");
+    const lightragApiKey = resolveEnv(cfg.lightragApiKey ?? "");
+    return {
+        enabled: cfg.enabled !== false,
+        geminiApiKey,
+        postgresUrl,
+        collections: cfg.collections ?? DEFAULT_COLLECTIONS,
+        topK: cfg.topK ?? DEFAULT_TOP_K,
+        scoreThreshold: cfg.scoreThreshold ?? DEFAULT_SCORE_THRESHOLD,
+        maxInjectChars: cfg.maxInjectChars ?? DEFAULT_MAX_INJECT_CHARS,
+        pgvectorEnabled: cfg.pgvectorEnabled !== false && Boolean(geminiApiKey),
+        lightragUrl,
+        lightragApiKey,
+        lightragQueryMode: cfg.lightragQueryMode ?? DEFAULT_LIGHTRAG_MODE,
+        lightragMaxChars: cfg.lightragMaxChars ?? DEFAULT_LIGHTRAG_MAX_CHARS,
+        lightragEnabled: cfg.lightragEnabled !== false && Boolean(lightragUrl),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,EAAE;AACF,2EAA2E;AAC3E,6DAA6D;AAQ7D;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAI,KAAQ;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,KAAK,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,IAAY,EAAE,EAAE;QACvD,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACjC,CAAC,CAAiB,CAAC;AACrB,CAAC;AAED,MAAM,oBAAoB,GAAG,kDAAkD,CAAC;AAChF,MAAM,mBAAmB,GAAG,CAAC,mBAAmB,CAAC,CAAC;AAClD,MAAM,aAAa,GAAG,CAAC,CAAC;AACxB,MAAM,uBAAuB,GAAG,GAAG,CAAC;AACpC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AACtC,MAAM,qBAAqB,GAAsB,QAAQ,CAAC;AAC1D,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAExC;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,MAA6B,EAAE;IAE/B,MAAM,YAAY,GAAG,UAAU,CAAC,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC;IACxD,MAAM,WAAW,GAAG,UAAU,CAAC,GAAG,CAAC,WAAW,IAAI,oBAAoB,CAAC,CAAC;IACxE,MAAM,WAAW,GAAG,UAAU,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,cAAc,GAAG,UAAU,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;IAE5D,OAAO;QACL,OAAO,EAAE,GAAG,CAAC,OAAO,KAAK,KAAK;QAC9B,YAAY;QACZ,WAAW;QACX,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,mBAAmB;QACnD,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,aAAa;QAC/B,cAAc,EAAE,GAAG,CAAC,cAAc,IAAI,uBAAuB;QAC7D,cAAc,EAAE,GAAG,CAAC,cAAc,IAAI,wBAAwB;QAC9D,eAAe,EAAE,GAAG,CAAC,eAAe,KAAK,KAAK,IAAI,OAAO,CAAC,YAAY,CAAC;QACvE,WAAW;QACX,cAAc;QACd,iBAAiB,EAAE,GAAG,CAAC,iBAAiB,IAAI,qBAAqB;QACjE,gBAAgB,EAAE,GAAG,CAAC,gBAAgB,IAAI,0BAA0B;QACpE,eAAe,EAAE,GAAG,CAAC,eAAe,KAAK,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;KACvE,CAAC;AACJ,CAAC"}

package/dist/embeddings.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare function embedQuery(text: string, geminiApiKey: string): Promise<number[]>;