@getplumb/openclaw-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plumb 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
+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,45 @@
+# @getplumb/openclaw-plugin
+
+> Plumb memory plugin for [OpenClaw](https://openclaw.ai)
+
+Automatically ingests conversations and injects relevant memory context into every AI response — no "remember this" commands needed.
+
+## What it does
+
+- **Auto-ingest:** every conversation turn is stored to your local Plumb DB after the response
+- **Context injection:** relevant memory facts are injected into the system prompt before each response
+- **Shadow mode:** try it without injection first — observe what would be injected
+
+## Install
+
+```bash
+npm install @getplumb/openclaw-plugin
+```
+
+Then add to your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "plumb": {
+      "package": "@getplumb/openclaw-plugin",
+      "dbPath": "~/.plumb/memory.db",
+      "userId": "your-user-id",
+      "shadowMode": false
+    }
+  },
+  "slots": {
+    "memory": "plumb"
+  }
+}
+```
+
+## Links
+
+- [Docs](https://docs.getplumb.dev)
+- [GitHub](https://github.com/getplumb/plumb)
+- [getplumb.dev](https://getplumb.dev)
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+export interface PlumbPluginConfig {
+    /** Path to the @plumb/mcp-server binary (e.g. node_modules/.bin/plumb-mcp). */
+    mcpServerPath: string;
+    /** User identifier for multi-user setups. */
+    userId: string;
+    /** Whether the plugin is active. */
+    enabled: boolean;
+    /** Path to the Plumb database file. If not provided, defaults to ~/.plumb/memory.db */
+    dbPath?: string;
+    /** If true: retrieve but don't inject (for validation). Default: false. */
+    shadowMode: boolean;
+}
+export declare const DEFAULT_CONFIG: PlumbPluginConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,aAAa,EAAE,MAAM,CAAC;IAEtB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IAEf,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IAEjB,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,2EAA2E;IAC3E,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,eAAO,MAAM,cAAc,EAAE,iBAK5B,CAAC"}

package/dist/config.js

@@ -0,0 +1,7 @@
+export const DEFAULT_CONFIG = {
+    mcpServerPath: 'plumb-mcp',
+    userId: 'default',
+    enabled: true,
+    shadowMode: false,
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAiBA,MAAM,CAAC,MAAM,cAAc,GAAsB;IAC/C,aAAa,EAAE,WAAW;IAC1B,MAAM,EAAE,SAAS;IACjB,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,KAAK;CAClB,CAAC"}

package/dist/error-logger.d.ts

@@ -0,0 +1,17 @@
+export interface ErrorLogEntry {
+    timestamp: string;
+    type: string;
+    message: string;
+    stack?: string;
+    context?: Record<string, unknown>;
+}
+/**
+ * Appends an error entry to ~/.plumb/errors.log (or PLUMB_DB_PATH parent if set).
+ * Format: JSONL (one JSON object per line).
+ *
+ * This function never throws — if the write fails, it silently logs to console.error only.
+ *
+ * @param entry - Error log entry with timestamp, type, message, and optional stack/context
+ */
+export declare function appendError(entry: ErrorLogEntry): void;
+//# sourceMappingURL=error-logger.d.ts.map

package/dist/error-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-logger.d.ts","sourceRoot":"","sources":["../src/error-logger.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAkBD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAetD"}

package/dist/error-logger.js

@@ -0,0 +1,40 @@
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { appendFileSync, mkdirSync } from 'node:fs';
+/**
+ * Derives the error log path from the DB path (if set) or defaults to ~/.plumb/errors.log.
+ * If PLUMB_DB_PATH environment variable is set, we use its parent directory.
+ */
+function getErrorLogPath() {
+    const dbPath = process.env.PLUMB_DB_PATH;
+    if (dbPath) {
+        // Use the parent directory of the DB path
+        return join(dirname(dbPath), 'errors.log');
+    }
+    // Default: ~/.plumb/errors.log
+    return join(homedir(), '.plumb', 'errors.log');
+}
+/**
+ * Appends an error entry to ~/.plumb/errors.log (or PLUMB_DB_PATH parent if set).
+ * Format: JSONL (one JSON object per line).
+ *
+ * This function never throws — if the write fails, it silently logs to console.error only.
+ *
+ * @param entry - Error log entry with timestamp, type, message, and optional stack/context
+ */
+export function appendError(entry) {
+    try {
+        const logPath = getErrorLogPath();
+        const logDir = dirname(logPath);
+        // Ensure directory exists
+        mkdirSync(logDir, { recursive: true });
+        // Write JSONL: one JSON object per line
+        const line = JSON.stringify(entry) + '\n';
+        appendFileSync(logPath, line, 'utf-8');
+    }
+    catch (err) {
+        // Non-blocking: if the log write itself fails, just console.error
+        console.error('[plumb/error-logger] Failed to write error log:', err);
+    }
+}
+//# sourceMappingURL=error-logger.js.map

package/dist/error-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-logger.js","sourceRoot":"","sources":["../src/error-logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAUpD;;;GAGG;AACH,SAAS,eAAe;IACtB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IAEzC,IAAI,MAAM,EAAE,CAAC;QACX,0CAA0C;QAC1C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,CAAC;IAC7C,CAAC;IAED,+BAA+B;IAC/B,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,KAAoB;IAC9C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,eAAe,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAEhC,0BAA0B;QAC1B,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAEvC,wCAAwC;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;QAC1C,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,kEAAkE;QAClE,OAAO,CAAC,KAAK,CAAC,iDAAiD,EAAE,GAAG,CAAC,CAAC;IACxE,CAAC;AACH,CAAC"}

package/dist/hooks/post-exchange.d.ts

@@ -0,0 +1,31 @@
+import type { LocalStore } from '@getplumb/core';
+type PluginHookLlmOutputEvent = {
+    runId: string;
+    sessionId: string;
+    provider: string;
+    model: string;
+    assistantTexts: string[];
+    usage?: {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        total?: number;
+    };
+};
+type PluginHookAgentContext = {
+    agentId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+    workspaceDir?: string;
+    messageProvider?: string;
+};
+/**
+ * Creates a hook handler that ingests every LLM exchange into the local store.
+ *
+ * Fire-and-forget pattern: returns void synchronously, ingests in background.
+ * Errors are caught and logged silently to avoid disrupting the agent flow.
+ */
+export declare function createPostExchangeHook(store: LocalStore, userId: string): (event: PluginHookLlmOutputEvent, ctx: PluginHookAgentContext) => void;
+export {};
+//# sourceMappingURL=post-exchange.d.ts.map

package/dist/hooks/post-exchange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-exchange.d.ts","sourceRoot":"","sources":["../../src/hooks/post-exchange.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAIjD,KAAK,wBAAwB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE;QACN,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAAC;AAEF,KAAK,sBAAsB,GAAG;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,IAC9D,OAAO,wBAAwB,EAAE,KAAK,sBAAsB,KAAG,IAAI,CA4C5E"}

package/dist/hooks/post-exchange.js

@@ -0,0 +1,52 @@
+import { appendError } from '../error-logger.js';
+/**
+ * Creates a hook handler that ingests every LLM exchange into the local store.
+ *
+ * Fire-and-forget pattern: returns void synchronously, ingests in background.
+ * Errors are caught and logged silently to avoid disrupting the agent flow.
+ */
+export function createPostExchangeHook(store, userId) {
+    return (event, ctx) => {
+        const exchange = {
+            id: crypto.randomUUID(),
+            userId,
+            sessionId: ctx.sessionId ?? event.sessionId ?? crypto.randomUUID(),
+            sessionLabel: ctx.sessionKey,
+            userMessage: event.prompt ?? '',
+            agentResponse: event.assistantTexts.join('\n'),
+            timestamp: new Date().toISOString(),
+            source: 'openclaw',
+        };
+        // Fire-and-forget ingest — never blocks the hook
+        (async () => {
+            try {
+                await store.ingest({
+                    userMessage: exchange.userMessage,
+                    agentResponse: exchange.agentResponse,
+                    timestamp: new Date(exchange.timestamp),
+                    source: exchange.source,
+                    sessionId: exchange.sessionId,
+                    ...(exchange.sessionLabel && { sessionLabel: exchange.sessionLabel }),
+                });
+            }
+            catch (e) {
+                // Log error to ~/.plumb/errors.log for debugging
+                const errorEntry = {
+                    timestamp: new Date().toISOString(),
+                    type: 'ingest_error',
+                    message: e instanceof Error ? e.message : String(e),
+                    context: {
+                        sessionId: exchange.sessionId,
+                        userId,
+                        source: exchange.source,
+                    },
+                    ...(e instanceof Error && e.stack ? { stack: e.stack } : {}),
+                };
+                appendError(errorEntry);
+                // Also log to console for immediate visibility during development
+                console.debug('[plumb] ingest error:', e);
+            }
+        })();
+    };
+}
+//# sourceMappingURL=post-exchange.js.map

package/dist/hooks/post-exchange.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-exchange.js","sourceRoot":"","sources":["../../src/hooks/post-exchange.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA0BjD;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAiB,EAAE,MAAc;IACtE,OAAO,CAAC,KAA+B,EAAE,GAA2B,EAAQ,EAAE;QAC5E,MAAM,QAAQ,GAAG;YACf,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;YACvB,MAAM;YACN,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS,IAAI,MAAM,CAAC,UAAU,EAAE;YAClE,YAAY,EAAE,GAAG,CAAC,UAAU;YAC5B,WAAW,EAAG,KAAa,CAAC,MAAM,IAAI,EAAE;YACxC,aAAa,EAAE,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC;YAC9C,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,MAAM,EAAE,UAAmB;SAC5B,CAAC;QAEF,iDAAiD;QACjD,CAAC,KAAK,IAAI,EAAE;YACV,IAAI,CAAC;gBACH,MAAM,KAAK,CAAC,MAAM,CAAC;oBACjB,WAAW,EAAE,QAAQ,CAAC,WAAW;oBACjC,aAAa,EAAE,QAAQ,CAAC,aAAa;oBACrC,SAAS,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;oBACvC,MAAM,EAAE,QAAQ,CAAC,MAAM;oBACvB,SAAS,EAAE,QAAQ,CAAC,SAAS;oBAC7B,GAAG,CAAC,QAAQ,CAAC,YAAY,IAAI,EAAE,YAAY,EAAE,QAAQ,CAAC,YAAY,EAAE,CAAC;iBACtE,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,CAAU,EAAE,CAAC;gBACpB,iDAAiD;gBACjD,MAAM,UAAU,GAAG;oBACjB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;oBACnC,IAAI,EAAE,cAAc;oBACpB,OAAO,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;oBACnD,OAAO,EAAE;wBACP,SAAS,EAAE,QAAQ,CAAC,SAAS;wBAC7B,MAAM;wBACN,MAAM,EAAE,QAAQ,CAAC,MAAM;qBACxB;oBACD,GAAG,CAAC,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC7D,CAAC;gBAEF,WAAW,CAAC,UAAU,CAAC,CAAC;gBAExB,kEAAkE;gBAClE,OAAO,CAAC,KAAK,CAAC,uBAAuB,EAAE,CAAC,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;IACP,CAAC,CAAC;AACJ,CAAC"}

package/dist/hooks/pre-response.d.ts

@@ -0,0 +1,31 @@
+import type { LocalStore } from '@getplumb/core';
+import type { NudgeManager } from '../nudge.js';
+type PluginHookBeforePromptBuildEvent = {
+    prompt: string;
+    messages: unknown[];
+};
+type PluginHookBeforePromptBuildResult = {
+    systemPrompt?: string;
+    prependContext?: string;
+};
+type PluginHookAgentContext = {
+    agentId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+    workspaceDir?: string;
+    messageProvider?: string;
+};
+/**
+ * Creates a hook handler that retrieves and injects memory context before each agent response.
+ *
+ * The hook queries the store with the incoming user message, formats the retrieved memories
+ * into a [PLUMB MEMORY] block, and prepends it to the system prompt.
+ *
+ * @param store LocalStore instance for memory retrieval
+ * @param nudgeManager NudgeManager instance for contextual upgrade nudges
+ * @param shadowMode If true, retrieves and logs what would be injected but doesn't actually inject
+ * @returns Hook handler for before_prompt_build event
+ */
+export declare function createPreResponseHook(store: LocalStore | null, nudgeManager: NudgeManager | null, shadowMode?: boolean): (event: PluginHookBeforePromptBuildEvent, ctx: PluginHookAgentContext) => Promise<PluginHookBeforePromptBuildResult | void>;
+export {};
+//# sourceMappingURL=pre-response.d.ts.map

package/dist/hooks/pre-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pre-response.d.ts","sourceRoot":"","sources":["../../src/hooks/pre-response.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,KAAK,gCAAgC,GAAG;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB,CAAC;AAEF,KAAK,iCAAiC,GAAG;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,KAAK,sBAAsB,GAAG;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAIF;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,UAAU,GAAG,IAAI,EACxB,YAAY,EAAE,YAAY,GAAG,IAAI,EACjC,UAAU,UAAQ,IAGhB,OAAO,gCAAgC,EACvC,KAAK,sBAAsB,KAC1B,OAAO,CAAC,iCAAiC,GAAG,IAAI,CAAC,CAgFrD"}

package/dist/hooks/pre-response.js

@@ -0,0 +1,81 @@
+import { buildMemoryContext, formatContextBlock } from '@getplumb/core';
+const INJECTION_TIMEOUT_MS = 800;
+/**
+ * Creates a hook handler that retrieves and injects memory context before each agent response.
+ *
+ * The hook queries the store with the incoming user message, formats the retrieved memories
+ * into a [PLUMB MEMORY] block, and prepends it to the system prompt.
+ *
+ * @param store LocalStore instance for memory retrieval
+ * @param nudgeManager NudgeManager instance for contextual upgrade nudges
+ * @param shadowMode If true, retrieves and logs what would be injected but doesn't actually inject
+ * @returns Hook handler for before_prompt_build event
+ */
+export function createPreResponseHook(store, nudgeManager, shadowMode = false) {
+    return async (event, ctx) => {
+        if (!store) {
+            return;
+        }
+        let formattedContext = '';
+        let nudgeText = null;
+        try {
+            // Race between retrieval and timeout
+            const memoryContext = await Promise.race([
+                buildMemoryContext(event.prompt, store),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), INJECTION_TIMEOUT_MS)),
+            ]);
+            // Format the memory context into a prompt block
+            formattedContext = formatContextBlock(memoryContext);
+        }
+        catch (e) {
+            // Handle timeout silently — never slow down a response
+            if (e instanceof Error && e.message === 'timeout') {
+                console.warn('[plumb] memory retrieval timeout — skipping injection');
+            }
+        }
+        // Check for nudges
+        if (nudgeManager && ctx.sessionId) {
+            try {
+                // Check for 'second_integration' trigger
+                const secondIntegrationNudge = nudgeManager.checkSecondIntegration(store.db, store.userId, ctx.sessionId);
+                if (secondIntegrationNudge) {
+                    nudgeText = secondIntegrationNudge;
+                    // Record the nudge so it won't fire again
+                    nudgeManager.recordNudge(store.db, 'second_integration');
+                }
+            }
+            catch (e) {
+                console.warn('[plumb] nudge check failed:', e);
+            }
+        }
+        // Build the final block
+        let block = '';
+        if (formattedContext && formattedContext.trim()) {
+            block = formattedContext;
+        }
+        if (nudgeText) {
+            if (block) {
+                // Append nudge after memory results
+                block = `${block}\n\n---\n${nudgeText}`;
+            }
+            else {
+                // Nudge is the sole content
+                block = nudgeText;
+            }
+        }
+        // Skip injection if no content
+        if (!block || !block.trim()) {
+            return;
+        }
+        // Wrap in [PLUMB MEMORY] delimiters
+        const finalBlock = `[PLUMB MEMORY]\n${block}\n[/PLUMB MEMORY]`;
+        // In shadow mode, log what would be injected but don't actually inject
+        if (shadowMode) {
+            console.debug('[plumb] shadow mode — would inject:', finalBlock.slice(0, 200));
+            return;
+        }
+        // Return the block to be prepended to the system prompt
+        return { prependContext: finalBlock };
+    };
+}
+//# sourceMappingURL=pre-response.js.map

package/dist/hooks/pre-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pre-response.js","sourceRoot":"","sources":["../../src/hooks/pre-response.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+export { PlumbPluginConfig, DEFAULT_CONFIG } from './config.js';
+export { PlumbMcpClient, MemorySearchResult, MemoryStoreResult, MemoryStatusResult, } from './mcp-client.js';
+export { plugin } from './plugin-module.js';
+export { createPostExchangeHook } from './hooks/post-exchange.js';
+import type { PlumbPluginConfig } from './config.js';
+import { PlumbMcpClient } from './mcp-client.js';
+/**
+ * Main entry point for the Plumb OpenClaw plugin.
+ *
+ * Manages the lifecycle of the MCP client connection to the local
+ * plumb memory server. Pipeline hooks (ingest after exchange, inject
+ * before response) are implemented via plugin-module.ts (T-010) and
+ * will be enhanced in T-011.
+ */
+export declare class PlumbPlugin {
+    readonly config: PlumbPluginConfig;
+    private mcpClient;
+    constructor(config?: Partial<PlumbPluginConfig>);
+    /** Connect to the MCP server. No-op if disabled. */
+    start(): Promise<void>;
+    /** Get the underlying MCP client (null if not started or disabled). */
+    get client(): PlumbMcpClient | null;
+    /** Disconnect and clean up. */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;GAOG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,OAAO,CAAC,SAAS,CAA+B;gBAEpC,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC;IAI/C,oDAAoD;IAC9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,uEAAuE;IACvE,IAAI,MAAM,IAAI,cAAc,GAAG,IAAI,CAElC;IAED,+BAA+B;IACzB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAM5B"}

package/dist/index.js

@@ -0,0 +1,40 @@
+export { DEFAULT_CONFIG } from './config.js';
+export { PlumbMcpClient, } from './mcp-client.js';
+export { plugin } from './plugin-module.js';
+export { createPostExchangeHook } from './hooks/post-exchange.js';
+import { DEFAULT_CONFIG } from './config.js';
+import { PlumbMcpClient } from './mcp-client.js';
+/**
+ * Main entry point for the Plumb OpenClaw plugin.
+ *
+ * Manages the lifecycle of the MCP client connection to the local
+ * plumb memory server. Pipeline hooks (ingest after exchange, inject
+ * before response) are implemented via plugin-module.ts (T-010) and
+ * will be enhanced in T-011.
+ */
+export class PlumbPlugin {
+    config;
+    mcpClient = null;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /** Connect to the MCP server. No-op if disabled. */
+    async start() {
+        if (!this.config.enabled)
+            return;
+        this.mcpClient = new PlumbMcpClient(this.config.mcpServerPath);
+        await this.mcpClient.connect();
+    }
+    /** Get the underlying MCP client (null if not started or disabled). */
+    get client() {
+        return this.mcpClient;
+    }
+    /** Disconnect and clean up. */
+    async stop() {
+        if (this.mcpClient) {
+            await this.mcpClient.close();
+            this.mcpClient = null;
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,cAAc,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EACL,cAAc,GAIf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,OAAO,WAAW;IACb,MAAM,CAAoB;IAC3B,SAAS,GAA0B,IAAI,CAAC;IAEhD,YAAY,MAAmC;QAC7C,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC;IACjD,CAAC;IAED,oDAAoD;IACpD,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO;QACjC,IAAI,CAAC,SAAS,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QAC/D,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;IACjC,CAAC;IAED,uEAAuE;IACvE,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,+BAA+B;IAC/B,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;YAC7B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACxB,CAAC;IACH,CAAC;CACF"}

package/dist/mcp-client.d.ts

@@ -0,0 +1,41 @@
+/** A single search result returned by the MCP server's memory_search tool. */
+export interface MemorySearchResult {
+    readonly fact: string;
+    readonly confidence: number;
+    readonly age_in_days: number;
+    readonly source_session_label?: string;
+    readonly layer: 'facts' | 'raw_log';
+}
+/** Result of a memory_store call. */
+export interface MemoryStoreResult {
+    readonly fact_id: string;
+}
+/** Status shape returned by the MCP server (ISO string for dates). */
+export interface MemoryStatusResult {
+    readonly factCount: number;
+    readonly rawLogCount: number;
+    readonly lastIngestion: string | null;
+    readonly storageBytes: number;
+}
+/**
+ * Thin wrapper around the MCP SDK Client that spawns the plumb MCP server
+ * as a child process via stdio and exposes typed helpers for the memory tools.
+ */
+export declare class PlumbMcpClient {
+    private client;
+    private transport;
+    private _connected;
+    constructor(mcpServerPath: string);
+    /** Spawn the MCP server and complete the handshake. */
+    connect(): Promise<void>;
+    get connected(): boolean;
+    /** Search memory for relevant facts / raw log entries. */
+    search(query: string, limit?: number): Promise<MemorySearchResult[]>;
+    /** Store a new piece of content in the memory layer. */
+    store(content: string, source: string): Promise<MemoryStoreResult>;
+    /** Get memory store statistics. */
+    status(): Promise<MemoryStatusResult>;
+    /** Disconnect from the MCP server and kill the child process. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=mcp-client.d.ts.map

package/dist/mcp-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.d.ts","sourceRoot":"","sources":["../src/mcp-client.ts"],"names":[],"mappings":"AAIA,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC;AAED,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,UAAU,CAAS;gBAEf,aAAa,EAAE,MAAM;IAWjC,uDAAuD;IACjD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,0DAA0D;IACpD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAS1E,wDAAwD;IAClD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IASxE,mCAAmC;IAC7B,MAAM,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAM3C,iEAAiE;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/mcp-client.js

@@ -0,0 +1,64 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+/**
+ * Thin wrapper around the MCP SDK Client that spawns the plumb MCP server
+ * as a child process via stdio and exposes typed helpers for the memory tools.
+ */
+export class PlumbMcpClient {
+    client;
+    transport;
+    _connected = false;
+    constructor(mcpServerPath) {
+        this.client = new Client({ name: 'plumb-openclaw-plugin', version: '0.1.0' });
+        this.transport = new StdioClientTransport({
+            command: mcpServerPath,
+            stderr: 'pipe',
+        });
+    }
+    /** Spawn the MCP server and complete the handshake. */
+    async connect() {
+        await this.client.connect(this.transport);
+        this._connected = true;
+    }
+    get connected() {
+        return this._connected;
+    }
+    /** Search memory for relevant facts / raw log entries. */
+    async search(query, limit) {
+        const args = { query };
+        if (limit !== undefined)
+            args.limit = limit;
+        const result = await this.client.callTool({ name: 'memory_search', arguments: args });
+        const text = extractText(result);
+        return JSON.parse(text);
+    }
+    /** Store a new piece of content in the memory layer. */
+    async store(content, source) {
+        const result = await this.client.callTool({
+            name: 'memory_store',
+            arguments: { content, source },
+        });
+        const text = extractText(result);
+        return JSON.parse(text);
+    }
+    /** Get memory store statistics. */
+    async status() {
+        const result = await this.client.callTool({ name: 'memory_status', arguments: {} });
+        const text = extractText(result);
+        return JSON.parse(text);
+    }
+    /** Disconnect from the MCP server and kill the child process. */
+    async close() {
+        this._connected = false;
+        await this.transport.close();
+    }
+}
+/** Extract the first text content block from an MCP tool result. */
+function extractText(result) {
+    const content = result.content;
+    const block = content.find((c) => c.type === 'text');
+    if (!block?.text)
+        throw new Error('MCP tool returned no text content');
+    return block.text;
+}
+//# sourceMappingURL=mcp-client.js.map

package/dist/mcp-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.js","sourceRoot":"","sources":["../src/mcp-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAyBjF;;;GAGG;AACH,MAAM,OAAO,cAAc;IACjB,MAAM,CAAS;IACf,SAAS,CAAuB;IAChC,UAAU,GAAG,KAAK,CAAC;IAE3B,YAAY,aAAqB;QAC/B,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CACtB,EAAE,IAAI,EAAE,uBAAuB,EAAE,OAAO,EAAE,OAAO,EAAE,CACpD,CAAC;QAEF,IAAI,CAAC,SAAS,GAAG,IAAI,oBAAoB,CAAC;YACxC,OAAO,EAAE,aAAa;YACtB,MAAM,EAAE,MAAM;SACf,CAAC,CAAC;IACL,CAAC;IAED,uDAAuD;IACvD,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IACzB,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,0DAA0D;IAC1D,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,KAAc;QACxC,MAAM,IAAI,GAA4B,EAAE,KAAK,EAAE,CAAC;QAChD,IAAI,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QAE5C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACtF,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAyB,CAAC;IAClD,CAAC;IAED,wDAAwD;IACxD,KAAK,CAAC,KAAK,CAAC,OAAe,EAAE,MAAc;QACzC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;YACxC,IAAI,EAAE,cAAc;YACpB,SAAS,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE;SAC/B,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAsB,CAAC;IAC/C,CAAC;IAED,mCAAmC;IACnC,KAAK,CAAC,MAAM;QACV,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;QACpF,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAuB,CAAC;IAChD,CAAC;IAED,iEAAiE;IACjE,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;QACxB,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IAC/B,CAAC;CACF;AAED,oEAAoE;AACpE,SAAS,WAAW,CAAC,MAA+C;IAClE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAiD,CAAC;IACzE,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;IACrD,IAAI,CAAC,KAAK,EAAE,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvE,OAAO,KAAK,CAAC,IAAI,CAAC;AACpB,CAAC"}

package/dist/nudge.d.ts

@@ -0,0 +1,49 @@
+export type NudgeTriggerType = 'second_integration' | 'mcp_downtime';
+type Database = any;
+/**
+ * Manages one-time contextual upgrade nudges to the user.
+ * Each trigger type fires exactly once per install, tracked in the nudge_log table.
+ */
+export declare class NudgeManager {
+    /** Track which sessions have been seen this runtime to avoid redundant checks */
+    private seenSessions;
+    /** Track MCP downtime start timestamp (in-memory, not persisted) */
+    private mcpDowntimeStart;
+    /** Threshold in milliseconds for MCP downtime trigger (5 minutes) */
+    private readonly MCP_DOWNTIME_THRESHOLD_MS;
+    /**
+     * Check if a nudge should be fired for the given trigger type.
+     * Returns the nudge text if it should fire, null otherwise.
+     */
+    checkTriggers(db: Database, triggerType: NudgeTriggerType): string | null;
+    /**
+     * Record that a nudge has been fired for the given trigger type.
+     * This ensures the trigger will never fire again.
+     */
+    recordNudge(db: Database, triggerType: NudgeTriggerType): void;
+    /**
+     * Get the nudge text for a given trigger type.
+     * Tone: factual, helpful, not pushy. Surfaced through the agent's voice.
+     */
+    getNudgeText(triggerType: NudgeTriggerType): string;
+    /**
+     * Check if the 'second_integration' trigger should fire.
+     * Counts distinct session_ids in raw_log for this userId.
+     * If >1 unique session has ingested data, that's a second integration.
+     *
+     * Only checks once per session to avoid redundant queries.
+     */
+    checkSecondIntegration(db: Database, userId: string, currentSessionId: string): string | null;
+    /**
+     * Trigger the MCP downtime nudge.
+     * Called when MCP client connection fails.
+     * Tracks downtime duration in-memory; fires if >5 minutes.
+     */
+    triggerMcpDowntime(db: Database): string | null;
+    /**
+     * Reset MCP downtime tracking (call when connection is restored).
+     */
+    resetMcpDowntime(): void;
+}
+export {};
+//# sourceMappingURL=nudge.d.ts.map

package/dist/nudge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nudge.d.ts","sourceRoot":"","sources":["../src/nudge.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,GAAG,cAAc,CAAC;AAIrE,KAAK,QAAQ,GAAG,GAAG,CAAC;AAEpB;;;GAGG;AACH,qBAAa,YAAY;IACvB,iFAAiF;IACjF,OAAO,CAAC,YAAY,CAA0B;IAE9C,oEAAoE;IACpE,OAAO,CAAC,gBAAgB,CAAuB;IAE/C,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAiB;IAE3D;;;OAGG;IACH,aAAa,CAAC,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI;IAezE;;;OAGG;IACH,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,GAAG,IAAI;IAO9D;;;OAGG;IACH,YAAY,CAAC,WAAW,EAAE,gBAAgB,GAAG,MAAM;IAWnD;;;;;;OAMG;IACH,sBAAsB,CACpB,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,GACvB,MAAM,GAAG,IAAI;IAsBhB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI;IAmB/C;;OAEG;IACH,gBAAgB,IAAI,IAAI;CAGzB"}

package/dist/nudge.js

@@ -0,0 +1,97 @@
+/**
+ * Manages one-time contextual upgrade nudges to the user.
+ * Each trigger type fires exactly once per install, tracked in the nudge_log table.
+ */
+export class NudgeManager {
+    /** Track which sessions have been seen this runtime to avoid redundant checks */
+    seenSessions = new Set();
+    /** Track MCP downtime start timestamp (in-memory, not persisted) */
+    mcpDowntimeStart = null;
+    /** Threshold in milliseconds for MCP downtime trigger (5 minutes) */
+    MCP_DOWNTIME_THRESHOLD_MS = 5 * 60 * 1000;
+    /**
+     * Check if a nudge should be fired for the given trigger type.
+     * Returns the nudge text if it should fire, null otherwise.
+     */
+    checkTriggers(db, triggerType) {
+        // Check if this trigger has already fired (check nudge_log table)
+        const existing = db.prepare(`SELECT id FROM nudge_log WHERE trigger_type = ? LIMIT 1`).get(triggerType);
+        if (existing) {
+            // This trigger has already fired — never fire again
+            return null;
+        }
+        // Trigger has not fired yet — return the nudge text
+        return this.getNudgeText(triggerType);
+    }
+    /**
+     * Record that a nudge has been fired for the given trigger type.
+     * This ensures the trigger will never fire again.
+     */
+    recordNudge(db, triggerType) {
+        const id = crypto.randomUUID();
+        db.prepare(`INSERT INTO nudge_log (id, trigger_type, fired_at) VALUES (?, ?, ?)`).run(id, triggerType, new Date().toISOString());
+    }
+    /**
+     * Get the nudge text for a given trigger type.
+     * Tone: factual, helpful, not pushy. Surfaced through the agent's voice.
+     */
+    getNudgeText(triggerType) {
+        switch (triggerType) {
+            case 'second_integration':
+                return "You've connected multiple integrations - if you want memory to sync across all of them automatically, Plumb hosted handles that: https://getplumb.dev/upgrade";
+            case 'mcp_downtime':
+                return 'Your local MCP server has been unreachable for a while - Plumb hosted runs in the cloud and stays available 24/7: https://getplumb.dev/upgrade';
+            default:
+                return '';
+        }
+    }
+    /**
+     * Check if the 'second_integration' trigger should fire.
+     * Counts distinct session_ids in raw_log for this userId.
+     * If >1 unique session has ingested data, that's a second integration.
+     *
+     * Only checks once per session to avoid redundant queries.
+     */
+    checkSecondIntegration(db, userId, currentSessionId) {
+        // Only check once per session
+        if (this.seenSessions.has(currentSessionId)) {
+            return null;
+        }
+        this.seenSessions.add(currentSessionId);
+        // Count distinct session_ids in raw_log for this user
+        const result = db.prepare(`SELECT COUNT(DISTINCT session_id) as count FROM raw_log WHERE user_id = ?`).get(userId);
+        const sessionCount = result?.count ?? 0;
+        if (sessionCount > 1) {
+            // Multiple sessions detected — check if we should fire the nudge
+            return this.checkTriggers(db, 'second_integration');
+        }
+        return null;
+    }
+    /**
+     * Trigger the MCP downtime nudge.
+     * Called when MCP client connection fails.
+     * Tracks downtime duration in-memory; fires if >5 minutes.
+     */
+    triggerMcpDowntime(db) {
+        const now = Date.now();
+        // Start tracking downtime if not already started
+        if (this.mcpDowntimeStart === null) {
+            this.mcpDowntimeStart = now;
+            return null;
+        }
+        // Check if downtime exceeds threshold
+        const downtimeDuration = now - this.mcpDowntimeStart;
+        if (downtimeDuration >= this.MCP_DOWNTIME_THRESHOLD_MS) {
+            // Threshold exceeded — check if we should fire the nudge
+            return this.checkTriggers(db, 'mcp_downtime');
+        }
+        return null;
+    }
+    /**
+     * Reset MCP downtime tracking (call when connection is restored).
+     */
+    resetMcpDowntime() {
+        this.mcpDowntimeStart = null;
+    }
+}
+//# sourceMappingURL=nudge.js.map

package/dist/nudge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nudge.js","sourceRoot":"","sources":["../src/nudge.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,MAAM,OAAO,YAAY;IACvB,iFAAiF;IACzE,YAAY,GAAgB,IAAI,GAAG,EAAE,CAAC;IAE9C,oEAAoE;IAC5D,gBAAgB,GAAkB,IAAI,CAAC;IAE/C,qEAAqE;IACpD,yBAAyB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;IAE3D;;;OAGG;IACH,aAAa,CAAC,EAAY,EAAE,WAA6B;QACvD,kEAAkE;QAClE,MAAM,QAAQ,GAAG,EAAE,CAAC,OAAO,CACzB,yDAAyD,CAC1D,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAEnB,IAAI,QAAQ,EAAE,CAAC;YACb,oDAAoD;YACpD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,oDAAoD;QACpD,OAAO,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IACxC,CAAC;IAED;;;OAGG;IACH,WAAW,CAAC,EAAY,EAAE,WAA6B;QACrD,MAAM,EAAE,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;QAC/B,EAAE,CAAC,OAAO,CACR,qEAAqE,CACtE,CAAC,GAAG,CAAC,EAAE,EAAE,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IACnD,CAAC;IAED;;;OAGG;IACH,YAAY,CAAC,WAA6B;QACxC,QAAQ,WAAW,EAAE,CAAC;YACpB,KAAK,oBAAoB;gBACvB,OAAO,+JAA+J,CAAC;YACzK,KAAK,cAAc;gBACjB,OAAO,gJAAgJ,CAAC;YAC1J;gBACE,OAAO,EAAE,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,sBAAsB,CACpB,EAAY,EACZ,MAAc,EACd,gBAAwB;QAExB,8BAA8B;QAC9B,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,gBAAgB,CAAC,EAAE,CAAC;YAC5C,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QAExC,sDAAsD;QACtD,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CACvB,2EAA2E,CAC5E,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAEd,MAAM,YAAY,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC,CAAC;QAExC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACrB,iEAAiE;YACjE,OAAO,IAAI,CAAC,aAAa,CAAC,EAAE,EAAE,oBAAoB,CAAC,CAAC;QACtD,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,kBAAkB,CAAC,EAAY;QAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,iDAAiD;QACjD,IAAI,IAAI,CAAC,gBAAgB,KAAK,IAAI,EAAE,CAAC;YACnC,IAAI,CAAC,gBAAgB,GAAG,GAAG,CAAC;YAC5B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,sCAAsC;QACtC,MAAM,gBAAgB,GAAG,GAAG,GAAG,IAAI,CAAC,gBAAgB,CAAC;QACrD,IAAI,gBAAgB,IAAI,IAAI,CAAC,yBAAyB,EAAE,CAAC;YACvD,yDAAyD;YACzD,OAAO,IAAI,CAAC,aAAa,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC;QAChD,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,gBAAgB;QACd,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAC/B,CAAC;CACF"}

package/dist/plugin-module.d.ts

@@ -0,0 +1,37 @@
+type PluginLogger = {
+    debug?: (message: string) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+};
+type PluginHookHandlerMap = {
+    llm_output: (event: any, ctx: any) => Promise<void> | void;
+    session_end: (event: any, ctx: any) => Promise<void> | void;
+    before_prompt_build: (event: any, ctx: any) => Promise<any> | void;
+    [key: string]: any;
+};
+type OpenClawPluginApi = {
+    id: string;
+    name: string;
+    pluginConfig?: Record<string, unknown>;
+    logger: PluginLogger;
+    on: <K extends keyof PluginHookHandlerMap>(hookName: K, handler: PluginHookHandlerMap[K], opts?: {
+        priority?: number;
+    }) => void;
+};
+type OpenClawPluginDefinition = {
+    id?: string;
+    name?: string;
+    version?: string;
+    kind?: 'memory';
+    activate?: (api: OpenClawPluginApi) => void | Promise<void>;
+};
+/**
+ * Plumb OpenClaw plugin entry point.
+ *
+ * Automatically ingests every LLM exchange into the local memory store via the
+ * llm_output hook. Runs fire-and-forget so it never blocks the agent pipeline.
+ */
+export declare const plugin: OpenClawPluginDefinition;
+export {};
+//# sourceMappingURL=plugin-module.d.ts.map

package/dist/plugin-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-module.d.ts","sourceRoot":"","sources":["../src/plugin-module.ts"],"names":[],"mappings":"AAQA,KAAK,YAAY,GAAG;IAClB,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC,CAAC;AAEF,KAAK,oBAAoB,GAAG;IAC1B,UAAU,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3D,WAAW,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC5D,mBAAmB,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IACnE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB,CAAC;AAEF,KAAK,iBAAiB,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,MAAM,EAAE,YAAY,CAAC;IACrB,EAAE,EAAE,CAAC,CAAC,SAAS,MAAM,oBAAoB,EACvC,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,EAChC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,KACzB,IAAI,CAAC;CACX,CAAC;AAEF,KAAK,wBAAwB,GAAG;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D,CAAC;AAIF;;;;;GAKG;AACH,eAAO,MAAM,MAAM,EAAE,wBAoCpB,CAAC"}

package/dist/plugin-module.js

@@ -0,0 +1,43 @@
+import { LocalStore } from '@getplumb/core';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createPostExchangeHook } from './hooks/post-exchange.js';
+import { createPreResponseHook } from './hooks/pre-response.js';
+import { NudgeManager } from './nudge.js';
+const DEFAULT_DB_PATH = join(homedir(), '.plumb', 'memory.db');
+/**
+ * Plumb OpenClaw plugin entry point.
+ *
+ * Automatically ingests every LLM exchange into the local memory store via the
+ * llm_output hook. Runs fire-and-forget so it never blocks the agent pipeline.
+ */
+export const plugin = {
+    id: 'plumb',
+    name: 'Plumb Memory',
+    version: '0.1.0',
+    kind: 'memory',
+    async activate(api) {
+        const dbPath = api.pluginConfig?.dbPath ?? DEFAULT_DB_PATH;
+        const userId = api.pluginConfig?.userId ?? 'default';
+        const shadowMode = api.pluginConfig?.shadowMode ?? false;
+        api.logger.info(`[plumb] Activating with dbPath=${dbPath}, userId=${userId}, shadowMode=${shadowMode}`);
+        const store = new LocalStore({ dbPath, userId });
+        const nudgeManager = new NudgeManager();
+        // Register the llm_output hook for auto-ingest
+        api.on('llm_output', createPostExchangeHook(store, userId));
+        // Register the before_prompt_build hook for memory injection
+        api.on('before_prompt_build', createPreResponseHook(store, nudgeManager, shadowMode));
+        // Clean up on session end
+        api.on('session_end', async () => {
+            try {
+                store.close();
+                api.logger.debug?.('[plumb] Store closed on session_end');
+            }
+            catch (e) {
+                api.logger.debug?.(`[plumb] Error closing store: ${e}`);
+            }
+        });
+        api.logger.info('[plumb] Plugin activated');
+    },
+};
+//# sourceMappingURL=plugin-module.js.map

package/dist/plugin-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-module.js","sourceRoot":"","sources":["../src/plugin-module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAqC1C,MAAM,eAAe,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAA6B;IAC9C,EAAE,EAAE,OAAO;IACX,IAAI,EAAE,cAAc;IACpB,OAAO,EAAE,OAAO;IAChB,IAAI,EAAE,QAAQ;IAEd,KAAK,CAAC,QAAQ,CAAC,GAAsB;QACnC,MAAM,MAAM,GAAI,GAAG,CAAC,YAAY,EAAE,MAA6B,IAAI,eAAe,CAAC;QACnF,MAAM,MAAM,GAAI,GAAG,CAAC,YAAY,EAAE,MAA6B,IAAI,SAAS,CAAC;QAC7E,MAAM,UAAU,GAAI,GAAG,CAAC,YAAY,EAAE,UAAkC,IAAI,KAAK,CAAC;QAElF,GAAG,CAAC,MAAM,CAAC,IAAI,CACb,kCAAkC,MAAM,YAAY,MAAM,gBAAgB,UAAU,EAAE,CACvF,CAAC;QAEF,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QACjD,MAAM,YAAY,GAAG,IAAI,YAAY,EAAE,CAAC;QAExC,+CAA+C;QAC/C,GAAG,CAAC,EAAE,CAAC,YAAY,EAAE,sBAAsB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;QAE5D,6DAA6D;QAC7D,GAAG,CAAC,EAAE,CAAC,qBAAqB,EAAE,qBAAqB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,CAAC,CAAC,CAAC;QAEtF,0BAA0B;QAC1B,GAAG,CAAC,EAAE,CAAC,aAAa,EAAE,KAAK,IAAI,EAAE;YAC/B,IAAI,CAAC;gBACH,KAAK,CAAC,KAAK,EAAE,CAAC;gBACd,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,qCAAqC,CAAC,CAAC;YAC5D,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,gCAAgC,CAAC,EAAE,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IAC9C,CAAC;CACF,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@getplumb/openclaw-plugin",
+  "version": "0.1.0",
+  "description": "Plumb OpenClaw plugin — auto-ingest and memory injection for OpenClaw",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@getplumb/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "better-sqlite3": "^12.6.2",
+    "openclaw": "^2026.3.2",
+    "typescript": "^5.4.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "echo \"No lint yet\" && exit 0",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}