@memorystack/clawdbot-memorystack 1.0.0

package/README.md

@@ -0,0 +1,102 @@
+# MemoryStack Plugin for Clawdbot
+
+Long-term memory for Clawdbot. Automatically remembers conversations, recalls relevant context, and builds a persistent memory layer — all powered by [MemoryStack](https://memorystack.app) cloud.
+
+## Install
+
+```bash
+cd extensions/memorystack
+npm install
+```
+
+Or install from npm (once published):
+
+```bash
+clawdbot plugins install @memorystack/clawdbot-memorystack
+```
+
+Restart Clawdbot after installing.
+
+## Configuration
+
+The only required value is your MemoryStack API key. Get one at [memorystack.app/dashboard/api-keys](https://memorystack.app/dashboard/api-keys).
+
+Set it as an environment variable:
+
+```bash
+export MEMORYSTACK_API_KEY="ms_proj_..."
+```
+
+Or configure it directly in `clawdbot.json`:
+
+```json
+{
+  "plugins": {
+    "slots": {
+      "memory": "clawdbot-memorystack"
+    },
+    "entries": {
+      "clawdbot-memorystack": {
+        "enabled": true,
+        "config": {
+          "apiKey": "${MEMORYSTACK_API_KEY}",
+          "autoRecall": true,
+          "autoCapture": true,
+          "maxRecallResults": 5
+        }
+      }
+    }
+  }
+}
+```
+
+### Advanced options
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `apiKey` | `string` | - | Your MemoryStack API key (required) |
+| `baseUrl` | `string` | `https://memorystack.app` | API endpoint URL |
+| `autoRecall` | `boolean` | `true` | Inject relevant memories before every AI turn |
+| `autoCapture` | `boolean` | `true` | Automatically store conversation content after every turn |
+| `maxRecallResults` | `number` | `5` | Max memories injected into context per turn (1-20) |
+| `debug` | `boolean` | `false` | Verbose debug logs for API calls and responses |
+
+## How it works
+
+Once installed, the plugin works automatically with zero interaction:
+
+- **Auto-Recall** — Before every AI turn, the plugin queries MemoryStack for relevant memories and injects them as context using semantic search.
+- **Auto-Capture** — After every AI turn, the last user/assistant exchange is sent to MemoryStack for extraction and long-term storage.
+
+Everything runs in the cloud. MemoryStack handles importance scoring, contradiction detection, consolidation, and reflection on its end.
+
+## AI Tools
+
+The AI can use these tools autonomously during conversations:
+
+| Tool | Description |
+|------|-------------|
+| `memorystack_search` | Search memories by query with semantic search |
+| `memorystack_add` | Save information to long-term memory |
+| `memorystack_stats` | View memory usage statistics |
+
+## Features
+
+- **Hybrid Search** - Vector similarity + text search with RRF ranking
+- **Importance Scoring** - Automatic ranking of what matters
+- **Contradiction Detection** - Resolves conflicts and updates beliefs
+- **Memory Consolidation** - Deduplication and merging (runs server-side)
+- **Temporal Decay** - Simulates natural forgetting
+- **Reflection** - Discovers patterns and generates insights
+
+## Links
+
+- 🌐 **Website**: https://memorystack.app
+- 📚 **Documentation**: https://memorystack.app/docs
+- 🚀 **Quick Start**: https://memorystack.app/docs/quickstart
+- 🔑 **Get API Key**: https://memorystack.app/dashboard/api-keys
+- 💰 **Pricing**: https://memorystack.app/pricing
+
+## License
+
+MIT

package/clawdbot.plugin.json

@@ -0,0 +1,66 @@
+{
+    "id": "clawdbot-memorystack",
+    "kind": "memory",
+    "uiHints": {
+        "apiKey": {
+            "label": "MemoryStack API Key",
+            "sensitive": true,
+            "placeholder": "ms_proj_...",
+            "help": "Your API key from memorystack.app/dashboard/api-keys (or use ${MEMORYSTACK_API_KEY})"
+        },
+        "baseUrl": {
+            "label": "API Base URL",
+            "placeholder": "https://memorystack.app",
+            "help": "MemoryStack API endpoint (default: https://memorystack.app)",
+            "advanced": true
+        },
+        "autoRecall": {
+            "label": "Auto-Recall",
+            "help": "Inject relevant memories before every AI turn"
+        },
+        "autoCapture": {
+            "label": "Auto-Capture",
+            "help": "Automatically store important information from conversations"
+        },
+        "maxRecallResults": {
+            "label": "Max Recall Results",
+            "placeholder": "5",
+            "help": "Maximum memories injected into context per turn",
+            "advanced": true
+        },
+        "debug": {
+            "label": "Debug Logging",
+            "help": "Enable verbose debug logs for API calls and responses",
+            "advanced": true
+        }
+    },
+    "configSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+            "apiKey": {
+                "type": "string"
+            },
+            "baseUrl": {
+                "type": "string"
+            },
+            "autoRecall": {
+                "type": "boolean"
+            },
+            "autoCapture": {
+                "type": "boolean"
+            },
+            "maxRecallResults": {
+                "type": "number",
+                "minimum": 1,
+                "maximum": 20
+            },
+            "debug": {
+                "type": "boolean"
+            }
+        },
+        "required": [
+            "apiKey"
+        ]
+    }
+}

package/config.ts

@@ -0,0 +1,32 @@
+import { Type } from "@sinclair/typebox";
+
+export const memorystackConfigSchema = Type.Object({
+    apiKey: Type.String(),
+    baseUrl: Type.Optional(Type.String()),
+    autoRecall: Type.Optional(Type.Boolean()),
+    autoCapture: Type.Optional(Type.Boolean()),
+    maxRecallResults: Type.Optional(Type.Number({ minimum: 1, maximum: 20 })),
+    debug: Type.Optional(Type.Boolean()),
+});
+
+export type MemorystackConfig = {
+    apiKey: string;
+    baseUrl: string;
+    autoRecall: boolean;
+    autoCapture: boolean;
+    maxRecallResults: number;
+    debug: boolean;
+};
+
+export function parseConfig(rawConfig: unknown): MemorystackConfig {
+    const cfg = rawConfig as Partial<MemorystackConfig>;
+
+    return {
+        apiKey: cfg.apiKey || process.env.MEMORYSTACK_API_KEY || "",
+        baseUrl: cfg.baseUrl || "https://memorystack.app",
+        autoRecall: cfg.autoRecall ?? true,
+        autoCapture: cfg.autoCapture ?? true,
+        maxRecallResults: cfg.maxRecallResults ?? 5,
+        debug: cfg.debug ?? false,
+    };
+}

package/hooks/capture.ts

@@ -0,0 +1,96 @@
+import { MemoryStackClient } from "@memorystack/sdk";
+import type { MemorystackConfig } from "../config.ts";
+import { log } from "../logger.ts";
+
+function getLastTurn(messages: unknown[]): unknown[] {
+    let lastUserIdx = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (
+            msg &&
+            typeof msg === "object" &&
+            (msg as Record<string, unknown>).role === "user"
+        ) {
+            lastUserIdx = i;
+            break;
+        }
+    }
+    return lastUserIdx >= 0 ? messages.slice(lastUserIdx) : messages;
+}
+
+export function buildCaptureHandler(cfg: MemorystackConfig) {
+    return async (event: Record<string, unknown>) => {
+        if (
+            !event.success ||
+            !Array.isArray(event.messages) ||
+            event.messages.length === 0
+        )
+            return;
+
+        const lastTurn = getLastTurn(event.messages);
+
+        const texts: string[] = [];
+        for (const msg of lastTurn) {
+            if (!msg || typeof msg !== "object") continue;
+            const msgObj = msg as Record<string, unknown>;
+            const role = msgObj.role;
+            if (role !== "user" && role !== "assistant") continue;
+
+            const content = msgObj.content;
+
+            const parts: string[] = [];
+
+            if (typeof content === "string") {
+                parts.push(content);
+            } else if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (!block || typeof block !== "object") continue;
+                    const b = block as Record<string, unknown>;
+                    if (b.type === "text" && typeof b.text === "string") {
+                        parts.push(b.text);
+                    }
+                }
+            }
+
+            if (parts.length > 0) {
+                texts.push(`[role: ${role}]\n${parts.join("\n")}\n[${role}:end]`);
+            }
+        }
+
+        // Filter out injected context and short messages
+        const captured = texts
+            .map((t) =>
+                t
+                    .replace(
+                        /<memorystack-context>[\s\S]*?<\/memorystack-context>\s*/g,
+                        "",
+                    )
+                    .trim(),
+            )
+            .filter((t) => t.length >= 10 && t.length <= 500);
+
+        if (captured.length === 0) return;
+
+        const content = captured.join("\n\n");
+
+        log.debug(
+            `capturing ${captured.length} texts (${content.length} chars)`,
+        );
+
+        try {
+            const client = new MemoryStackClient({
+                apiKey: cfg.apiKey,
+                baseUrl: cfg.baseUrl,
+                enableLogging: cfg.debug,
+            });
+
+            await client.add(content, {
+                metadata: { source: "clawdbot_auto_capture", timestamp: new Date().toISOString() },
+            });
+
+            log.debug(`captured ${captured.length} messages successfully`);
+        } catch (err) {
+            log.error("capture failed", err);
+        }
+    };
+}

package/hooks/recall.ts

@@ -0,0 +1,104 @@
+import { MemoryStackClient } from "@memorystack/sdk";
+import type { MemorystackConfig } from "../config.ts";
+import { log } from "../logger.ts";
+
+const MAX_CONTEXT_CHARS = 2000;
+
+interface MemoryResult {
+    content: string;
+    memory_type?: string;
+    confidence?: number;
+    created_at?: string;
+}
+
+function formatGroupedMemories(memories: MemoryResult[]): string {
+    // Group by memory type
+    const groups: Record<string, MemoryResult[]> = {};
+    const ungrouped: MemoryResult[] = [];
+
+    for (const m of memories) {
+        const type = m.memory_type || "other";
+        if (type === "other") {
+            ungrouped.push(m);
+        } else {
+            groups[type] = groups[type] || [];
+            groups[type].push(m);
+        }
+    }
+
+    const sections: string[] = [];
+    const typeLabels: Record<string, string> = {
+        fact: "📋 Facts",
+        preference: "💜 Preferences",
+        episode: "📅 Recent Context",
+        procedure: "🔧 Procedures",
+        belief: "💭 Beliefs",
+    };
+
+    // Format grouped memories
+    for (const [type, items] of Object.entries(groups)) {
+        const label = typeLabels[type] || type.charAt(0).toUpperCase() + type.slice(1);
+        const lines = items.map((m) => {
+            const conf = m.confidence && m.confidence >= 0.8 ? ` (${Math.round(m.confidence * 100)}%)` : "";
+            return `- ${m.content}${conf}`;
+        });
+        sections.push(`## ${label}\n${lines.join("\n")}`);
+    }
+
+    // Add ungrouped at end
+    if (ungrouped.length > 0) {
+        const lines = ungrouped.map((m) => `- ${m.content}`);
+        sections.push(`## Other\n${lines.join("\n")}`);
+    }
+
+    return sections.join("\n\n");
+}
+
+export function buildRecallHandler(cfg: MemorystackConfig) {
+    return async (event: Record<string, unknown>) => {
+        const prompt = event.prompt as string | undefined;
+        if (!prompt || prompt.length < 10) return;
+
+        log.debug(`recalling for prompt (${prompt.length} chars)`);
+
+        try {
+            const client = new MemoryStackClient({
+                apiKey: cfg.apiKey,
+                baseUrl: cfg.baseUrl,
+                enableLogging: cfg.debug,
+            });
+
+            const results = await client.search(prompt, {
+                limit: cfg.maxRecallResults,
+            });
+
+            if (results.count === 0) {
+                log.debug("no memories to inject");
+                return;
+            }
+
+            const formattedMemories = formatGroupedMemories(results.results);
+
+            // Truncate if too long
+            const truncated = formattedMemories.length > MAX_CONTEXT_CHARS
+                ? formattedMemories.slice(0, MAX_CONTEXT_CHARS) + "\n...(truncated)"
+                : formattedMemories;
+
+            const context = `<memorystack-context>
+The following is recalled context about the user. Reference it only when relevant.
+
+${truncated}
+
+Use these memories naturally when relevant — including indirect connections — but don't force them into every response or make assumptions beyond what's stated.
+</memorystack-context>`;
+
+            log.debug(`injecting ${results.count} memories (${context.length} chars)`);
+
+            return { prependContext: context };
+        } catch (err) {
+            log.error("recall failed", err);
+            return;
+        }
+    };
+}
+

package/index.ts

@@ -0,0 +1,54 @@
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { parseConfig, memorystackConfigSchema } from "./config.ts";
+import { initLogger } from "./logger.ts";
+import { registerSearchTool } from "./tools/search.ts";
+import { registerAddTool } from "./tools/add.ts";
+import { registerStatsTool } from "./tools/stats.ts";
+import { buildRecallHandler } from "./hooks/recall.ts";
+import { buildCaptureHandler } from "./hooks/capture.ts";
+
+export default {
+    id: "clawdbot-memorystack",
+    name: "MemoryStack",
+    description: "Clawdbot powered by MemoryStack plugin",
+    kind: "memory" as const,
+    configSchema: memorystackConfigSchema,
+
+    register(api: ClawdbotPluginApi) {
+        const cfg = parseConfig(api.pluginConfig);
+
+        if (!cfg.apiKey) {
+            api.logger.error("memorystack: API key is required. Set MEMORYSTACK_API_KEY or configure in plugin config.");
+            return;
+        }
+
+        initLogger(api.logger, cfg.debug);
+
+        // Register tools
+        registerSearchTool(api, cfg);
+        registerAddTool(api, cfg);
+        registerStatsTool(api, cfg);
+
+        // Auto-recall hook
+        if (cfg.autoRecall) {
+            const recallHandler = buildRecallHandler(cfg);
+            api.on("before_agent_start", recallHandler);
+        }
+
+        // Auto-capture hook
+        if (cfg.autoCapture) {
+            api.on("agent_end", buildCaptureHandler(cfg));
+        }
+
+        // Register service
+        api.registerService({
+            id: "clawdbot-memorystack",
+            start: () => {
+                api.logger.info("memorystack: connected");
+            },
+            stop: () => {
+                api.logger.info("memorystack: stopped");
+            },
+        });
+    },
+};

package/logger.ts

@@ -0,0 +1,36 @@
+import type { Logger } from "clawdbot/plugin-sdk";
+
+let logger: Logger;
+let debugEnabled = false;
+
+export function initLogger(l: Logger, debug: boolean): void {
+    logger = l;
+    debugEnabled = debug;
+}
+
+export const log = {
+    info: (msg: string, ...args: unknown[]) => {
+        logger?.info(`memorystack: ${msg}`, ...args);
+    },
+    warn: (msg: string, ...args: unknown[]) => {
+        logger?.warn(`memorystack: ${msg}`, ...args);
+    },
+    error: (msg: string, err?: unknown) => {
+        logger?.error(`memorystack: ${msg}`, err);
+    },
+    debug: (msg: string, data?: unknown) => {
+        if (debugEnabled) {
+            logger?.debug?.(`memorystack: ${msg}`, data);
+        }
+    },
+    debugRequest: (method: string, params: unknown) => {
+        if (debugEnabled) {
+            logger?.debug?.(`memorystack → ${method}`, params);
+        }
+    },
+    debugResponse: (method: string, result: unknown) => {
+        if (debugEnabled) {
+            logger?.debug?.(`memorystack ← ${method}`, result);
+        }
+    },
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "@memorystack/clawdbot-memorystack",
+    "version": "1.0.0",
+    "type": "module",
+    "description": "Clawdbot MemoryStack memory plugin - long-term memory for your AI assistant",
+    "license": "MIT",
+    "author": "MemoryStack <support@memorystack.app>",
+    "homepage": "https://memorystack.app",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/memorystack-labs/memorystack"
+    },
+    "keywords": [
+        "clawdbot",
+        "moltbot",
+        "memory",
+        "memorystack",
+        "ai",
+        "long-term-memory"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "@memorystack/sdk": "^1.0.3",
+        "@sinclair/typebox": "0.34.47"
+    },
+    "peerDependencies": {
+        "clawdbot": ">=2026.1.24"
+    },
+    "clawdbot": {
+        "extensions": [
+            "./index.ts"
+        ]
+    },
+    "devDependencies": {
+        "typescript": "^5.9.3"
+    }
+}

package/tools/add.ts

@@ -0,0 +1,58 @@
+import { Type } from "@sinclair/typebox";
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { MemoryStackClient } from "@memorystack/sdk";
+import type { MemorystackConfig } from "../config.ts";
+import { log } from "../logger.ts";
+
+export function registerAddTool(
+    api: ClawdbotPluginApi,
+    cfg: MemorystackConfig,
+): void {
+    api.registerTool(
+        {
+            name: "memorystack_add",
+            label: "Memory Add",
+            description: "Save important information to long-term memory with automatic importance scoring.",
+            parameters: Type.Object({
+                text: Type.String({ description: "Information to remember" }),
+                userId: Type.Optional(Type.String({ description: "User ID (for B2B apps)" })),
+            }),
+            async execute(
+                _toolCallId: string,
+                params: { text: string; userId?: string },
+            ) {
+                log.debugRequest("add", { textLength: params.text.length, userId: params.userId });
+
+                const client = new MemoryStackClient({
+                    apiKey: cfg.apiKey,
+                    baseUrl: cfg.baseUrl,
+                    enableLogging: cfg.debug,
+                });
+
+                const result = await client.add(params.text, {
+                    userId: params.userId,
+                    metadata: { source: "clawdbot_tool" },
+                });
+
+                log.debugResponse("add", {
+                    memories_created: result.memories_created,
+                    memory_ids: result.memory_ids,
+                });
+
+                const preview =
+                    params.text.length > 80 ? `${params.text.slice(0, 80)}…` : params.text;
+
+                return {
+                    content: [
+                        {
+                            type: "text" as const,
+                            text: `Stored: "${preview}"\nCreated ${result.memories_created} memory (IDs: ${result.memory_ids.join(", ")})`,
+                        },
+                    ],
+                    details: result,
+                };
+            },
+        },
+        { name: "memorystack_add" },
+    );
+}

package/tools/search.ts

@@ -0,0 +1,107 @@
+import { Type } from "@sinclair/typebox";
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { MemoryStackClient } from "@memorystack/sdk";
+import type { MemorystackConfig } from "../config.ts";
+import { log } from "../logger.ts";
+
+export function registerSearchTool(
+    api: ClawdbotPluginApi,
+    cfg: MemorystackConfig,
+): void {
+    api.registerTool(
+        {
+            name: "memorystack_search",
+            label: "Memory Search",
+            description:
+                "Search through long-term memories for relevant information using semantic search. Supports filtering by memory type, confidence, and recency.",
+            parameters: Type.Object({
+                query: Type.String({ description: "Search query" }),
+                limit: Type.Optional(
+                    Type.Number({ description: "Max results (default: 5)" }),
+                ),
+                memory_type: Type.Optional(
+                    Type.String({
+                        description:
+                            "Filter by type: fact, preference, episode, procedure, belief",
+                    }),
+                ),
+                min_confidence: Type.Optional(
+                    Type.Number({
+                        description: "Minimum confidence score 0-1 (default: 0)",
+                    }),
+                ),
+                days_ago: Type.Optional(
+                    Type.Number({
+                        description: "Only memories from last N days",
+                    }),
+                ),
+            }),
+            async execute(
+                _toolCallId: string,
+                params: {
+                    query: string;
+                    limit?: number;
+                    memory_type?: string;
+                    min_confidence?: number;
+                    days_ago?: number;
+                },
+            ) {
+                const limit = params.limit ?? 5;
+                log.debugRequest("search", { query: params.query, limit, ...params });
+
+                const client = new MemoryStackClient({
+                    apiKey: cfg.apiKey,
+                    baseUrl: cfg.baseUrl,
+                    enableLogging: cfg.debug,
+                });
+
+                const searchOpts: Record<string, unknown> = { limit };
+                if (params.memory_type) {
+                    searchOpts.memory_type = params.memory_type;
+                }
+
+                const results = await client.search(params.query, searchOpts);
+
+                if (results.count === 0) {
+                    return {
+                        content: [
+                            { type: "text" as const, text: "No relevant memories found." },
+                        ],
+                    };
+                }
+
+                const text = results.results
+                    .map((r, i) => {
+                        const type = r.memory_type ? ` [${r.memory_type}]` : "";
+                        const conf = r.confidence
+                            ? ` (${(r.confidence * 100).toFixed(0)}%)`
+                            : "";
+                        return `${i + 1}. ${r.content}${type}${conf}`;
+                    })
+                    .join("\n");
+
+                log.debugResponse("search", { count: results.count });
+
+                return {
+                    content: [
+                        {
+                            type: "text" as const,
+                            text: `Found ${results.count} memories:\n\n${text}`,
+                        },
+                    ],
+                    details: {
+                        count: results.count,
+                        mode: results.mode,
+                        memories: results.results.map((r) => ({
+                            id: r.id,
+                            content: r.content,
+                            memory_type: r.memory_type,
+                            confidence: r.confidence,
+                        })),
+                    },
+                };
+            },
+        },
+        { name: "memorystack_search" },
+    );
+}

package/tools/stats.ts

@@ -0,0 +1,53 @@
+import { Type } from "@sinclair/typebox";
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { MemoryStackClient } from "@memorystack/sdk";
+import type { MemorystackConfig } from "../config.ts";
+import { log } from "../logger.ts";
+
+export function registerStatsTool(
+    api: ClawdbotPluginApi,
+    cfg: MemorystackConfig,
+): void {
+    api.registerTool(
+        {
+            name: "memorystack_stats",
+            label: "Memory Stats",
+            description: "Get statistics about memory usage and API calls.",
+            parameters: Type.Object({}),
+            async execute() {
+                log.debugRequest("stats", {});
+
+                const client = new MemoryStackClient({
+                    apiKey: cfg.apiKey,
+                    baseUrl: cfg.baseUrl,
+                    enableLogging: cfg.debug,
+                });
+
+                const stats = await client.getStats();
+
+                log.debugResponse("stats", {
+                    total_memories: stats.totals.total_memories,
+                    api_calls: stats.usage.current_month_api_calls,
+                });
+
+                const text = [
+                    `**Total Memories:** ${stats.totals.total_memories}`,
+                    `**API Calls:** ${stats.usage.current_month_api_calls} / ${stats.usage.monthly_api_limit}`,
+                    `**Plan:** ${stats.plan_tier || "Free"}`,
+                    `**Storage:** ${(stats.storage.total_storage_bytes / 1024 / 1024).toFixed(2)} MB`,
+                ].join("\n");
+
+                return {
+                    content: [
+                        {
+                            type: "text" as const,
+                            text: `# MemoryStack Stats\n\n${text}`,
+                        },
+                    ],
+                    details: stats,
+                };
+            },
+        },
+        { name: "memorystack_stats" },
+    );
+}