@vainplex/openclaw-knowledge-engine 0.1.1 → 0.1.3

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Vainplex
+Copyright (c) 2026 OpenClaw Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -14,11 +14,11 @@ Every message your OpenClaw agent processes flows through the Knowledge Engine:
 6. **Background Maintenance** — Prunes low-relevance facts, compacts storage, runs cleanup
 
 ```
-User: "We're meeting with Sebastian from Mondo Gate next Tuesday"
+User: "We're meeting with Alex from Acme Corp next Tuesday"
   │
-  ├─ Regex → entities: [Sebastian (person), Mondo Gate (organization)]
-  └─ LLM   → facts:   [Sebastian — works-at — Mondo Gate]
-                       [Meeting — scheduled-with — Mondo Gate]
+  ├─ Regex → entities: [Alex (person), Acme Corp (organization)]
+  └─ LLM   → facts:   [Alex — works-at — Acme Corp]
+                       [Meeting — scheduled-with — Acme Corp]
 ```
 
 ## Quick Start
@@ -167,9 +167,9 @@ Facts are stored as structured triples:
 ```json
 {
   "id": "f-abc123",
-  "subject": "Sebastian",
+  "subject": "Alex",
   "predicate": "works-at",
-  "object": "Mondo Gate",
+  "object": "Acme Corp",
   "source": "extracted-llm",
   "relevance": 0.95,
   "createdAt": 1707123456789,
@@ -235,7 +235,7 @@ npm test
 
 Tests cover: config validation, entity extraction, fact CRUD, decay, pruning, LLM batching, HTTP client, embeddings, storage atomicity, maintenance scheduling, hook orchestration.
 
-## Part of the Darkplex Plugin Suite
+## Part of the Vainplex Plugin Suite
 
 | # | Plugin | Status | Description |
 |---|--------|--------|-------------|

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 import type { OpenClawPluginApi } from './src/types.js';
-declare const _default: (api: OpenClawPluginApi, context: {
-    workspace: string;
-}) => void;
-export default _default;
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    register(api: OpenClawPluginApi): void;
+};
+export default plugin;

package/dist/index.js

@@ -1,29 +1,33 @@
-// index.ts
-import { resolveConfig } from './src/config.js';
+// index.ts — OpenClaw Plugin Entry Point
+import { loadConfig } from './src/config-loader.js';
 import { HookManager } from './src/hooks.js';
-// The main entry point for the OpenClaw plugin.
-// This function is called by the OpenClaw host during plugin loading.
-export default (api, context) => {
-    const { pluginConfig, logger } = api;
-    const { workspace: openClawWorkspace } = context;
-    // 1. Resolve and validate the configuration
-    const config = resolveConfig(pluginConfig, logger, openClawWorkspace);
-    if (!config) {
-        logger.error('Failed to initialize Knowledge Engine: Invalid configuration. The plugin will be disabled.');
-        return;
-    }
-    if (!config.enabled) {
-        logger.info('Knowledge Engine is disabled in the configuration.');
-        return;
-    }
-    // 2. Initialize the Hook Manager with the resolved config
-    try {
-        const hookManager = new HookManager(api, config);
-        // 3. Register all the event hooks
-        hookManager.registerHooks();
-        logger.info('Knowledge Engine plugin initialized successfully.');
-    }
-    catch (err) {
-        logger.error('An unexpected error occurred during Knowledge Engine initialization.', err);
-    }
+const plugin = {
+    id: 'openclaw-knowledge-engine',
+    name: 'OpenClaw Knowledge Engine',
+    description: 'Real-time knowledge extraction — entities, facts, and relationships from conversations',
+    version: '0.1.2',
+    register(api) {
+        const { pluginConfig, logger } = api;
+        // 1. Resolve and validate the configuration
+        const { config } = loadConfig(pluginConfig, logger);
+        if (!config) {
+            logger.error('Knowledge Engine: Invalid configuration — plugin disabled.');
+            return;
+        }
+        if (!config.enabled) {
+            logger.info('[knowledge-engine] Disabled via config');
+            return;
+        }
+        // 2. Initialize the Hook Manager and register hooks
+        try {
+            logger.info('[knowledge-engine] Registering hooks...');
+            const hookManager = new HookManager(api, config);
+            hookManager.registerHooks();
+            logger.info('[knowledge-engine] Ready');
+        }
+        catch (err) {
+            logger.error('[knowledge-engine] Failed to initialize', err);
+        }
+    },
 };
+export default plugin;

package/dist/src/config-loader.d.ts

@@ -0,0 +1,22 @@
+import type { KnowledgeConfig, Logger } from "./types.js";
+/** Minimal inline config that lives in openclaw.json */
+export interface InlineConfig {
+    readonly enabled?: boolean;
+    /** Override path to external config file */
+    readonly configPath?: string;
+}
+export interface ConfigLoadResult {
+    readonly config: KnowledgeConfig | null;
+    readonly source: "inline" | "file" | "defaults";
+    readonly filePath?: string;
+}
+/**
+ * Load knowledge-engine config with the following priority:
+ *
+ * 1. Legacy inline config (full config in openclaw.json) → use it directly
+ * 2. External file (configPath or default location) → read + resolve
+ * 3. Graceful defaults → everything enabled, fail-open
+ *
+ * NEVER throws. Worst case: returns defaults with a warning.
+ */
+export declare function loadConfig(pluginConfig: Record<string, unknown> | undefined, logger: Logger): ConfigLoadResult;

package/dist/src/config-loader.js

@@ -0,0 +1,104 @@
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { resolveConfig, DEFAULT_CONFIG } from "./config.js";
+const DEFAULT_CONFIG_DIR = join(process.env["HOME"] ?? "/tmp", ".openclaw", "plugins", "openclaw-knowledge-engine");
+const DEFAULT_CONFIG_FILENAME = "config.json";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Determine whether pluginConfig is a full (legacy) inline config
+ * or just the minimal inline pointer.
+ *
+ * Heuristic: if it has keys beyond `enabled` and `configPath`,
+ * treat it as legacy inline config.
+ */
+function isLegacyInlineConfig(raw) {
+    const inlineOnlyKeys = new Set(["enabled", "configPath"]);
+    return Object.keys(raw).some((k) => !inlineOnlyKeys.has(k));
+}
+/**
+ * Read and parse a JSON file. Returns null on any error.
+ */
+function readJsonFile(path, logger) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed)) {
+            logger.warn(`[knowledge-engine] Config file is not an object: ${path}`);
+            return null;
+        }
+        return parsed;
+    }
+    catch (e) {
+        logger.warn(`[knowledge-engine] Failed to read config file ${path}: ${e instanceof Error ? e.message : String(e)}`);
+        return null;
+    }
+}
+/**
+ * Apply inline `enabled` override to a file-loaded config (immutably).
+ */
+function applyInlineOverrides(fileConfig, inline) {
+    if (typeof inline["enabled"] === "boolean") {
+        return { ...fileConfig, enabled: inline["enabled"] };
+    }
+    return fileConfig;
+}
+/**
+ * Bootstrap a default config file and return its contents.
+ * Returns null if writing or reading back fails.
+ */
+function bootstrapConfig(path, logger) {
+    try {
+        const dir = dirname(path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(path, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n", "utf-8");
+        logger.info(`[knowledge-engine] Created default config at ${path}`);
+        return readJsonFile(path, logger);
+    }
+    catch (e) {
+        logger.warn(`[knowledge-engine] Failed to write default config: ${e instanceof Error ? e.message : String(e)}`);
+        return null;
+    }
+}
+/**
+ * Load knowledge-engine config with the following priority:
+ *
+ * 1. Legacy inline config (full config in openclaw.json) → use it directly
+ * 2. External file (configPath or default location) → read + resolve
+ * 3. Graceful defaults → everything enabled, fail-open
+ *
+ * NEVER throws. Worst case: returns defaults with a warning.
+ */
+export function loadConfig(pluginConfig, logger) {
+    const raw = pluginConfig ?? {};
+    // Priority 1: Legacy inline config (backward compatible)
+    if (isLegacyInlineConfig(raw)) {
+        logger.info("[knowledge-engine] Using inline config from openclaw.json");
+        return { config: resolveConfig(raw, logger), source: "inline" };
+    }
+    // Priority 2: External config file
+    const configPath = typeof raw["configPath"] === "string"
+        ? raw["configPath"]
+        : join(DEFAULT_CONFIG_DIR, DEFAULT_CONFIG_FILENAME);
+    const fileConfig = readJsonFile(configPath, logger);
+    if (fileConfig !== null) {
+        const merged = applyInlineOverrides(fileConfig, raw);
+        logger.info(`[knowledge-engine] Loaded config from ${configPath}`);
+        return { config: resolveConfig(merged, logger), source: "file", filePath: configPath };
+    }
+    // File missing → bootstrap with defaults
+    if (!existsSync(configPath)) {
+        const bootstrapped = bootstrapConfig(configPath, logger);
+        if (bootstrapped !== null) {
+            const merged = applyInlineOverrides(bootstrapped, raw);
+            return { config: resolveConfig(merged, logger), source: "file", filePath: configPath };
+        }
+    }
+    // Priority 3: Graceful defaults (file broken or unwritable)
+    logger.warn("[knowledge-engine] Falling back to default config");
+    return { config: resolveConfig(undefined, logger), source: "defaults" };
+}

package/dist/src/config.d.ts

@@ -12,4 +12,4 @@ export declare const DEFAULT_CONFIG: Omit<KnowledgeConfig, 'workspace'>;
  * @param openClawWorkspace The root workspace directory provided by OpenClaw.
  * @returns A fully resolved KnowledgeConfig, or null if validation fails.
  */
-export declare function resolveConfig(userConfig: Record<string, unknown>, logger: Logger, openClawWorkspace: string): KnowledgeConfig | null;
+export declare function resolveConfig(userConfig: Record<string, unknown> | undefined | null, logger: Logger, openClawWorkspace?: string): KnowledgeConfig | null;

package/dist/src/config.js

@@ -78,8 +78,9 @@ function resolveTilde(ws, logger, fallback) {
  * @returns A fully resolved KnowledgeConfig, or null if validation fails.
  */
 export function resolveConfig(userConfig, logger, openClawWorkspace) {
-    const config = mergeConfigDefaults(userConfig, openClawWorkspace);
-    const fallbackWs = path.join(openClawWorkspace, 'knowledge-engine');
+    const ws = openClawWorkspace ?? process.cwd();
+    const config = mergeConfigDefaults(userConfig ?? {}, ws);
+    const fallbackWs = path.join(ws, 'knowledge-engine');
     config.workspace = resolveTilde(config.workspace, logger, fallbackWs);
     const errors = validateConfig(config);
     if (errors.length > 0) {

package/openclaw.plugin.json

@@ -1,123 +1,127 @@
 {
-  "id": "@vainplex/openclaw-knowledge-engine",
-  "config": {
-    "enabled": {
-      "type": "boolean",
-      "default": true,
-      "description": "Whether the knowledge engine plugin is enabled."
-    },
-    "workspace": {
-      "type": "string",
-      "default": "~/.clawd/plugins/knowledge-engine",
-      "description": "The directory to store knowledge files (entities.json, facts.json)."
-    },
-    "extraction": {
-      "type": "object",
-      "properties": {
-        "regex": {
-          "type": "object",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "default": true,
-              "description": "Enable or disable high-speed regex-based entity extraction."
+  "id": "openclaw-knowledge-engine",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Whether the knowledge engine plugin is enabled."
+      },
+      "workspace": {
+        "type": "string",
+        "default": "~/.clawd/plugins/knowledge-engine",
+        "description": "The directory to store knowledge files (entities.json, facts.json)."
+      },
+      "extraction": {
+        "type": "object",
+        "properties": {
+          "regex": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": true,
+                "description": "Enable or disable high-speed regex-based entity extraction."
+              }
             }
-          }
-        },
-        "llm": {
-          "type": "object",
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "default": true,
-              "description": "Enable or disable high-fidelity LLM-based entity and fact extraction."
-            },
-            "model": {
-              "type": "string",
-              "default": "mistral:7b",
-              "description": "The model name to use for the LLM API call (e.g., Ollama model)."
-            },
-            "endpoint": {
-              "type": "string",
-              "default": "http://localhost:11434/api/generate",
-              "description": "The HTTP endpoint for the LLM generation API."
-            },
-            "batchSize": {
-              "type": "number",
-              "default": 10,
-              "description": "Number of messages to batch together before sending to the LLM."
-            },
-            "cooldownMs": {
-              "type": "number",
-              "default": 30000,
-              "description": "Milliseconds to wait after the last message before sending a batch to the LLM."
+          },
+          "llm": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": true,
+                "description": "Enable or disable high-fidelity LLM-based entity and fact extraction."
+              },
+              "model": {
+                "type": "string",
+                "default": "mistral:7b",
+                "description": "The model name to use for the LLM API call (e.g., Ollama model)."
+              },
+              "endpoint": {
+                "type": "string",
+                "default": "http://localhost:11434/api/generate",
+                "description": "The HTTP endpoint for the LLM generation API."
+              },
+              "batchSize": {
+                "type": "number",
+                "default": 10,
+                "description": "Number of messages to batch together before sending to the LLM."
+              },
+              "cooldownMs": {
+                "type": "number",
+                "default": 30000,
+                "description": "Milliseconds to wait after the last message before sending a batch to the LLM."
+              }
             }
           }
         }
-      }
-    },
-    "decay": {
-      "type": "object",
-      "properties": {
-        "enabled": {
-          "type": "boolean",
-          "default": true,
-          "description": "Enable or disable the periodic decay of fact relevance."
-        },
-        "intervalHours": {
-          "type": "number",
-          "default": 24,
-          "description": "How often (in hours) to run the decay process."
-        },
-        "rate": {
-          "type": "number",
-          "default": 0.02,
-          "description": "The percentage of relevance to decay in each interval (e.g., 0.02 is 2%)."
+      },
+      "decay": {
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable or disable the periodic decay of fact relevance."
+          },
+          "intervalHours": {
+            "type": "number",
+            "default": 24,
+            "description": "How often (in hours) to run the decay process."
+          },
+          "rate": {
+            "type": "number",
+            "default": 0.02,
+            "description": "The percentage of relevance to decay in each interval (e.g., 0.02 is 2%)."
+          }
         }
-      }
-    },
-    "embeddings": {
-      "type": "object",
-      "properties": {
-        "enabled": {
-          "type": "boolean",
-          "default": false,
-          "description": "Enable or disable syncing of facts to a vector database."
-        },
-        "endpoint": {
-          "type": "string",
-          "default": "http://localhost:8000/api/v1/collections/facts/add",
-          "description": "The HTTP endpoint for the vector database's add API (ChromaDB compatible)."
-        },
-        "collectionName": {
-          "type": "string",
-          "default": "openclaw-facts",
-          "description": "The name of the collection to use in the vector database."
-        },
-        "syncIntervalMinutes": {
-          "type": "number",
-          "default": 15,
-          "description": "How often (in minutes) to sync new facts to the vector database."
+      },
+      "embeddings": {
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable or disable syncing of facts to a vector database."
+          },
+          "endpoint": {
+            "type": "string",
+            "default": "http://localhost:8000/api/v1/collections/facts/add",
+            "description": "The HTTP endpoint for the vector database's add API (ChromaDB compatible)."
+          },
+          "collectionName": {
+            "type": "string",
+            "default": "openclaw-facts",
+            "description": "The name of the collection to use in the vector database."
+          },
+          "syncIntervalMinutes": {
+            "type": "number",
+            "default": 15,
+            "description": "How often (in minutes) to sync new facts to the vector database."
+          }
         }
-      }
-    },
-    "storage": {
-      "type": "object",
-      "properties": {
-        "maxEntities": {
-          "type": "number",
-          "default": 5000,
-          "description": "The maximum number of entities to store before pruning."
-        },
-        "maxFacts": {
-          "type": "number",
-          "default": 10000,
-          "description": "The maximum number of facts to store before pruning."
-        },
-        "writeDebounceMs": {
-          "type": "number",
-          "default": 15000,
-          "description": "Milliseconds to wait after a change before writing data to disk."
+      },
+      "storage": {
+        "type": "object",
+        "properties": {
+          "maxEntities": {
+            "type": "number",
+            "default": 5000,
+            "description": "The maximum number of entities to store before pruning."
+          },
+          "maxFacts": {
+            "type": "number",
+            "default": 10000,
+            "description": "The maximum number of facts to store before pruning."
+          },
+          "writeDebounceMs": {
+            "type": "number",
+            "default": 15000,
+            "description": "Milliseconds to wait after a change before writing data to disk."
+          }
         }
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vainplex/openclaw-knowledge-engine",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "An OpenClaw plugin for real-time and batch knowledge extraction from conversational data.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,14 +17,18 @@
     "nlp",
     "entity-extraction"
   ],
-  "author": "Vainplex",
+  "author": "Albert Hild <a.hild@vainplex.de>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/alberthild/openclaw-knowledge-engine.git"
+    "url": "https://github.com/alberthild/vainplex-openclaw.git",
+    "directory": "packages/openclaw-knowledge-engine"
   },
   "openclaw": {
-    "id": "@vainplex/openclaw-knowledge-engine"
+    "id": "openclaw-knowledge-engine",
+    "extensions": [
+      "./dist/index.js"
+    ]
   },
   "devDependencies": {
     "@types/node": "^20.11.24",
@@ -32,5 +36,11 @@
     "typescript": "^5.3.3",
     "tsx": "^4.7.1"
   },
-  "type": "module"
+  "type": "module",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ]
 }