@karmaniverous/jeeves-watcher-openclaw 0.3.7 → 0.3.9

package/dist/cli.js

@@ -8,9 +8,13 @@ import { fileURLToPath } from 'url';
  * CLI for installing/uninstalling the jeeves-watcher OpenClaw plugin.
  *
  * Usage:
- *   npx \@karmaniverous/jeeves-watcher-openclaw install
+ *   npx \@karmaniverous/jeeves-watcher-openclaw install [--memory]
  *   npx \@karmaniverous/jeeves-watcher-openclaw uninstall
  *
+ * The --memory flag claims the OpenClaw memory slot, replacing memory-core
+ * with the plugin's Qdrant-backed memory_search and memory_get tools.
+ * Without --memory, only watcher admin tools are registered.
+ *
  * Bypasses OpenClaw's `plugins install` command, which has a known
  * spawn EINVAL bug on Windows (https://github.com/openclaw/openclaw/issues/9224).
  *
@@ -79,7 +83,7 @@ function patchAllowList(parent, key, label, mode) {
     return undefined;
 }
 /** Patch OpenClaw config for install or uninstall. Returns log messages. */
-function patchConfig(config, mode) {
+function patchConfig(config, mode, options = {}) {
     const messages = [];
     // Ensure plugins section
     if (!config.plugins || typeof config.plugins !== 'object') {
@@ -110,13 +114,20 @@ function patchConfig(config, mode) {
         plugins.slots = {};
     }
     const slots = plugins.slots;
-    if (mode === 'add') {
+    if (mode === 'add' && options.memory) {
         const prev = slots.memory;
         slots.memory = PLUGIN_ID;
         if (prev !== PLUGIN_ID) {
             messages.push(`Set plugins.slots.memory to "${PLUGIN_ID}"${prev ? ` (was "${prev}")` : ''}`);
         }
     }
+    else if (mode === 'add' && !options.memory) {
+        // Non-memory install: revert slot if we held it
+        if (slots.memory === PLUGIN_ID) {
+            slots.memory = 'memory-core';
+            messages.push(`Reverted plugins.slots.memory to "memory-core" (non-memory install)`);
+        }
+    }
     else if (slots.memory === PLUGIN_ID) {
         slots.memory = 'memory-core';
         messages.push(`Reverted plugins.slots.memory to "memory-core"`);
@@ -129,7 +140,7 @@ function patchConfig(config, mode) {
     return messages;
 }
 /** Install the plugin into OpenClaw's extensions directory. */
-function install() {
+function install(memoryMode) {
     const home = resolveOpenClawHome();
     const configPath = resolveConfigPath(home);
     const extDir = join(home, 'extensions', PLUGIN_ID);
@@ -138,6 +149,7 @@ function install() {
     console.log(`Config:         ${configPath}`);
     console.log(`Extensions dir: ${extDir}`);
     console.log(`Package root:   ${pkgRoot}`);
+    console.log(`Memory mode:    ${memoryMode ? 'yes (claiming memory slot)' : 'no (watcher tools only)'}`);
     console.log();
     if (!existsSync(home)) {
         console.error(`Error: OpenClaw home directory not found at ${home}`);
@@ -173,6 +185,20 @@ function install() {
         cpSync(nodeModulesSrc, join(extDir, 'node_modules'), { recursive: true });
         console.log('  ✓ node_modules');
     }
+    // Patch manifest based on memory mode
+    const installedManifestPath = join(extDir, 'openclaw.plugin.json');
+    const manifest = readJson(installedManifestPath);
+    if (manifest) {
+        if (memoryMode) {
+            manifest.kind = 'memory';
+            console.log('  ✓ Set kind: "memory" in manifest');
+        }
+        else {
+            delete manifest.kind;
+            console.log('  ✓ Removed kind from manifest (non-memory mode)');
+        }
+        writeJson(installedManifestPath, manifest);
+    }
     // Patch config
     console.log();
     console.log('Patching OpenClaw config...');
@@ -181,13 +207,19 @@ function install() {
         console.error(`Error: Could not parse ${configPath}`);
         process.exit(1);
     }
-    for (const msg of patchConfig(config, 'add')) {
+    for (const msg of patchConfig(config, 'add', { memory: memoryMode })) {
         console.log(`  ✓ ${msg}`);
     }
     writeJson(configPath, config);
     console.log();
     console.log('✅ Plugin installed successfully.');
     console.log('   Restart the OpenClaw gateway to load the plugin.');
+    if (memoryMode) {
+        console.log('   Memory slot claimed — memory_search and memory_get tools will be available.');
+    }
+    else {
+        console.log('   Watcher tools available. Run with --memory after bootstrapping to enable memory features.');
+    }
 }
 /** Uninstall the plugin from OpenClaw's extensions directory. */
 function uninstall() {
@@ -221,9 +253,10 @@ function uninstall() {
 }
 // Main
 const command = process.argv[2];
+const memoryFlag = process.argv.includes('--memory');
 switch (command) {
     case 'install':
-        install();
+        install(memoryFlag);
         break;
     case 'uninstall':
         uninstall();
@@ -232,8 +265,11 @@ switch (command) {
         console.log(`@karmaniverous/jeeves-watcher-openclaw — OpenClaw plugin installer`);
         console.log();
         console.log('Usage:');
-        console.log('  npx @karmaniverous/jeeves-watcher-openclaw install    Install plugin');
-        console.log('  npx @karmaniverous/jeeves-watcher-openclaw uninstall  Remove plugin');
+        console.log('  npx @karmaniverous/jeeves-watcher-openclaw install [--memory]  Install plugin');
+        console.log('  npx @karmaniverous/jeeves-watcher-openclaw uninstall             Remove plugin');
+        console.log();
+        console.log('Options:');
+        console.log('  --memory  Claim memory slot (replaces memory-core with Qdrant-backed search)');
         console.log();
         console.log('Environment variables:');
         console.log('  OPENCLAW_CONFIG  Path to openclaw.json (overrides all)');

package/dist/index.js

@@ -15,7 +15,7 @@ function normalizePath(p) {
 }
 /**
  * Resolve the workspace path from gateway config.
- * Priority: agent-specific > defaults > fallback (~/.openclaw/workspace).
+ * Priority: agent-specific \> defaults \> fallback (~/.openclaw/workspace).
  */
 function getWorkspacePath(api) {
     const agentWorkspace = api.config?.agents?.entries?.['main']?.workspace ??
@@ -27,6 +27,26 @@ function getApiUrl(api) {
     const url = api.config?.plugins?.entries?.['jeeves-watcher-openclaw']?.config?.apiUrl;
     return typeof url === 'string' ? url : DEFAULT_API_URL;
 }
+/**
+ * Resolve user-supplied schemas from plugin config.
+ * Returns a map of rule name → schema array (always normalized to array).
+ */
+function getPluginSchemas(api) {
+    const config = api.config?.plugins?.entries?.['jeeves-watcher-openclaw']?.config;
+    const raw = config?.schemas;
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const result = {};
+    for (const [name, value] of Object.entries(raw)) {
+        if (Array.isArray(value)) {
+            result[name] = value;
+        }
+        else if (typeof value === 'object' || typeof value === 'string') {
+            result[name] = [value];
+        }
+    }
+    return result;
+}
 /** Format a successful tool result. */
 function ok(data) {
     return {
@@ -90,12 +110,42 @@ async function postJson(url, body) {
  * memory_search call. Re-attempts on failure. memory_get reads files
  * directly from the filesystem with path validation.
  */
-/** Build virtual inference rules for a workspace path. */
-function buildVirtualRules(workspace) {
+/** Private property prefix — namespaces plugin metadata to avoid collisions. */
+const PROP_PREFIX = '_jeeves_watcher_openclaw_';
+/** Private property keys used by the plugin for filtering. */
+const PROP_SOURCE = `${PROP_PREFIX}source_`;
+const PROP_KIND = `${PROP_PREFIX}kind_`;
+/** Memory source value for filter queries. */
+const SOURCE_MEMORY = 'memory';
+/** Virtual rule names (exported for testing and config reference). */
+const RULE_LONGTERM = 'openclaw-memory-longterm';
+const RULE_DAILY = 'openclaw-memory-daily';
+/**
+ * Build virtual inference rules for a workspace path.
+ *
+ * Each rule's schema is composed of:
+ * 1. Plugin-internal schema (private namespaced properties, no uiHint)
+ * 2. User-supplied schemas from plugin config (optional, owner-controlled)
+ */
+function buildVirtualRules(workspace, userSchemas) {
     const ws = normalizePath(workspace);
+    const longtermInternal = {
+        type: 'object',
+        properties: {
+            [PROP_SOURCE]: { type: 'string', set: SOURCE_MEMORY },
+            [PROP_KIND]: { type: 'string', set: 'long-term' },
+        },
+    };
+    const dailyInternal = {
+        type: 'object',
+        properties: {
+            [PROP_SOURCE]: { type: 'string', set: SOURCE_MEMORY },
+            [PROP_KIND]: { type: 'string', set: 'daily-log' },
+        },
+    };
     return [
         {
-            name: 'openclaw-memory-longterm',
+            name: RULE_LONGTERM,
             description: 'OpenClaw long-term memory file',
             match: {
                 properties: {
@@ -106,22 +156,10 @@ function buildVirtualRules(workspace) {
                     },
                 },
             },
-            schema: [
-                {
-                    type: 'object',
-                    properties: {
-                        domains: {
-                            type: 'array',
-                            items: { type: 'string' },
-                            set: ['memory'],
-                        },
-                        kind: { type: 'string', set: 'long-term' },
-                    },
-                },
-            ],
+            schema: [longtermInternal, ...(userSchemas[RULE_LONGTERM] ?? [])],
         },
         {
-            name: 'openclaw-memory-daily',
+            name: RULE_DAILY,
             description: 'OpenClaw daily memory logs',
             match: {
                 properties: {
@@ -132,19 +170,7 @@ function buildVirtualRules(workspace) {
                     },
                 },
             },
-            schema: [
-                {
-                    type: 'object',
-                    properties: {
-                        domains: {
-                            type: 'array',
-                            items: { type: 'string' },
-                            set: ['memory'],
-                        },
-                        kind: { type: 'string', set: 'daily-log' },
-                    },
-                },
-            ],
+            schema: [dailyInternal, ...(userSchemas[RULE_DAILY] ?? [])],
         },
     ];
 }
@@ -166,6 +192,7 @@ function isAllowedMemoryPath(filePath, workspace) {
  */
 function createMemoryTools(api, baseUrl) {
     const workspace = getWorkspacePath(api);
+    const userSchemas = getPluginSchemas(api);
     const state = {
         initialized: false,
         lastWatcherUptime: 0,
@@ -188,7 +215,7 @@ function createMemoryTools(api, baseUrl) {
             body: JSON.stringify({ source: PLUGIN_SOURCE }),
         });
         // Register virtual rules
-        const virtualRules = buildVirtualRules(state.workspace);
+        const virtualRules = buildVirtualRules(state.workspace, userSchemas);
         await postJson(`${state.baseUrl}/rules/register`, {
             source: PLUGIN_SOURCE,
             rules: virtualRules,
@@ -216,7 +243,7 @@ function createMemoryTools(api, baseUrl) {
             const body = {
                 query: params.query,
                 filter: {
-                    must: [{ key: 'domains', match: { value: 'memory' } }],
+                    must: [{ key: PROP_SOURCE, match: { value: SOURCE_MEMORY } }],
                 },
             };
             if (params.maxResults !== undefined)

package/dist/skills/jeeves-watcher/SKILL.md

@@ -84,6 +84,52 @@ You don't need to know the rules in advance. The config is introspectable at run
 2. **Search** — use `watcher_search` with a natural language query and optional metadata filters
 3. **Read source** — use `read` (standard file read) with `file_path` from search results for full document content
 
+## Bootstrap (First Session)
+
+The first time the watcher plugin loads in a new deployment, orient yourself proactively. Don't wait for the user to ask a question — understand what you have access to.
+
+**Automatic bootstrap sequence:**
+
+1. **Health check** — call `watcher_status`. Confirm the service is running, note point count and collection dimensions.
+2. **Discover the deployment** — run the Orientation Pattern (see below): query `$.['description','search']` for organizational strategy and score thresholds, then `$.inferenceRules[*].['name','description']` for available record types.
+3. **Cache context** — store the orientation results mentally for the session. You now know what domains exist, what record types are searchable, and how to interpret scores.
+4. **Report readiness** — briefly tell the user what you found: how many points, which domains, any issues. One or two sentences, not a wall of text.
+
+**On subsequent sessions:** Repeat steps 1-3 silently. Only report if something changed (service down, point count dropped significantly, new domains appeared).
+
+**Key principle:** The agent drives discovery. The user shouldn't have to explain their archive to you — the archive explains itself through its config.
+
+## Install Modes
+
+The plugin supports two install modes, controlled by the `--memory` flag during installation:
+
+**Standard mode** (`npx @karmaniverous/jeeves-watcher-openclaw install`):
+- Registers `watcher_*` tools only (search, enrich, status, query, validate, config_apply, reindex, issues)
+- OpenClaw's built-in `memory-core` remains the memory provider
+- Use when the watcher is a supplementary search tool alongside native memory
+
+**Memory mode** (`npx @karmaniverous/jeeves-watcher-openclaw install --memory`):
+- Registers all tools: `watcher_*` plus `memory_search` and `memory_get`
+- Claims the OpenClaw memory slot — the watcher becomes the memory provider
+- MEMORY.md and memory/*.md files are indexed and searched via the watcher's vector store
+- Use when the watcher should be the single source of truth for both archive search and agent memory
+
+**How to tell which mode you're in:** If `memory_search` and `memory_get` are in your available tools, you're in memory mode. If you only see `watcher_*` tools, you're in standard mode.
+
+## Proactive Posture
+
+**If you're in standard mode and the deployment would benefit from memory mode, say so.** The watcher's vector store with 3072-dimension Gemini embeddings provides significantly better semantic memory than flat file search. If you notice:
+
+- The user has a substantial archive (>10K points)
+- Memory searches are returning poor results via native memory
+- The user is asking questions that span multiple memory files
+
+...then suggest the upgrade:
+
+> "The watcher is running with a large archive but I'm using basic file memory. Upgrading to memory mode would give semantic search over your memory files too. To upgrade: `npx @karmaniverous/jeeves-watcher-openclaw install --memory` and restart the gateway."
+
+**Don't nag.** Suggest once per session at most, and only when there's a concrete benefit. If the user declines or doesn't respond, drop it.
+
 ## Tools
 
 ### `memory_search`

package/dist/src/cli.d.ts

@@ -2,9 +2,13 @@
  * CLI for installing/uninstalling the jeeves-watcher OpenClaw plugin.
  *
  * Usage:
- *   npx \@karmaniverous/jeeves-watcher-openclaw install
+ *   npx \@karmaniverous/jeeves-watcher-openclaw install [--memory]
  *   npx \@karmaniverous/jeeves-watcher-openclaw uninstall
  *
+ * The --memory flag claims the OpenClaw memory slot, replacing memory-core
+ * with the plugin's Qdrant-backed memory_search and memory_get tools.
+ * Without --memory, only watcher admin tools are registered.
+ *
  * Bypasses OpenClaw's `plugins install` command, which has a known
  * spawn EINVAL bug on Windows (https://github.com/openclaw/openclaw/issues/9224).
  *
@@ -13,5 +17,10 @@
  *   - OPENCLAW_HOME env var (path to .openclaw directory)
  *   - Default: ~/.openclaw/openclaw.json
  */
+/** Options for patchConfig. */
+export interface PatchConfigOptions {
+    /** Whether to claim the memory slot (--memory flag). */
+    memory?: boolean;
+}
 /** Patch OpenClaw config for install or uninstall. Returns log messages. */
-export declare function patchConfig(config: Record<string, unknown>, mode: 'add' | 'remove'): string[];
+export declare function patchConfig(config: Record<string, unknown>, mode: 'add' | 'remove', options?: PatchConfigOptions): string[];

package/dist/src/helpers.d.ts

@@ -42,11 +42,22 @@ export declare const PLUGIN_SOURCE = "jeeves-watcher-openclaw";
 export declare function normalizePath(p: string): string;
 /**
  * Resolve the workspace path from gateway config.
- * Priority: agent-specific > defaults > fallback (~/.openclaw/workspace).
+ * Priority: agent-specific \> defaults \> fallback (~/.openclaw/workspace).
  */
 export declare function getWorkspacePath(api: PluginApi): string;
 /** Resolve the watcher API base URL from plugin config. */
 export declare function getApiUrl(api: PluginApi): string;
+/**
+ * Schema value type — matches watcher inference rule schema conventions.
+ * Can be an inline JSON Schema object, a file reference string,
+ * a named schema reference, or a composable array of these.
+ */
+export type SchemaValue = Record<string, unknown> | string | Array<Record<string, unknown> | string>;
+/**
+ * Resolve user-supplied schemas from plugin config.
+ * Returns a map of rule name → schema array (always normalized to array).
+ */
+export declare function getPluginSchemas(api: PluginApi): Record<string, Array<Record<string, unknown> | string>>;
 /** Format a successful tool result. */
 export declare function ok(data: unknown): ToolResult;
 /** Format an error tool result. */

package/dist/src/memoryTools.d.ts

@@ -7,6 +7,14 @@
  * directly from the filesystem with path validation.
  */
 import { type PluginApi, type ToolResult } from './helpers.js';
+/** Private property keys used by the plugin for filtering. */
+export declare const PROP_SOURCE = "_jeeves_watcher_openclaw_source_";
+export declare const PROP_KIND = "_jeeves_watcher_openclaw_kind_";
+/** Memory source value for filter queries. */
+export declare const SOURCE_MEMORY = "memory";
+/** Virtual rule names (exported for testing and config reference). */
+export declare const RULE_LONGTERM = "openclaw-memory-longterm";
+export declare const RULE_DAILY = "openclaw-memory-daily";
 /**
  * Create memory tool registrations for the plugin.
  * Returns register functions for memory_search and memory_get.

package/openclaw.plugin.json

@@ -2,8 +2,7 @@
   "id": "jeeves-watcher-openclaw",
   "name": "Jeeves Watcher",
   "description": "Semantic search, metadata enrichment, and instance administration for a jeeves-watcher deployment.",
-  "version": "0.3.7",
-  "kind": "memory",
+  "version": "0.3.9",
   "skills": [
     "dist/skills/jeeves-watcher"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-watcher-openclaw",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "author": "Jason Williscroft",
   "description": "OpenClaw plugin for jeeves-watcher — semantic search and metadata enrichment tools",
   "license": "BSD-3-Clause",