@memorystack/clawdbot-memorystack 1.0.0 → 1.1.0

package/hooks/capture.ts

@@ -18,7 +18,11 @@ function getLastTurn(messages: unknown[]): unknown[] {
     return lastUserIdx >= 0 ? messages.slice(lastUserIdx) : messages;
 }
 
-export function buildCaptureHandler(cfg: MemorystackConfig) {
+export function buildCaptureHandler(
+    cfg: MemorystackConfig,
+    getSessionKey?: () => string | undefined,
+    getContext?: () => Record<string, any>,
+) {
     return async (event: Record<string, unknown>) => {
         if (
             !event.success ||
@@ -72,6 +76,8 @@ export function buildCaptureHandler(cfg: MemorystackConfig) {
         if (captured.length === 0) return;
 
         const content = captured.join("\n\n");
+        const sessionKey = getSessionKey?.();
+        const ctx = getContext?.() || {};
 
         log.debug(
             `capturing ${captured.length} texts (${content.length} chars)`,
@@ -84,8 +90,28 @@ export function buildCaptureHandler(cfg: MemorystackConfig) {
                 enableLogging: cfg.debug,
             });
 
+            // Prepare metadata from context
+            const metadata: Record<string, any> = {
+                source: "clawdbot_auto_capture",
+                session_id: sessionKey,
+                timestamp: new Date().toISOString(),
+                user_id: ctx.userId,
+                agent_id: ctx.agentId,
+                provider: ctx.Provider,
+                model: ctx.Model,
+                sender_name: ctx.SenderName,
+            };
+
+            // Remove undefined values
+            Object.keys(metadata).forEach(key => metadata[key] === undefined && delete metadata[key]);
+
             await client.add(content, {
-                metadata: { source: "clawdbot_auto_capture", timestamp: new Date().toISOString() },
+                sessionId: sessionKey,
+                agentId: ctx.agentId,
+                userId: ctx.userId,
+                teamId: ctx.teamId,
+                conversationId: ctx.conversationId,
+                metadata: metadata,
             });
 
             log.debug(`captured ${captured.length} messages successfully`);

package/index.ts

@@ -4,9 +4,40 @@ import { initLogger } from "./logger.ts";
 import { registerSearchTool } from "./tools/search.ts";
 import { registerAddTool } from "./tools/add.ts";
 import { registerStatsTool } from "./tools/stats.ts";
+import { registerDeleteTool } from "./tools/delete.ts";
+import { registerReflectTool } from "./tools/reflect.ts";
+import { registerConsolidateTool } from "./tools/consolidate.ts";
 import { buildRecallHandler } from "./hooks/recall.ts";
 import { buildCaptureHandler } from "./hooks/capture.ts";
 
+// Helper to properly parse Moltbot session keys
+// Format: "agent:{agentId}:{rest}" where rest may be "subagent:{uuid}" or "main" etc.
+function parseSessionKey(sessionKey: string | undefined | null): {
+    agentId: string;
+    subagentId: string | null;
+    sessionId: string;
+} {
+    const DEFAULT_AGENT = "main";
+    if (!sessionKey) return { agentId: DEFAULT_AGENT, subagentId: null, sessionId: "" };
+
+    const parts = sessionKey.split(":");
+    if (parts.length < 3 || parts[0] !== "agent") {
+        // Not a standard agent session key, return as-is
+        return { agentId: DEFAULT_AGENT, subagentId: null, sessionId: sessionKey };
+    }
+
+    const agentId = parts[1] || DEFAULT_AGENT;
+    const rest = parts.slice(2).join(":");
+
+    // Check if this is a subagent session
+    let subagentId: string | null = null;
+    if (rest.toLowerCase().startsWith("subagent:")) {
+        subagentId = rest.slice("subagent:".length);
+    }
+
+    return { agentId, subagentId, sessionId: sessionKey };
+}
+
 export default {
     id: "clawdbot-memorystack",
     name: "MemoryStack",
@@ -24,20 +55,64 @@ export default {
 
         initLogger(api.logger, cfg.debug);
 
+        // Context tracking
+        let currentContext: Record<string, any> = {};
+        const getContext = () => currentContext;
+        const getSessionKey = () => currentContext.sessionKey;
+
         // Register tools
-        registerSearchTool(api, cfg);
-        registerAddTool(api, cfg);
+        registerSearchTool(api, cfg, getSessionKey, getContext);
+        registerAddTool(api, cfg, getSessionKey, getContext);
         registerStatsTool(api, cfg);
+        registerDeleteTool(api, cfg);
+        registerReflectTool(api, cfg);
+        registerConsolidateTool(api, cfg);
 
-        // Auto-recall hook
-        if (cfg.autoRecall) {
-            const recallHandler = buildRecallHandler(cfg);
-            api.on("before_agent_start", recallHandler);
-        }
+        // ALWAYS capture context on before_agent_start (regardless of autoRecall setting)
+        // This ensures tools like memorystack_add have access to agentId, subagentId, etc.
+        const recallHandler = cfg.autoRecall ? buildRecallHandler(cfg, getSessionKey) : null;
+
+        api.on("before_agent_start", (event: Record<string, unknown>, ctx: Record<string, unknown>) => {
+            if (ctx) {
+                currentContext = { ...ctx };
+
+                // Parse session key to extract proper IDs
+                // Moltbot passes agentId incorrectly as "agent" (the literal prefix)
+                // We need to parse the sessionKey to get the actual agentId
+                const parsed = parseSessionKey(currentContext.sessionKey as string);
+
+                // Use parsed agentId, overriding the incorrect ctx.agentId
+                if (!currentContext.agentId || currentContext.agentId === "agent") {
+                    currentContext.agentId = parsed.agentId;
+                }
+
+                // Track subagent ID separately if present (for scoped searches)
+                if (parsed.subagentId) {
+                    currentContext.subagentId = parsed.subagentId;
+                }
+
+                // Normalize other commonly used fields
+                if (!currentContext.userId && currentContext.SenderId) currentContext.userId = currentContext.SenderId;
+
+                // Map group context to MemoryStack scoping
+                if (currentContext.groupId) currentContext.teamId = currentContext.groupId;
+                if (currentContext.groupChannel) currentContext.conversationId = currentContext.groupChannel;
+                // Fallback for conversation ID from session key if no group channel
+                if (!currentContext.conversationId && getSessionKey()) currentContext.conversationId = getSessionKey();
+            }
+
+            // Only run recall if autoRecall is enabled
+            if (recallHandler) {
+                return recallHandler(event);
+            }
+        });
 
         // Auto-capture hook
         if (cfg.autoCapture) {
-            api.on("agent_end", buildCaptureHandler(cfg));
+            const captureHandler = buildCaptureHandler(cfg, getSessionKey, getContext);
+            api.on("agent_end", (event: Record<string, unknown>) => {
+                return captureHandler(event);
+            });
         }
 
         // Register service

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@memorystack/clawdbot-memorystack",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "type": "module",
     "description": "Clawdbot MemoryStack memory plugin - long-term memory for your AI assistant",
     "license": "MIT",
@@ -22,7 +22,7 @@
         "access": "public"
     },
     "dependencies": {
-        "@memorystack/sdk": "^1.0.3",
+        "@memorystack/sdk": "^1.0.4",
         "@sinclair/typebox": "0.34.47"
     },
     "peerDependencies": {

package/tools/add.ts

@@ -7,21 +7,51 @@ import { log } from "../logger.ts";
 export function registerAddTool(
     api: ClawdbotPluginApi,
     cfg: MemorystackConfig,
+    getSessionKey?: () => string | undefined,
+    getContext?: () => Record<string, any>,
 ): void {
     api.registerTool(
         {
             name: "memorystack_add",
             label: "Memory Add",
-            description: "Save important information to long-term memory with automatic importance scoring.",
+            description: `Save important information to long-term memory with automatic importance scoring.
+
+**Automatic Context Capture**: The following are automatically captured from your session context:
+- agent_id: Your agent identifier (e.g., "main", subagent UUID)
+- session_id: Current session key for conversation tracking
+- team_id: Team/group identifier (if in a group chat)
+- conversation_id: Specific conversation thread ID
+- user_id: The sender's ID (can be overridden with userId parameter)
+
+You don't need to specify these manually - they are captured automatically to organize memories.`,
             parameters: Type.Object({
                 text: Type.String({ description: "Information to remember" }),
-                userId: Type.Optional(Type.String({ description: "User ID (for B2B apps)" })),
+                userId: Type.Optional(Type.String({ description: "Override user ID (defaults to sender)" })),
+                memory_type: Type.Optional(
+                    Type.String({
+                        description: "Type of memory: fact, preference, episode, procedure, belief",
+                    }),
+                ),
             }),
             async execute(
                 _toolCallId: string,
-                params: { text: string; userId?: string },
+                params: { text: string; userId?: string; memory_type?: string },
             ) {
-                log.debugRequest("add", { textLength: params.text.length, userId: params.userId });
+                const sessionKey = getSessionKey?.();
+                const ctx = getContext?.() || {};
+
+                // For subagents, use the subagent UUID as the agent_id
+                // This ensures subagent memories are properly attributed
+                const effectiveAgentId = ctx.subagentId || ctx.agentId || "main";
+
+                log.debugRequest("add", {
+                    textLength: params.text.length,
+                    userId: params.userId,
+                    sessionKey,
+                    agentId: ctx.agentId,
+                    subagentId: ctx.subagentId,
+                    effectiveAgentId,
+                });
 
                 const client = new MemoryStackClient({
                     apiKey: cfg.apiKey,
@@ -29,9 +59,30 @@ export function registerAddTool(
                     enableLogging: cfg.debug,
                 });
 
+                // Prepare metadata from context
+                const metadata: Record<string, any> = {
+                    source: "clawdbot_tool",
+                    session_key: sessionKey,
+                    timestamp: new Date().toISOString(),
+                    user_id: params.userId ?? ctx.userId,
+                    parent_agent_id: ctx.agentId,  // Track the parent agent
+                    subagent_id: ctx.subagentId,   // Track if this is a subagent
+                    provider: ctx.Provider,
+                    model: ctx.Model,
+                    sender_name: ctx.SenderName,
+                };
+
+                // Remove undefined values
+                Object.keys(metadata).forEach(key => metadata[key] === undefined && delete metadata[key]);
+
                 const result = await client.add(params.text, {
-                    userId: params.userId,
-                    metadata: { source: "clawdbot_tool" },
+                    userId: params.userId ?? ctx.userId,
+                    sessionId: sessionKey,
+                    agentId: effectiveAgentId,  // Use subagentId if available!
+                    teamId: ctx.teamId,
+                    conversationId: ctx.conversationId,
+                    memory_type: params.memory_type,
+                    metadata: metadata,
                 });
 
                 log.debugResponse("add", {

package/tools/consolidate.ts

@@ -0,0 +1,116 @@
+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 registerConsolidateTool(
+    api: ClawdbotPluginApi,
+    cfg: MemorystackConfig,
+): void {
+    api.registerTool(
+        {
+            name: "memorystack_consolidate",
+            label: "Consolidate Memories",
+            description:
+                "Merge duplicate or highly similar memories to reduce noise and keep memory clean. Useful for maintenance.",
+            parameters: Type.Object({
+                similarityThreshold: Type.Optional(
+                    Type.Number({
+                        description: "Similarity threshold 0-1 (default: 0.85). Higher = stricter matching.",
+                    }),
+                ),
+                dryRun: Type.Optional(
+                    Type.Boolean({
+                        description: "Preview only, don't merge (default: false)",
+                    }),
+                ),
+                maxPairs: Type.Optional(
+                    Type.Number({
+                        description: "Max pairs to process (default: 20)",
+                    }),
+                ),
+            }),
+            async execute(
+                _toolCallId: string,
+                params: {
+                    similarityThreshold?: number;
+                    dryRun?: boolean;
+                    maxPairs?: number;
+                },
+            ) {
+                const similarityThreshold = params.similarityThreshold ?? 0.85;
+                const dryRun = params.dryRun ?? false;
+                const maxPairs = params.maxPairs ?? 20;
+
+                log.debugRequest("consolidate", { similarityThreshold, dryRun, maxPairs });
+
+                const client = new MemoryStackClient({
+                    apiKey: cfg.apiKey,
+                    baseUrl: cfg.baseUrl,
+                    enableLogging: cfg.debug,
+                });
+
+                try {
+                    const result = await client.consolidateMemories({
+                        similarityThreshold,
+                        dryRun,
+                    });
+
+                    log.debugResponse("consolidate", {
+                        merged: result.memoriesMerged ?? 0,
+                        processed: result.memoriesProcessed ?? 0,
+                    });
+
+                    // Format output
+                    const lines: string[] = [];
+                    lines.push(`# 🧹 Memory Consolidation`);
+                    lines.push("");
+                    lines.push(`**Memories Processed:** ${result.memoriesProcessed ?? 0}`);
+                    lines.push(`**Duplicates Merged:** ${result.memoriesMerged ?? 0}`);
+                    lines.push(`**Memories Removed:** ${result.memoriesRemoved ?? 0}`);
+
+                    if (result.mergedPairs && result.mergedPairs.length > 0) {
+                        lines.push("");
+                        lines.push("## Merged Pairs");
+                        for (const pair of result.mergedPairs.slice(0, 5)) {
+                            lines.push(`- Merged: "${pair.original?.substring(0, 50)}..." → "${pair.merged?.substring(0, 50)}..."`);
+                        }
+                    }
+
+                    if (dryRun) {
+                        lines.push("");
+                        lines.push("*This was a dry run - no changes were made.*");
+                    } else if (result.memoriesMerged === 0) {
+                        lines.push("");
+                        lines.push("✨ No duplicates found - your memory is already clean!");
+                    } else {
+                        lines.push("");
+                        lines.push("✅ Consolidation complete!");
+                    }
+
+                    return {
+                        content: [
+                            {
+                                type: "text" as const,
+                                text: lines.join("\n"),
+                            },
+                        ],
+                        details: result,
+                    };
+                } catch (error: any) {
+                    log.error("consolidate failed", error);
+                    return {
+                        content: [
+                            {
+                                type: "text" as const,
+                                text: `❌ Consolidation failed: ${error?.message || "Unknown error"}`,
+                            },
+                        ],
+                    };
+                }
+            },
+        },
+        { name: "memorystack_consolidate" },
+    );
+}

package/tools/delete.ts

@@ -0,0 +1,68 @@
+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 registerDeleteTool(
+    api: ClawdbotPluginApi,
+    cfg: MemorystackConfig,
+): void {
+    api.registerTool(
+        {
+            name: "memorystack_delete",
+            label: "Delete Memory",
+            description:
+                "Delete a memory by ID. Use search first to find the memory ID if you only have the content.",
+            parameters: Type.Object({
+                memoryId: Type.String({ description: "UUID of the memory to delete" }),
+                hard: Type.Optional(
+                    Type.Boolean({
+                        description: "Permanently delete (true) or soft delete (false, default)",
+                    }),
+                ),
+            }),
+            async execute(
+                _toolCallId: string,
+                params: { memoryId: string; hard?: boolean },
+            ) {
+                log.debugRequest("delete", { memoryId: params.memoryId, hard: params.hard });
+
+                const client = new MemoryStackClient({
+                    apiKey: cfg.apiKey,
+                    baseUrl: cfg.baseUrl,
+                    enableLogging: cfg.debug,
+                });
+
+                try {
+                    const result = await client.deleteMemory(params.memoryId, params.hard ?? false);
+
+                    log.debugResponse("delete", { success: result.success });
+
+                    return {
+                        content: [
+                            {
+                                type: "text" as const,
+                                text: result.success
+                                    ? `✅ Memory deleted successfully (ID: ${params.memoryId})`
+                                    : `❌ Failed to delete memory`,
+                            },
+                        ],
+                        details: result,
+                    };
+                } catch (error: any) {
+                    log.error("delete failed", error);
+                    return {
+                        content: [
+                            {
+                                type: "text" as const,
+                                text: `❌ Failed to delete memory: ${error?.message || "Unknown error"}`,
+                            },
+                        ],
+                    };
+                }
+            },
+        },
+        { name: "memorystack_delete" },
+    );
+}

package/tools/reflect.ts

@@ -0,0 +1,119 @@
+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 registerReflectTool(
+    api: ClawdbotPluginApi,
+    cfg: MemorystackConfig,
+): void {
+    api.registerTool(
+        {
+            name: "memorystack_reflect",
+            label: "Reflect on Memories",
+            description:
+                "Analyze memories to discover patterns, generate insights, and identify recurring themes. Great for understanding user behavior over time.",
+            parameters: Type.Object({
+                timeWindowDays: Type.Optional(
+                    Type.Number({
+                        description: "Analyze memories from last N days (default: 7, max: 90)",
+                    }),
+                ),
+                analysisDepth: Type.Optional(
+                    Type.String({
+                        description: "Analysis depth: 'shallow' (faster) or 'deep' (more thorough)",
+                    }),
+                ),
+                dryRun: Type.Optional(
+                    Type.Boolean({
+                        description: "Preview only, don't save insights (default: false)",
+                    }),
+                ),
+            }),
+            async execute(
+                _toolCallId: string,
+                params: {
+                    timeWindowDays?: number;
+                    analysisDepth?: string;
+                    dryRun?: boolean;
+                },
+            ) {
+                const timeWindowDays = params.timeWindowDays ?? 7;
+                const analysisDepth = params.analysisDepth ?? "shallow";
+                const dryRun = params.dryRun ?? false;
+
+                log.debugRequest("reflect", { timeWindowDays, analysisDepth, dryRun });
+
+                const client = new MemoryStackClient({
+                    apiKey: cfg.apiKey,
+                    baseUrl: cfg.baseUrl,
+                    enableLogging: cfg.debug,
+                });
+
+                try {
+                    const result = await client.reflectOnMemories({
+                        timeWindowDays,
+                        analysisDepth: analysisDepth as "shallow" | "deep",
+                        dryRun,
+                    });
+
+                    log.debugResponse("reflect", {
+                        patterns: result.patterns?.length ?? 0,
+                        insights: result.insightsGenerated ?? 0,
+                    });
+
+                    // Format output
+                    const lines: string[] = [];
+                    lines.push(`# 🔮 Memory Reflection`);
+                    lines.push("");
+                    lines.push(`**Memories Analyzed:** ${result.memoriesAnalyzed}`);
+                    lines.push(`**Patterns Found:** ${result.patterns?.length ?? 0}`);
+                    lines.push(`**Insights Generated:** ${result.insightsGenerated ?? 0}`);
+
+                    if (result.patterns && result.patterns.length > 0) {
+                        lines.push("");
+                        lines.push("## Patterns");
+                        for (const pattern of result.patterns.slice(0, 5)) {
+                            lines.push(`- **${pattern.type || "Pattern"}:** ${pattern.description || pattern.content}`);
+                        }
+                    }
+
+                    if (result.insights && result.insights.length > 0) {
+                        lines.push("");
+                        lines.push("## Insights");
+                        for (const insight of result.insights.slice(0, 5)) {
+                            lines.push(`- ${insight.content || insight}`);
+                        }
+                    }
+
+                    if (dryRun) {
+                        lines.push("");
+                        lines.push("*This was a dry run - no insights were saved.*");
+                    }
+
+                    return {
+                        content: [
+                            {
+                                type: "text" as const,
+                                text: lines.join("\n"),
+                            },
+                        ],
+                        details: result,
+                    };
+                } catch (error: any) {
+                    log.error("reflect failed", error);
+                    return {
+                        content: [
+                            {
+                                type: "text" as const,
+                                text: `❌ Reflection failed: ${error?.message || "Unknown error"}`,
+                            },
+                        ],
+                    };
+                }
+            },
+        },
+        { name: "memorystack_reflect" },
+    );
+}

package/tools/search.ts

@@ -7,18 +7,43 @@ import { log } from "../logger.ts";
 export function registerSearchTool(
     api: ClawdbotPluginApi,
     cfg: MemorystackConfig,
+    getSessionKey?: () => string | undefined,
+    getContext?: () => Record<string, any>,
 ): 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.",
+            description: `Search through long-term memories using semantic search.
+
+**Automatic Context**: Your agent_id, session_id, team_id, and conversation_id are available for filtering.
+
+**Scoping Options**:
+- scope="global": Search all memories (default)
+- scope="agent": Search only memories from THIS agent
+- scope="team": Search only memories from this team/group
+
+**Explicit Filters** (override scope):
+- agent_id: Search memories from a specific agent/subagent by UUID
+- session_id: Search memories from a specific session
+- metadata: Filter by metadata key-value pairs (e.g., parent_agent_id, source)
+
+**Filtering**: Supports memory_type, min_confidence, days_ago, and current_session filters.`,
             parameters: Type.Object({
                 query: Type.String({ description: "Search query" }),
                 limit: Type.Optional(
                     Type.Number({ description: "Max results (default: 5)" }),
                 ),
+                agent_id: Type.Optional(
+                    Type.String({
+                        description: "Filter by specific agent/subagent UUID (e.g., from a spawned subagent)",
+                    }),
+                ),
+                session_id: Type.Optional(
+                    Type.String({
+                        description: "Filter by specific session key",
+                    }),
+                ),
                 memory_type: Type.Optional(
                     Type.String({
                         description:
@@ -35,19 +60,47 @@ export function registerSearchTool(
                         description: "Only memories from last N days",
                     }),
                 ),
+                current_session: Type.Optional(
+                    Type.Boolean({
+                        description: "Filter to current session only (default: false)",
+                    }),
+                ),
+                scope: Type.Optional(
+                    Type.String({
+                        description: "Scope of search: 'global', 'agent', 'team' (default: 'global')",
+                        enum: ["global", "agent", "team"],
+                    }),
+                ),
+                metadata: Type.Optional(
+                    Type.Record(Type.String(), Type.Any(), {
+                        description: "Filter by metadata fields (e.g., { parent_agent_id: 'main' })",
+                    }),
+                ),
             }),
             async execute(
                 _toolCallId: string,
                 params: {
                     query: string;
                     limit?: number;
+                    agent_id?: string;
+                    session_id?: string;
                     memory_type?: string;
                     min_confidence?: number;
                     days_ago?: number;
+                    current_session?: boolean;
+                    scope?: "global" | "agent" | "team";
+                    metadata?: Record<string, any>;
                 },
             ) {
                 const limit = params.limit ?? 5;
-                log.debugRequest("search", { query: params.query, limit, ...params });
+                const sessionKey = getSessionKey?.();
+                const ctx = getContext?.() || {};
+
+                log.debugRequest("search", {
+                    query: params.query,
+                    scope: params.scope,
+                    agentId: ctx.agentId
+                });
 
                 const client = new MemoryStackClient({
                     apiKey: cfg.apiKey,
@@ -55,51 +108,102 @@ export function registerSearchTool(
                     enableLogging: cfg.debug,
                 });
 
-                const searchOpts: Record<string, unknown> = { limit };
-                if (params.memory_type) {
-                    searchOpts.memory_type = params.memory_type;
+                // Build search options
+                const searchOpts: any = {
+                    limit,
+                    userId: ctx.userId, // Default to current user
+                    min_confidence: params.min_confidence,
+                    memory_type: params.memory_type,
+                };
+
+                // For subagents, use subagentId as the effective agent
+                const effectiveAgentId = ctx.subagentId || ctx.agentId;
+
+                // Priority: explicit params > scope > default
+                // 1. Explicit agent_id/session_id params override everything
+                if (params.agent_id) {
+                    searchOpts.agentId = params.agent_id;
+                } else if (params.scope === "agent" && effectiveAgentId) {
+                    // 2. Scope-based filtering
+                    searchOpts.agentId = effectiveAgentId;
+                } else if (params.scope === "team" && ctx.teamId) {
+                    searchOpts.teamId = ctx.teamId;
+                }
+                // 3. global scope = no agent filter (default)
+
+                // Session filtering: explicit param > current_session flag
+                if (params.session_id) {
+                    searchOpts.sessionId = params.session_id;
+                } else if (params.current_session && sessionKey) {
+                    searchOpts.sessionId = sessionKey;
+                }
+
+                // Metadata filtering (passed directly to SDK)
+                if (params.metadata && Object.keys(params.metadata).length > 0) {
+                    searchOpts.metadata = params.metadata;
+                }
+
+                // Apply Time Filter (handled via generic params if needed, or client-side filtering)
+                // improved SDK might support start_date, but for now we can rely on natural language query 
+                // or pass it if backend supports it. The backend supports start_date.
+                if (params.days_ago) {
+                    const date = new Date();
+                    date.setDate(date.getDate() - params.days_ago);
+                    searchOpts.start_date = date.toISOString();
                 }
 
-                const results = await client.search(params.query, searchOpts);
+                try {
+                    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)}%)`
+                                : "";
+                            // Full ISO timestamp for temporal reasoning (e.g., 2024-06-03T14:30:00Z)
+                            const timestamp = r.created_at ? ` [${r.created_at}]` : "";
+                            return `${i + 1}. ${r.content}${type}${conf}${timestamp}`;
+                        })
+                        .join("\n");
+
+                    log.debugResponse("search", { count: results.count });
 
-                if (results.count === 0) {
                     return {
                         content: [
-                            { type: "text" as const, text: "No relevant memories found." },
+                            {
+                                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,
+                                created_at: r.created_at,
+                                metadata: r.metadata,
+                            })),
+                        },
+                    };
+                } catch (error: any) {
+                    log.error("search failed", error);
+                    return {
+                        content: [{ type: "text", text: `Search failed: ${error.message}` }],
+                        isError: true,
                     };
                 }
-
-                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/verify_recent.ts

@@ -0,0 +1,52 @@
+import { MemoryStackClient } from "@memorystack/sdk";
+
+const API_KEY = "mem_live_KT9roc_L4O60KJ6_l7SGdzXeTib1RHoF3QlmhLghMbQ";
+
+async function verifyRecentMemories() {
+    const client = new MemoryStackClient({
+        apiKey: API_KEY,
+        baseUrl: "http://localhost:3000",
+    });
+
+    console.log("🔍 Inspecting Most Recent Memories\n");
+    console.log("=".repeat(60) + "\n");
+
+    try {
+        // Fetch 5 most recent memories
+        const results = await client.search("memorystack", {
+            limit: 5,
+        });
+
+        console.log(`Found ${results.count} recent memories.\n`);
+
+        results.results.forEach((m, i) => {
+            console.log(`Memory #${i + 1}`);
+            console.log(`   ID: ${m.id}`);
+            console.log(`   Agent ID: "${m.agent_id}"`);
+            console.log(`   Session ID: "${m.session_id}"`);
+            console.log(`   Created At: ${m.created_at}`);
+            console.log(`   Content: ${m.content.substring(0, 100)}...`);
+
+            // Check metadata for subagent details
+            if (m.metadata) {
+                console.log(`   Metadata:`);
+                if (m.metadata.subagent_id) console.log(`      - subagent_id: ${m.metadata.subagent_id}`);
+                if (m.metadata.parent_agent_id) console.log(`      - parent_agent_id: ${m.metadata.parent_agent_id}`);
+            }
+
+            // Verification logic
+            if (m.agent_id !== "main" && m.agent_id !== "agent") {
+                console.log(`   ✅ SUCCESS: Uses specific Agent ID!`);
+            } else if (m.metadata?.subagent_id) {
+                console.log(`   ⚠️ Stored as 'main', but has subagent_id in metadata.`);
+            }
+
+            console.log("-".repeat(40));
+        });
+
+    } catch (e: any) {
+        console.log(`❌ Error: ${e.message}`);
+    }
+}
+
+verifyRecentMemories().catch(console.error);