@karmaniverous/jeeves-watcher-openclaw 0.3.13 → 0.4.1

package/dist/cli.js

@@ -8,13 +8,9 @@ import { fileURLToPath } from 'url';
  * CLI for installing/uninstalling the jeeves-watcher OpenClaw plugin.
  *
  * Usage:
- *   npx \@karmaniverous/jeeves-watcher-openclaw install [--memory]
+ *   npx \@karmaniverous/jeeves-watcher-openclaw install
  *   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).
  *
@@ -83,7 +79,7 @@ function patchAllowList(parent, key, label, mode) {
     return undefined;
 }
 /** Patch OpenClaw config for install or uninstall. Returns log messages. */
-function patchConfig(config, mode, options = {}) {
+function patchConfig(config, mode) {
     const messages = [];
     // Ensure plugins section
     if (!config.plugins || typeof config.plugins !== 'object') {
@@ -109,56 +105,6 @@ function patchConfig(config, mode, options = {}) {
         Reflect.deleteProperty(entries, PLUGIN_ID);
         messages.push(`Removed "${PLUGIN_ID}" from plugins.entries`);
     }
-    // plugins.slots — claim or release the memory slot
-    if (!plugins.slots || typeof plugins.slots !== 'object') {
-        plugins.slots = {};
-    }
-    const slots = plugins.slots;
-    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"`);
-    }
-    // memory-core.enabled — disable when claiming memory slot to prevent
-    // core memory tools from shadowing the plugin's tools
-    const memoryCoreEntry = entries['memory-core'];
-    if (mode === 'add' && options.memory) {
-        if (!memoryCoreEntry) {
-            entries['memory-core'] = { enabled: false };
-            messages.push('Set memory-core.enabled to false');
-        }
-        else if (memoryCoreEntry.enabled !== false) {
-            memoryCoreEntry.enabled = false;
-            messages.push('Set memory-core.enabled to false');
-        }
-    }
-    else if (mode === 'add' && !options.memory) {
-        // Non-memory install: re-enable memory-core if we disabled it
-        if (memoryCoreEntry && memoryCoreEntry.enabled === false) {
-            memoryCoreEntry.enabled = true;
-            messages.push('Re-enabled memory-core (non-memory install)');
-        }
-    }
-    else if (mode === 'remove') {
-        // Uninstall: re-enable memory-core if we disabled it
-        if (memoryCoreEntry && memoryCoreEntry.enabled === false) {
-            memoryCoreEntry.enabled = true;
-            messages.push('Re-enabled memory-core');
-        }
-    }
     // tools.allow
     const tools = (config.tools ?? {});
     const toolAllow = patchAllowList(tools, 'allow', 'tools.allow', mode);
@@ -167,7 +113,7 @@ function patchConfig(config, mode, options = {}) {
     return messages;
 }
 /** Install the plugin into OpenClaw's extensions directory. */
-function install(memoryMode) {
+function install() {
     const home = resolveOpenClawHome();
     const configPath = resolveConfigPath(home);
     const extDir = join(home, 'extensions', PLUGIN_ID);
@@ -176,7 +122,6 @@ function install(memoryMode) {
     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}`);
@@ -212,20 +157,6 @@ function install(memoryMode) {
         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...');
@@ -234,19 +165,13 @@ function install(memoryMode) {
         console.error(`Error: Could not parse ${configPath}`);
         process.exit(1);
     }
-    for (const msg of patchConfig(config, 'add', { memory: memoryMode })) {
+    for (const msg of patchConfig(config, 'add')) {
         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() {
@@ -280,10 +205,9 @@ function uninstall() {
 }
 // Main
 const command = process.argv[2];
-const memoryFlag = process.argv.includes('--memory');
 switch (command) {
     case 'install':
-        install(memoryFlag);
+        install();
         break;
     case 'uninstall':
         uninstall();
@@ -292,11 +216,8 @@ switch (command) {
         console.log(`@karmaniverous/jeeves-watcher-openclaw — OpenClaw plugin installer`);
         console.log();
         console.log('Usage:');
-        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('  npx @karmaniverous/jeeves-watcher-openclaw install    Install plugin');
+        console.log('  npx @karmaniverous/jeeves-watcher-openclaw uninstall  Remove plugin');
         console.log();
         console.log('Environment variables:');
         console.log('  OPENCLAW_CONFIG  Path to openclaw.json (overrides all)');

package/dist/index.js

@@ -1,52 +1,13 @@
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { readFile } from 'node:fs/promises';
-
 /**
  * @module plugin/helpers
  * Shared types and utility functions for the OpenClaw plugin tool registrations.
  */
 const DEFAULT_API_URL = 'http://127.0.0.1:1936';
-/** Source identifier for virtual rule registration. */
-const PLUGIN_SOURCE = 'jeeves-watcher-openclaw';
-/** Normalize a path to forward slashes and lowercase drive letter on Windows. */
-function normalizePath(p) {
-    return p.replace(/\\/g, '/');
-}
-/**
- * Resolve the workspace path from gateway config.
- * Priority: agent-specific \> defaults \> fallback (~/.openclaw/workspace).
- */
-function getWorkspacePath(api) {
-    const agentWorkspace = api.config?.agents?.entries?.['main']?.workspace ??
-        api.config?.agents?.defaults?.workspace;
-    return agentWorkspace ?? join(homedir(), '.openclaw', 'workspace');
-}
 /** Resolve the watcher API base URL from plugin config. */
 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 {
@@ -102,204 +63,6 @@ async function postJson(url, body) {
     });
 }
 
-/**
- * @module plugin/memoryTools
- * memory_search and memory_get tool implementations with lazy init.
- *
- * Lazy init registers virtual inference rules with the watcher on first
- * memory_search call. Re-attempts on failure. memory_get reads files
- * directly from the filesystem with path validation.
- */
-/** 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: RULE_LONGTERM,
-            description: 'OpenClaw long-term memory file',
-            match: {
-                properties: {
-                    file: {
-                        properties: {
-                            path: { glob: `${ws}/MEMORY.md` },
-                        },
-                    },
-                },
-            },
-            schema: [longtermInternal, ...(userSchemas[RULE_LONGTERM] ?? [])],
-        },
-        {
-            name: RULE_DAILY,
-            description: 'OpenClaw daily memory logs',
-            match: {
-                properties: {
-                    file: {
-                        properties: {
-                            path: { glob: `${ws}/memory/**/*.md` },
-                        },
-                    },
-                },
-            },
-            schema: [dailyInternal, ...(userSchemas[RULE_DAILY] ?? [])],
-        },
-    ];
-}
-/** Validate a path is within the memory scope. */
-function isAllowedMemoryPath(filePath, workspace) {
-    const norm = normalizePath(filePath).toLowerCase();
-    const ws = normalizePath(workspace).toLowerCase();
-    // Exact match: {workspace}/MEMORY.md
-    if (norm === `${ws}/memory.md`)
-        return true;
-    // Prefix match: {workspace}/memory/**/*.md
-    if (norm.startsWith(`${ws}/memory/`) && norm.endsWith('.md'))
-        return true;
-    return false;
-}
-/**
- * Create memory tool registrations for the plugin.
- * Returns register functions for memory_search and memory_get.
- */
-function createMemoryTools(api, baseUrl) {
-    const workspace = getWorkspacePath(api);
-    const userSchemas = getPluginSchemas(api);
-    const state = {
-        initialized: false,
-        lastWatcherUptime: 0,
-        workspace,
-        baseUrl,
-    };
-    /** Lazy init: register virtual rules with watcher. */
-    async function ensureInit() {
-        // Check watcher is reachable and detect restarts
-        const status = (await fetchJson(`${state.baseUrl}/status`));
-        const uptime = status.uptime ?? 0;
-        // If watcher restarted (uptime decreased), re-register virtual rules
-        if (state.initialized && uptime >= state.lastWatcherUptime)
-            return;
-        state.lastWatcherUptime = uptime;
-        // Clear any stale rules
-        await fetchJson(`${state.baseUrl}/rules/unregister`, {
-            method: 'DELETE',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ source: PLUGIN_SOURCE }),
-        });
-        // Register virtual rules
-        const virtualRules = buildVirtualRules(state.workspace, userSchemas);
-        await postJson(`${state.baseUrl}/rules/register`, {
-            source: PLUGIN_SOURCE,
-            rules: virtualRules,
-        });
-        // Re-apply rules to already-indexed files matching virtual rule globs
-        const globs = virtualRules
-            .map((r) => {
-            const path = r.match.properties.file.properties.path;
-            return typeof path.glob === 'string' ? path.glob : undefined;
-        })
-            .filter((g) => g !== undefined);
-        if (globs.length > 0) {
-            try {
-                await postJson(`${state.baseUrl}/rules/reapply`, { globs });
-            }
-            catch {
-                // Non-fatal: files will get correct rules on next change
-            }
-        }
-        state.initialized = true;
-    }
-    const memorySearch = async (_id, params) => {
-        try {
-            await ensureInit();
-            const body = {
-                query: params.query,
-                filter: {
-                    must: [{ key: PROP_SOURCE, match: { value: SOURCE_MEMORY } }],
-                },
-            };
-            if (params.maxResults !== undefined)
-                body.limit = params.maxResults;
-            const raw = await postJson(`${state.baseUrl}/search`, body);
-            // Map results to system-prompt-compatible format
-            const results = raw.map((r) => {
-                const payload = r.payload;
-                const mapped = {
-                    path: payload.file_path,
-                    snippet: payload.chunk_text,
-                    score: r.score,
-                };
-                if (payload.line_start != null)
-                    mapped.from = payload.line_start;
-                if (payload.line_end != null)
-                    mapped.to = payload.line_end;
-                return mapped;
-            });
-            const minScore = typeof params.minScore === 'number' ? params.minScore : 0;
-            const filtered = results.filter((r) => typeof r.score === 'number' && r.score >= minScore);
-            return ok({ provider: 'jeeves-watcher', results: filtered });
-        }
-        catch (error) {
-            state.initialized = false;
-            return connectionFail(error, state.baseUrl);
-        }
-    };
-    const memoryGet = async (_id, params) => {
-        try {
-            const filePath = String(params.path);
-            // Re-derive workspace on every call for immediate pickup of moves
-            const currentWorkspace = getWorkspacePath(api);
-            if (!isAllowedMemoryPath(filePath, currentWorkspace)) {
-                return fail(`Path not within memory scope. Allowed: ${currentWorkspace}/MEMORY.md and ${currentWorkspace}/memory/**/*.md`);
-            }
-            const content = await readFile(filePath, 'utf-8');
-            if (params.from !== undefined) {
-                const from = Number(params.from);
-                const lines = content.split('\n');
-                const startIdx = Math.max(0, from - 1); // 1-indexed to 0-indexed
-                const count = params.lines !== undefined
-                    ? Number(params.lines)
-                    : lines.length - startIdx;
-                const sliced = lines.slice(startIdx, startIdx + count);
-                return ok({ provider: 'jeeves-watcher', content: sliced.join('\n') });
-            }
-            return ok({ provider: 'jeeves-watcher', content });
-        }
-        catch (error) {
-            return fail(error);
-        }
-    };
-    return { memorySearch, memoryGet };
-}
-
 /**
  * @module plugin/watcherTools
  * Watcher tool registrations (watcher_* tools) for the OpenClaw plugin.
@@ -485,53 +248,7 @@ function registerWatcherTools(api, baseUrl) {
 /** Register all jeeves-watcher tools with the OpenClaw plugin API. */
 function register(api) {
     const baseUrl = getApiUrl(api);
-    // Register 8 watcher_* tools
     registerWatcherTools(api, baseUrl);
-    // Register memory slot tools (memory_search + memory_get)
-    const { memorySearch, memoryGet } = createMemoryTools(api, baseUrl);
-    api.registerTool({
-        name: 'memory_search',
-        description: 'Semantically search MEMORY.md and memory/*.md files. Returns top snippets with path and line numbers.',
-        parameters: {
-            type: 'object',
-            required: ['query'],
-            properties: {
-                query: { type: 'string', description: 'Search query text.' },
-                maxResults: {
-                    type: 'number',
-                    description: 'Maximum results to return.',
-                },
-                minScore: {
-                    type: 'number',
-                    description: 'Minimum similarity score threshold.',
-                },
-            },
-        },
-        execute: memorySearch,
-    });
-    api.registerTool({
-        name: 'memory_get',
-        description: 'Read content from MEMORY.md or memory/*.md files with optional line range.',
-        parameters: {
-            type: 'object',
-            required: ['path'],
-            properties: {
-                path: {
-                    type: 'string',
-                    description: 'Path to the memory file to read.',
-                },
-                from: {
-                    type: 'number',
-                    description: 'Line number to start reading from (1-indexed).',
-                },
-                lines: {
-                    type: 'number',
-                    description: 'Number of lines to read.',
-                },
-            },
-        },
-        execute: memoryGet,
-    });
 }
 
 export { register as default };

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

@@ -3,8 +3,8 @@ name: jeeves-watcher
 description: >
   Semantic search across a structured document archive. Use when you need to
   recall prior context, find documents, answer questions that require searching
-  across domains (email, Slack, Jira, codebase, meetings, projects), enrich
-  document metadata, manage watcher config, or diagnose indexing issues.
+  across indexed domains, enrich document metadata, manage watcher config, or
+  diagnose indexing issues.
 ---
 
 # jeeves-watcher — Search, Discovery & Administration
@@ -54,15 +54,17 @@ curl -X POST http://127.0.0.1:<PORT>/config/query \
 
 ## Theory of Operation
 
-You have access to a **semantic archive** of your human's working world: email, Slack messages, Jira tickets, code repositories, meeting notes, project documents, and more. Everything is indexed, chunked, embedded, and searchable. This is your long-term memory for anything beyond the current conversation.
+You have access to a **semantic archive** of your human's working world. Documents, messages, tickets, notes, code, and other artifacts are indexed, chunked, embedded, and searchable. This is your long-term recall for anything beyond the current conversation.
+
+**Every deployment is different.** The archive's structure, domains, metadata fields, and record types are all defined by the deployment's configuration. Do not assume any particular domains exist (e.g., "email", "slack", "jira"). Always discover what's available using the Orientation Pattern below. Examples in this skill use common domain names for illustration only.
 
 **When to reach for the watcher:**
 
-- **Someone asks about something that happened.** A meeting, a decision, a conversation, a ticket. You weren't there, but the archive was. Search it.
+- **Someone asks about something that happened.** A meeting, a decision, a conversation, a ticket, a message. You weren't there, but the archive was. Search it.
 - **You need context you don't have.** Before asking the human "what's the status of X?", search for X. The answer is probably already indexed.
-- **You're working on a project and need background.** Architecture decisions, prior discussions, related tickets, relevant code. Search by topic, filter by domain.
+- **You're working on something and need background.** Prior discussions, related records, relevant documents. Search by topic, filter by domain.
 - **You need to verify something.** Don't guess from stale memory. Search for the current state.
-- **You want to connect dots across domains.** The same topic might appear in a Jira ticket, a Slack thread, an email, and a code commit. A single semantic search surfaces all of them.
+- **You want to connect dots across domains.** The same topic might appear in multiple domains. A single semantic search surfaces all of them.
 
 **When NOT to use it:**
 
@@ -72,10 +74,10 @@ You have access to a **semantic archive** of your human's working world: email,
 
 ## Memory → Archive Escalation
 
-You have two search tools with different scopes:
+You have two complementary tools with different scopes:
 
-- **`memory_search`** — curated notes (MEMORY.md + memory/*.md). High signal, small scope. This is your long-term memory: decisions, rules, people, project context. Always check here first.
-- **`watcher_search`** — the full indexed archive (160K+ points across all domains: Slack, email, Jira, code, meetings, tweets, projects). Broad scope, raw record.
+- **memory-core** (`memory_search` / `memory_get`) — OpenClaw's built-in memory provider. Manages curated notes in MEMORY.md and memory/*.md. High signal, small scope. This is your long-term memory: decisions, rules, people, project context. Always check here first.
+- **watcher** (`watcher_search`) — the full indexed archive across all configured domains. Broad scope, raw record.
 
 **The escalation rule:** When `memory_search` returns thin, zero, or low-confidence results for something your human clearly expects you to know about — a person, a project, an event, a thing — don't stop there. Follow up with `watcher_search` across the full index.
 
@@ -90,96 +92,280 @@ You have two search tools with different scopes:
 - The question is about your own operational rules or preferences (that's purely memory)
 - You've already searched the archive this turn
 
-**Example:** "Tell me about Noodle" → memory says "male, he/him" → that's thin → escalate to `watcher_search("Noodle")` → tweets reveal #NoodleThePoodle with photos. Report the full picture.
+**Example:** "Tell me about Project X" → memory says "started in January" → that's thin → escalate to `watcher_search("Project X")` → tickets, messages, and docs reveal the full history. Report the full picture.
+
+**The principle:** Memory-core is your curated highlights. The watcher archive is your perfect recall. Use memory first for speed and signal, but never let its narrow scope be the ceiling of what you can remember.
+
+## Embedding Alignment
+
+Memory-core and the watcher both use embeddings, but may use different models by default. For best cross-tool consistency, offer to configure memory-core to use `gemini-embedding-001` (the same model the watcher uses) via the gateway config:
+
+1. **Verify Google API key** — check that the gateway has a Google API key configured (needed for Gemini embeddings).
+2. **Apply config** — use `gateway config.patch` to set the memory-core embedding provider:
+   ```json
+   {
+     "agents": {
+       "defaults": {
+         "memorySearch": {
+           "provider": "gemini",
+           "model": "gemini-embedding-001"
+         }
+       }
+     }
+   }
+   ```
+3. **Restart gateway** to pick up the new embedding provider. Memory-core will re-embed all memory files on next sync (dimension change triggers automatic vector table recreation).
+
+This gives memory-core the same 3072-dimensional Gemini embeddings the watcher uses, ensuring semantic similarity scores are comparable across memory and archive searches.
 
-**The principle:** Memory is your curated highlights. The archive is your perfect recall. Use memory first for speed and signal, but never let its narrow scope be the ceiling of what you can remember.
+## Plugin Installation
 
-**How it works, conceptually:**
+```
+npx @karmaniverous/jeeves-watcher-openclaw install
+```
 
-The watcher monitors directories on the filesystem. When files change, it extracts text, applies **inference rules** (config-driven pattern matching) to derive structured metadata, and embeds everything into a vector store. Each inference rule defines a record type: what files it matches, what metadata schema applies, how to extract fields.
+This copies the plugin to OpenClaw's extensions directory and patches `openclaw.json` to register it. Restart the gateway to load the plugin.
 
-You don't need to know the rules in advance. The config is introspectable at runtime. Orient once per session, then search with confidence.
+To remove:
+```
+npx @karmaniverous/jeeves-watcher-openclaw uninstall
+```
 
-**Key mental model:** Think of it as a search engine scoped to your human's data, with structured metadata on every result. Plain semantic search works. Adding metadata filters makes it precise.
+## Quick Start (Existing Deployment)
 
-## Quick Start
+If the watcher service is already running and healthy:
 
 1. **Orient yourself** (once per session) — use `watcher_query` to learn the deployment's organizational strategy and available record types (see Orientation Pattern below)
 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)
+## Bootstrap (First-Time Setup)
 
-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.
+When the plugin loads and the watcher service is NOT yet set up, drive the entire setup proactively. The user should be able to install the plugin with nothing else in place and the bootstrap process gets them to a working system.
 
-**Automatic bootstrap sequence:**
+**The agent drives this process.** Don't hand the user CLI commands and wait. Check each prerequisite, explain what's needed, execute what you can, and prompt the user only for decisions that require human judgment.
 
-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.
+### Step 1: Check Node.js
 
-**On subsequent sessions:** Repeat steps 1-3 silently. Only report if something changed (service down, point count dropped significantly, new domains appeared).
+Verify Node.js is installed and version ≥ 20:
+```bash
+node --version
+```
 
-**Key principle:** The agent drives discovery. The user shouldn't have to explain their archive to you — the archive explains itself through its config.
+If missing or too old, guide the user to install Node.js 20+ from https://nodejs.org or via their package manager.
 
-## Install Modes
+### Step 2: Install Qdrant
 
-The plugin supports two install modes, controlled by the `--memory` flag during installation:
+Check if Qdrant is already running:
+```bash
+curl -s http://localhost:6333/healthz
+```
 
-**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 (re-enabled if previously disabled)
-- Use when the watcher is a supplementary search tool alongside native memory
+If not running, install it. **Prefer native installation** (especially on cloud instances where Docker may not be available):
+
+**Linux (recommended for servers):**
+```bash
+# Download latest release
+curl -L https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-unknown-linux-musl.tar.gz -o qdrant.tar.gz
+tar xzf qdrant.tar.gz
+
+# Run (foreground for testing)
+./qdrant
+
+# For production: create a systemd service
+sudo tee /etc/systemd/system/qdrant.service > /dev/null <<EOF
+[Unit]
+Description=Qdrant Vector Database
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=/usr/local/bin/qdrant --config-path /etc/qdrant/config.yaml
+Restart=always
+User=qdrant
+
+[Install]
+WantedBy=multi-user.target
+EOF
+sudo systemctl enable --now qdrant
+```
 
-**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
-- Disables `memory-core` (`plugins.entries.memory-core.enabled: false`) to prevent core memory tools from shadowing the plugin's tools
-- 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
+**Windows:**
+```powershell
+# Download from GitHub releases page
+# https://github.com/qdrant/qdrant/releases
+# Extract and run, or register as NSSM service:
+nssm install Qdrant <path-to-qdrant.exe>
+nssm start Qdrant
+```
 
-**Why `memory-core` must be disabled:** OpenClaw's built-in `memory-core` plugin registers its own `memory_search` and `memory_get` tools. If both `memory-core` and this plugin are enabled, the core tools shadow the plugin's tools (same name, core registers first). Disabling `memory-core` ensures the plugin's Qdrant-backed implementations are the ones that execute.
+**Docker (fallback, if available):**
+```bash
+docker run -d -p 6333:6333 -v qdrant_data:/qdrant/storage qdrant/qdrant
+```
 
-**How to tell which mode you're in:** Check the response from `memory_search` or `memory_get`. In memory mode (watcher-backed), responses include `"provider": "jeeves-watcher"`. In standard mode (memory-core), responses are bare arrays/strings with no `provider` field.
+After installation, verify:
+```bash
+curl -s http://localhost:6333/healthz
+```
 
-## Proactive Posture
+### Step 3: Install Watcher Service
 
-**On your first `memory_search` or `memory_get` call each session, check the response for the `provider` field.**
+Install the watcher CLI globally:
+```bash
+npm install -g @karmaniverous/jeeves-watcher
+```
 
-- **If the response is `{ provider: "jeeves-watcher", ... }`:** You're in memory mode. The watcher is serving memory. No action needed.
-- **If the response has any other shape** (bare array, bare string, different provider, no `provider` field): The watcher is NOT serving memory. Another provider is active. Check whether an upgrade is warranted.
+Verify:
+```bash
+jeeves-watcher --version
+```
 
-**When to suggest upgrading to memory mode:**
-Call `watcher_status` to check the archive size. If the watcher has >10K points, the deployment has a substantial archive and would benefit from semantic memory. Offer to run the upgrade yourself:
+### Step 4: Set Up Embedding Provider
 
-> "I notice memory queries are running on flat file search, but the watcher has [N] points with semantic embeddings. I can upgrade to memory mode now — this runs `npx @karmaniverous/jeeves-watcher-openclaw install --memory` and restarts the gateway. Shall I go ahead?"
+The watcher uses Google Gemini for embeddings by default (`gemini-embedding-001`, 3072 dimensions).
 
-If the user agrees, execute the install and gateway restart. Don't hand them a CLI command when you can do it yourself.
+Check for an existing API key:
+```bash
+echo $GOOGLE_API_KEY    # Linux/Mac
+echo %GOOGLE_API_KEY%   # Windows cmd
+$env:GOOGLE_API_KEY     # PowerShell
+```
 
-**Don't nag.** Suggest once per session at most. If the user declines, drop it.
+If not set, guide the user:
+1. Go to https://aistudio.google.com/apikey
+2. Create an API key (free tier supports 1,000 embedding requests/minute)
+3. Set it as a persistent environment variable:
+   - **Linux:** Add `export GOOGLE_API_KEY=<key>` to `~/.bashrc` or `~/.profile`
+   - **Windows:** `setx GOOGLE_API_KEY "<key>"` (new shell sessions only) or set via System Properties → Environment Variables
+   - **macOS:** Add to `~/.zshrc` or use `launchctl setenv`
+
+Verify the key works by testing a Gemini API call:
+```bash
+curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent?key=$GOOGLE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"models/gemini-embedding-001","content":{"parts":[{"text":"test"}]}}'
+```
 
-## Tools
+A successful response contains an `embedding.values` array.
 
-### `memory_search`
-Semantically search MEMORY.md and memory/*.md files. Powered by the watcher's vector store with Gemini 3072-dim embeddings.
-- `query` (string, required) — search query text
-- `maxResults` (number, optional) — maximum results to return
-- `minScore` (number, optional) — minimum similarity score threshold
+### Step 5: Author Initial Config
 
-**Response (memory mode):** `{ provider: "jeeves-watcher", results: [{ path, from, to, snippet, score }] }` where `from`/`to` are 1-indexed line numbers.
-**Response (standard mode / memory-core):** `[{ path, from, to, snippet, score }]` — bare array, no `provider` field.
+Ask the user these questions:
+- **What directories should the watcher index?** (e.g., `~/documents`, `~/projects`, a workspace path)
+- **What types of files matter?** (helps determine file extensions for watch globs)
+- **Are there directories to exclude?** (node_modules, .git, build outputs, etc.)
 
-### `memory_get`
-Read content from MEMORY.md or memory/*.md files with optional line range.
-- `path` (string, required) — path to the memory file
-- `from` (number, optional) — line number to start reading from (1-indexed)
-- `lines` (number, optional) — number of lines to read
+Then generate a starter config file. Example minimal config:
 
-**Response (memory mode):** `{ provider: "jeeves-watcher", content: "file content..." }`
-**Response (standard mode / memory-core):** `"file content..."` — bare string, no `provider` field.
+```json
+{
+  "description": "Personal knowledge base indexing",
+  "api": { "port": 1936 },
+  "watch": {
+    "paths": [
+      "/home/user/documents/**/*.{md,txt,json,pdf,html,docx}"
+    ],
+    "ignored": ["**/node_modules/**", "**/.git/**", "**/dist/**"]
+  },
+  "embedding": {
+    "provider": "gemini",
+    "model": "gemini-embedding-001",
+    "dimensions": 3072,
+    "apiKey": "${GOOGLE_API_KEY}",
+    "chunkSize": 1000,
+    "chunkOverlap": 200,
+    "rateLimitPerMinute": 1000,
+    "concurrency": 5
+  },
+  "vectorStore": {
+    "url": "http://localhost:6333",
+    "collection": "jeeves_archive"
+  },
+  "search": {
+    "scoreThresholds": { "strong": 0.75, "relevant": 0.5, "noise": 0.25 },
+    "hybrid": { "enabled": true }
+  },
+  "logging": { "level": "info" },
+  "inferenceRules": []
+}
+```
 
-Path validation: only files within the workspace's MEMORY.md and memory/**/*.md are accessible.
+Write the config to a sensible location (e.g., `~/.config/jeeves-watcher.config.json` on Linux, or alongside the user's workspace). Validate with:
+```bash
+jeeves-watcher validate -c <config-path>
+```
+
+### Step 6: Register and Start as a Service
+
+**The watcher should run as a persistent service, not a foreground process.**
+
+**Linux (systemd):**
+```bash
+sudo tee /etc/systemd/system/jeeves-watcher.service > /dev/null <<EOF
+[Unit]
+Description=Jeeves Watcher - Filesystem Indexing Service
+After=network.target qdrant.service
+
+[Service]
+Type=simple
+ExecStart=$(which jeeves-watcher) start -c <config-path>
+Restart=always
+Environment=GOOGLE_API_KEY=<key>
+User=$USER
+
+[Install]
+WantedBy=multi-user.target
+EOF
+sudo systemctl enable --now jeeves-watcher
+```
+
+**Windows (NSSM):**
+```powershell
+jeeves-watcher service install
+# Or manually:
+nssm install jeeves-watcher "$(which jeeves-watcher)" start -c <config-path>
+nssm set jeeves-watcher AppEnvironmentExtra GOOGLE_API_KEY=<key>
+nssm start jeeves-watcher
+```
+
+Verify the service started:
+```bash
+curl -s http://127.0.0.1:1936/status
+```
+
+### Step 7: Verify Health
+
+Call `watcher_status` (or `curl http://127.0.0.1:1936/status`). Confirm:
+- Service is running
+- Qdrant collection exists with expected dimensions (3072)
+- Point count is increasing (initial indexing in progress)
+
+If the point count is 0 after a minute, check `watcher_issues` for embedding failures.
+
+### Step 8: Orientation
+
+Once health is confirmed and initial indexing has started:
+
+1. Query `$.['description','search']` for the deployment's organizational strategy and score thresholds.
+2. Query `$.inferenceRules[*].['name','description']` for available record types.
+3. Report to the user: how many points indexed so far, which domains are available, estimated time to complete initial indexing (based on file count and embedding rate).
+
+### Step 9: Align Memory-Core Embeddings
+
+After the watcher is healthy, offer to align OpenClaw's memory-core with the same embedding model for consistent vector quality across both systems. See the **Embedding Alignment** section above for the procedure.
+
+### On Subsequent Sessions
+
+On sessions after bootstrap is complete:
+
+1. Call `watcher_status` silently.
+2. Run the orientation queries silently.
+3. 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.
+
+## Tools
 
 ### `watcher_search`
 Semantic search over indexed documents.
@@ -227,6 +413,8 @@ Get runtime embedding failures. Returns `{ filePath: IssueRecord }` showing file
 
 Filters use Qdrant's native JSON filter format, passed as the `filter` parameter to `watcher_search`.
 
+> **Note:** The field names and values used in these examples (e.g., `domain`, `status`, `assignee`) are illustrative. Actual fields depend on the deployment's inference rules. Use the Orientation Pattern and Query Planning sections to discover what's available before constructing filters.
+
 ### Basic Patterns
 
 **Match exact value:**
@@ -442,7 +630,7 @@ Compose individual field conditions into complex queries using three combinators
     { "key": "created", "range": { "gte": 1735689600 } }
   ],
   "should": [
-    { "key": "assignee", "match": { "value": "Jason Williscroft" } },
+    { "key": "assignee", "match": { "value": "Jane Doe" } },
     { "key": "assignee", "match": { "value": null } }
   ],
   "must_not": [

package/dist/src/cli.d.ts

@@ -2,13 +2,9 @@
  * CLI for installing/uninstalling the jeeves-watcher OpenClaw plugin.
  *
  * Usage:
- *   npx \@karmaniverous/jeeves-watcher-openclaw install [--memory]
+ *   npx \@karmaniverous/jeeves-watcher-openclaw install
  *   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).
  *
@@ -17,10 +13,5 @@
  *   - 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', options?: PatchConfigOptions): string[];
+export declare function patchConfig(config: Record<string, unknown>, mode: 'add' | 'remove'): string[];

package/dist/src/helpers.d.ts

@@ -10,14 +10,6 @@ export interface PluginApi {
                 config?: Record<string, unknown>;
             }>;
         };
-        agents?: {
-            entries?: Record<string, {
-                workspace?: string;
-            }>;
-            defaults?: {
-                workspace?: string;
-            };
-        };
     };
     registerTool(tool: {
         name: string;
@@ -36,28 +28,8 @@ export interface ToolResult {
     }>;
     isError?: boolean;
 }
-/** Source identifier for virtual rule registration. */
-export declare const PLUGIN_SOURCE = "jeeves-watcher-openclaw";
-/** Normalize a path to forward slashes and lowercase drive letter on Windows. */
-export declare function normalizePath(p: string): string;
-/**
- * Resolve the workspace path from gateway config.
- * 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/openclaw.plugin.json

@@ -2,7 +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.13",
+  "version": "0.4.1",
   "skills": [
     "dist/skills/jeeves-watcher"
   ],
@@ -13,14 +13,14 @@
       "apiUrl": {
         "type": "string",
         "description": "jeeves-watcher API base URL",
-        "default": "http://127.0.0.1:3458"
+        "default": "http://127.0.0.1:1936"
       }
     }
   },
   "uiHints": {
     "apiUrl": {
       "label": "Watcher API URL",
-      "placeholder": "http://127.0.0.1:3458"
+      "placeholder": "http://127.0.0.1:1936"
     }
   }
 }

package/package.json

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

package/dist/src/memoryTools.d.ts

@@ -1,25 +0,0 @@
-/**
- * @module plugin/memoryTools
- * memory_search and memory_get tool implementations with lazy init.
- *
- * Lazy init registers virtual inference rules with the watcher on first
- * memory_search call. Re-attempts on failure. memory_get reads files
- * 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.
- */
-export declare function createMemoryTools(api: PluginApi, baseUrl: string): {
-    memorySearch: (_id: string, params: Record<string, unknown>) => Promise<ToolResult>;
-    memoryGet: (_id: string, params: Record<string, unknown>) => Promise<ToolResult>;
-};

package/dist/src/memoryTools.test.d.ts

@@ -1 +0,0 @@
-export {};