@memoryrelay/plugin-memoryrelay-ai 0.15.7 → 0.16.0

package/src/hooks/subagent.ts

@@ -0,0 +1,62 @@
+// src/hooks/subagent.ts
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { PluginConfig, MemoryRelayClient } from "../pipelines/types.js";
+
+export interface AutoCaptureConfig {
+  enabled: boolean;
+  tier: string;
+  blocklist?: string[];
+}
+
+export function registerSubagentHooks(
+  api: OpenClawPluginApi,
+  config: PluginConfig,
+  client: MemoryRelayClient,
+  agentId: string,
+  autoCaptureConfig: AutoCaptureConfig,
+  isBlocklisted: (content: string, blocklist: string[]) => boolean,
+): void {
+  api.on("subagent_spawned", async (event, _ctx) => {
+    try {
+      api.logger.debug?.(
+        `memory-memoryrelay: subagent spawned: ${event.agentId} (session: ${event.childSessionKey}, label: ${event.label || "none"})`
+      );
+    } catch (err) {
+      api.logger.warn?.(`memory-memoryrelay: subagent_spawned hook failed: ${String(err)}`);
+    }
+  });
+
+  api.on("subagent_ended", async (event, _ctx) => {
+    try {
+      const outcome = event.outcome || "unknown";
+      const summary = `Subagent ${event.targetSessionKey} ended: ${event.reason} (outcome: ${outcome})`;
+
+      // Only store subagent completions if autoCapture is enabled and content passes filters (#44)
+      if (autoCaptureConfig.enabled) {
+        if (isBlocklisted(summary, autoCaptureConfig.blocklist || [])) {
+          api.logger.debug?.(`memory-memoryrelay: subagent completion blocklisted, skipping storage`);
+          return;
+        }
+
+        // Skip routine completion events — only store failures or unusual outcomes
+        if (outcome === "ok" || outcome === "success") {
+          api.logger.debug?.(`memory-memoryrelay: skipping routine subagent completion: ${summary}`);
+          return;
+        }
+
+        await client.store(summary, {
+          category: "subagent-activity",
+          source: "subagent_ended_hook",
+          agent: agentId,
+          outcome,
+        });
+
+        api.logger.debug?.(`memory-memoryrelay: stored subagent completion: ${summary}`);
+      } else {
+        api.logger.debug?.(`memory-memoryrelay: autoCapture disabled, skipping subagent completion storage`);
+      }
+    } catch (err) {
+      api.logger.warn?.(`memory-memoryrelay: subagent_ended hook failed: ${String(err)}`);
+    }
+  });
+}

package/src/pipelines/capture/content-strip.ts

@@ -0,0 +1,14 @@
+import type { CaptureStage } from "../types.js";
+import { stripContent } from "../../filters/content-patterns.js";
+
+export const captureContentStrip: CaptureStage = {
+  name: "content-strip",
+  enabled: () => true,
+  execute: async (input, _ctx) => {
+    const cleaned = input.messages
+      .map(msg => ({ ...msg, content: stripContent(msg.content) }))
+      .filter(msg => msg.content.length >= 10);
+    if (cleaned.length === 0) return { action: "skip" };
+    return { action: "continue", data: { messages: cleaned } };
+  },
+};

package/src/pipelines/capture/dedup.ts

@@ -0,0 +1,17 @@
+import type { CaptureStage } from "../types.js";
+
+export const captureDedup: CaptureStage = {
+  name: "dedup",
+  enabled: () => true,
+  execute: async (input, ctx) => {
+    const kept = [];
+    for (const msg of input.messages) {
+      const existing = await ctx.client.search(msg.content, 1, 0.95, {
+        namespace: ctx.requestCtx.namespace,
+      });
+      if (existing.length === 0) { kept.push(msg); }
+    }
+    if (kept.length === 0) return { action: "skip" };
+    return { action: "continue", data: { messages: kept } };
+  },
+};

package/src/pipelines/capture/index.ts

@@ -0,0 +1,13 @@
+import type { CaptureStage } from "../types.js";
+import { captureTriggerGate } from "./trigger-gate.js";
+import { captureMessageFilter } from "./message-filter.js";
+import { captureContentStrip } from "./content-strip.js";
+import { captureTruncate } from "./truncate.js";
+import { captureDedup } from "./dedup.js";
+import { captureStore } from "./store.js";
+
+export const capturePipeline: CaptureStage[] = [
+  captureTriggerGate, captureMessageFilter, captureContentStrip, captureTruncate, captureDedup, captureStore,
+];
+
+export { captureTriggerGate, captureMessageFilter, captureContentStrip, captureTruncate, captureDedup, captureStore };

package/src/pipelines/capture/message-filter.ts

@@ -0,0 +1,16 @@
+import type { CaptureStage } from "../types.js";
+import { shouldDropMessage, isAssistantBoilerplate } from "../../filters/noise-patterns.js";
+
+export const captureMessageFilter: CaptureStage = {
+  name: "message-filter",
+  enabled: () => true,
+  execute: async (input, _ctx) => {
+    const kept = input.messages.filter(msg => {
+      if (shouldDropMessage(msg)) return false;
+      if (isAssistantBoilerplate(msg)) return false;
+      return true;
+    });
+    if (kept.length === 0) return { action: "skip" };
+    return { action: "continue", data: { messages: kept } };
+  },
+};

package/src/pipelines/capture/store.ts

@@ -0,0 +1,33 @@
+import type { CaptureStage } from "../types.js";
+import { resolveScope } from "../../filters/content-patterns.js";
+
+export const captureStore: CaptureStage = {
+  name: "store",
+  enabled: () => true,
+  execute: async (input, ctx) => {
+    const tier = ctx.config.autoCapture?.tier ?? "smart";
+    const maxCapture = tier === "conservative" ? 1 : tier === "aggressive" ? 5 : 3;
+    const toStore = input.messages.slice(0, maxCapture);
+
+    // Resolve session UUID for session-scoped storage
+    let sessionId: string | undefined;
+    if (ctx.sessionResolver) {
+      try {
+        const entry = await ctx.sessionResolver.resolve(ctx.requestCtx);
+        sessionId = entry.sessionId;
+      } catch {
+        // Continue without session_id if resolution fails
+      }
+    }
+
+    for (const msg of toStore) {
+      const scope = resolveScope(msg.content);
+      const opts: Record<string, unknown> = { scope };
+      if (scope === "session" && sessionId) {
+        opts.session_id = sessionId;
+      }
+      await ctx.client.store(msg.content, { source: "auto-capture", scope }, opts);
+    }
+    return { action: "continue", data: input };
+  },
+};

package/src/pipelines/capture/trigger-gate.ts

@@ -0,0 +1,21 @@
+import type { CaptureStage } from "../types.js";
+import { isNonInteractive } from "../../filters/non-interactive.js";
+
+export const captureTriggerGate: CaptureStage = {
+  name: "trigger-gate",
+  enabled: () => true,
+  execute: async (input, ctx) => {
+    if (isNonInteractive({
+      trigger: ctx.requestCtx.trigger,
+      sessionKey: ctx.requestCtx.sessionKey,
+      prompt: ctx.requestCtx.prompt,
+    })) {
+      return { action: "skip" };
+    }
+    if (ctx.requestCtx.isSubagent) {
+      const policy = ctx.config.namespace?.subagentPolicy ?? "inherit";
+      if (policy === "skip") { return { action: "skip" }; }
+    }
+    return { action: "continue", data: input };
+  },
+};

package/src/pipelines/capture/truncate.ts

@@ -0,0 +1,16 @@
+import type { CaptureStage } from "../types.js";
+
+export const captureTruncate: CaptureStage = {
+  name: "truncate",
+  enabled: () => true,
+  execute: async (input, ctx) => {
+    const maxLength = ctx.config.autoCapture?.maxMessageLength ?? 2000;
+    const truncated = input.messages.map(msg => ({
+      ...msg,
+      content: msg.content.length > maxLength
+        ? msg.content.slice(0, maxLength) + "\u2026"
+        : msg.content,
+    }));
+    return { action: "continue", data: { messages: truncated } };
+  },
+};

package/src/pipelines/recall/format.ts

@@ -0,0 +1,30 @@
+import type { RecallStage, Memory } from "../types.js";
+
+export function formatMemories(longTerm: Memory[], session: Memory[], isSubagent: boolean): string {
+  const sections: string[] = [];
+  if (longTerm.length > 0) {
+    sections.push(`<long-term-memories>\n${longTerm.map(m => `- ${m.content}`).join("\n")}\n</long-term-memories>`);
+  }
+  if (session.length > 0) {
+    sections.push(`<session-memories>\n${session.map(m => `- ${m.content}`).join("\n")}\n</session-memories>`);
+  }
+  if (isSubagent && sections.length > 0) {
+    sections.unshift("_These memories belong to the parent session. Use for context only._");
+  }
+  return sections.join("\n\n");
+}
+
+export const recallFormat: RecallStage = {
+  name: "format",
+  enabled: () => true,
+  execute: async (input, ctx) => {
+    const { isSubagent } = ctx.requestCtx;
+    const longTermMemories = (input.longTerm ?? []).map(s => s.memory);
+    const sessionMemories = (input.session ?? []).map(s => s.memory);
+    if (longTermMemories.length === 0 && sessionMemories.length === 0) {
+      return { action: "skip" };
+    }
+    const formatted = formatMemories(longTermMemories, sessionMemories, isSubagent);
+    return { action: "continue", data: { ...input, formatted } };
+  },
+};

package/src/pipelines/recall/index.ts

@@ -0,0 +1,12 @@
+import type { RecallStage } from "../types.js";
+import { recallTriggerGate } from "./trigger-gate.js";
+import { recallScopeResolver } from "./scope-resolver.js";
+import { recallSearch } from "./search.js";
+import { recallRank } from "./rank.js";
+import { recallFormat } from "./format.js";
+
+export const recallPipeline: RecallStage[] = [
+  recallTriggerGate, recallScopeResolver, recallSearch, recallRank, recallFormat,
+];
+
+export { recallTriggerGate, recallScopeResolver, recallSearch, recallRank, recallFormat };

package/src/pipelines/recall/rank.ts

@@ -0,0 +1,40 @@
+import type { RecallStage, Memory } from "../types.js";
+
+interface RankingConfig {
+  freshnessBoost?: boolean;
+  freshnessWindowHours?: number;
+  importanceBoost?: boolean;
+  tierBoost?: boolean;
+}
+
+export function scoreMemory(memory: Memory, similarity: number, rankingConfig: RankingConfig): number {
+  let score = similarity;
+  if (rankingConfig.freshnessBoost !== false) {
+    const windowHours = rankingConfig.freshnessWindowHours ?? 24;
+    const ageHours = (Date.now() - new Date(memory.created_at).getTime()) / 3_600_000;
+    if (ageHours < windowHours) { score += 0.1 * (1 - ageHours / windowHours); }
+  }
+  if (rankingConfig.importanceBoost !== false && memory.importance != null) {
+    score += 0.1 * memory.importance;
+  }
+  if (rankingConfig.tierBoost !== false && memory.tier === "hot") { score += 0.05; }
+  return Math.min(score, 1.0);
+}
+
+export const recallRank: RecallStage = {
+  name: "rank",
+  enabled: () => true,
+  execute: async (input, ctx) => {
+    const limit = ctx.config.recallLimit ?? 5;
+    const rankingConfig = ctx.config.ranking ?? {};
+    const scoredLongTerm = (input.longTerm ?? [])
+      .map(r => ({ memory: r.memory, finalScore: scoreMemory(r.memory, r.finalScore, rankingConfig) }))
+      .sort((a, b) => b.finalScore - a.finalScore)
+      .slice(0, limit);
+    const scoredSession = (input.session ?? [])
+      .map(r => ({ memory: r.memory, finalScore: scoreMemory(r.memory, r.finalScore, rankingConfig) }))
+      .sort((a, b) => b.finalScore - a.finalScore)
+      .slice(0, limit);
+    return { action: "continue", data: { ...input, longTerm: scoredLongTerm, session: scoredSession } };
+  },
+};

package/src/pipelines/recall/scope-resolver.ts

@@ -0,0 +1,20 @@
+import type { RecallStage } from "../types.js";
+
+export const recallScopeResolver: RecallStage = {
+  name: "scope-resolver",
+  enabled: () => true,
+  execute: async (input, ctx) => {
+    const { isSubagent, parentSessionKey, sessionKey } = ctx.requestCtx;
+    const policy = ctx.config.namespace?.subagentPolicy ?? "inherit";
+    if (isSubagent && policy === "skip") {
+      return { action: "skip" };
+    }
+    const resolvedSessionKey = (isSubagent && policy === "inherit")
+      ? parentSessionKey ?? sessionKey
+      : sessionKey;
+    return {
+      action: "continue",
+      data: { ...input, resolvedSessionKey },
+    };
+  },
+};

package/src/pipelines/recall/search.ts

@@ -0,0 +1,43 @@
+import type { RecallStage } from "../types.js";
+
+export const recallSearch: RecallStage = {
+  name: "search",
+  enabled: (ctx) => !!ctx.config.autoRecall,
+  execute: async (input, ctx) => {
+    const { client } = ctx;
+    const { namespace } = ctx.requestCtx;
+    const resolvedSessionKey = input.resolvedSessionKey ?? ctx.requestCtx.sessionKey;
+    const limit = ctx.config.recallLimit ?? 5;
+    const threshold = ctx.config.recallThreshold ?? 0.3;
+
+    // Resolve session key to MemoryRelay session UUID
+    let sessionId: string | undefined;
+    if (ctx.sessionResolver) {
+      try {
+        const entry = await ctx.sessionResolver.resolve({
+          ...ctx.requestCtx,
+          sessionKey: resolvedSessionKey,
+        });
+        sessionId = entry.sessionId;
+      } catch {
+        // Fall back to raw session key if resolution fails
+        sessionId = resolvedSessionKey;
+      }
+    } else {
+      sessionId = resolvedSessionKey;
+    }
+
+    const [longTerm, session] = await Promise.all([
+      client.search(input.prompt, limit, threshold, { scope: "long-term", namespace }),
+      client.search(input.prompt, limit, threshold, { scope: "session", session_id: sessionId, namespace }),
+    ]);
+    return {
+      action: "continue",
+      data: {
+        ...input,
+        longTerm: longTerm.map(r => ({ memory: r.memory, finalScore: r.score })),
+        session: session.map(r => ({ memory: r.memory, finalScore: r.score })),
+      },
+    };
+  },
+};

package/src/pipelines/recall/trigger-gate.ts

@@ -0,0 +1,17 @@
+import type { RecallStage } from "../types.js";
+import { isNonInteractive } from "../../filters/non-interactive.js";
+
+export const recallTriggerGate: RecallStage = {
+  name: "trigger-gate",
+  enabled: () => true,
+  execute: async (input, ctx) => {
+    if (isNonInteractive({
+      trigger: ctx.requestCtx.trigger,
+      sessionKey: ctx.requestCtx.sessionKey,
+      prompt: ctx.requestCtx.prompt,
+    })) {
+      return { action: "skip" };
+    }
+    return { action: "continue", data: input };
+  },
+};

package/src/pipelines/runner.ts

@@ -0,0 +1,25 @@
+import type { PipelineContext } from "./types.js";
+
+interface Stage<TInput> {
+  name: string;
+  enabled: (ctx: PipelineContext) => boolean;
+  execute: (input: TInput, ctx: PipelineContext) => Promise<
+    | { action: "continue"; data: TInput }
+    | { action: "skip" }
+  >;
+}
+
+export async function runPipeline<TInput>(
+  stages: Stage<TInput>[],
+  input: TInput,
+  ctx: PipelineContext,
+): Promise<TInput | null> {
+  let current = input;
+  for (const stage of stages) {
+    if (!stage.enabled(ctx)) continue;
+    const result = await stage.execute(current, ctx);
+    if (result.action === "skip") return null;
+    current = result.data;
+  }
+  return current;
+}

package/src/pipelines/types.ts

@@ -0,0 +1,157 @@
+export interface Memory {
+  id: string;
+  content: string;
+  agent_id: string;
+  user_id: string;
+  metadata: Record<string, string>;
+  entities: string[];
+  created_at: string;
+  updated_at: string;
+  importance?: number;
+  tier?: "hot" | "warm" | "cold";
+}
+
+export interface ConversationMessage {
+  role: "user" | "assistant" | "system";
+  content: string;
+}
+
+export interface ScoredMemory {
+  memory: Memory;
+  finalScore: number;
+}
+
+export interface RequestContext {
+  readonly sessionKey: string;
+  readonly agentId: string | null;
+  readonly channel: string | null;
+  readonly trigger: string | null;
+  readonly prompt: string;
+  readonly isSubagent: boolean;
+  readonly parentSessionKey: string | null;
+  readonly namespace: string;
+  readonly timestamp: number;
+}
+
+export interface PluginConfig {
+  apiKey?: string;
+  agentId?: string;
+  apiUrl?: string;
+  defaultProject?: string;
+  autoRecall?: boolean;
+  recallLimit?: number;
+  recallThreshold?: number;
+  excludeChannels?: string[];
+  autoCapture?: {
+    enabled: boolean;
+    tier: "off" | "conservative" | "smart" | "aggressive";
+    confirmFirst?: number;
+    maxMessageLength?: number;
+    stripLargeCodeBlocks?: boolean;
+    categories?: {
+      credentials?: boolean;
+      preferences?: boolean;
+      technical?: boolean;
+      personal?: boolean;
+    };
+    blocklist?: string[];
+  };
+  namespace?: {
+    isolateAgents?: boolean;
+    subagentPolicy?: "inherit" | "isolate" | "skip";
+  };
+  ranking?: {
+    freshnessBoost?: boolean;
+    freshnessWindowHours?: number;
+    importanceBoost?: boolean;
+    tierBoost?: boolean;
+  };
+  sessionTimeoutMinutes?: number;
+  sessionCleanupIntervalMinutes?: number;
+  debug?: boolean;
+  verbose?: boolean;
+  maxLogEntries?: number;
+  logFile?: string;
+}
+
+export interface StoreOptions {
+  deduplicate?: boolean;
+  dedup_threshold?: number;
+  project?: string;
+  importance?: number;
+  tier?: string;
+  scope?: string;
+  session_id?: string;
+}
+
+export interface SearchOptions {
+  include_confidential?: boolean;
+  include_archived?: boolean;
+  compress?: boolean;
+  max_context_tokens?: number;
+  project?: string;
+  tier?: string;
+  min_importance?: number;
+  scope?: string;
+  session_id?: string;
+  namespace?: string;
+}
+
+export interface MemoryRelayClient {
+  search(query: string, limit?: number, threshold?: number, opts?: SearchOptions): Promise<Array<{ memory: Memory; score: number }>>;
+  store(content: string, metadata?: Record<string, string>, options?: StoreOptions): Promise<Memory>;
+  list(limit?: number, offset?: number, opts?: { scope?: string }): Promise<Memory[]>;
+  getOrCreateSession(
+    externalId: string,
+    agentId?: string,
+    title?: string,
+    project?: string,
+    metadata?: Record<string, string>,
+  ): Promise<{ id: string }>;
+  endSession(sessionId: string, summary?: string): Promise<void>;
+}
+
+export interface SessionResolverLike {
+  resolve(requestCtx: RequestContext): Promise<{ sessionId: string; externalId: string }>;
+}
+
+export interface PipelineContext {
+  readonly requestCtx: RequestContext;
+  readonly config: PluginConfig;
+  readonly client: MemoryRelayClient;
+  readonly sessionResolver?: SessionResolverLike;
+}
+
+export interface RecallInput {
+  prompt: string;
+  memories: Memory[];
+  scope: "session" | "long-term" | "all";
+  resolvedSessionKey?: string;
+  longTerm?: ScoredMemory[];
+  session?: ScoredMemory[];
+  formatted?: string;
+}
+
+export type RecallResult =
+  | { action: "continue"; data: RecallInput }
+  | { action: "skip" };
+
+export interface RecallStage {
+  name: string;
+  enabled: (ctx: PipelineContext) => boolean;
+  execute: (input: RecallInput, ctx: PipelineContext) => Promise<RecallResult>;
+}
+
+export interface CaptureInput {
+  messages: ConversationMessage[];
+}
+
+export type CaptureResult =
+  | { action: "continue"; data: CaptureInput }
+  | { action: "skip" };
+
+export interface CaptureStage {
+  name: string;
+  enabled: (ctx: PipelineContext) => boolean;
+  execute: (input: CaptureInput, ctx: PipelineContext) => Promise<CaptureResult>;
+}

package/src/tools/agent-tools.ts

@@ -0,0 +1,127 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { PluginConfig } from "../pipelines/types.js";
+import type { MemoryRelayClient } from "../client/memoryrelay-client.js";
+
+export function registerAgentTools(
+  api: OpenClawPluginApi,
+  config: PluginConfig,
+  client: MemoryRelayClient,
+  isToolEnabled: (name: string) => boolean,
+): void {
+
+  // --------------------------------------------------------------------------
+  // 14. agent_list
+  // --------------------------------------------------------------------------
+  if (isToolEnabled("agent_list")) {
+    api.registerTool((ctx) => ({
+
+        name: "agent_list",
+        description: "List available agents.",
+        parameters: {
+          type: "object",
+          properties: {
+            limit: {
+              type: "number",
+              description: "Maximum agents to return. Default 20.",
+              minimum: 1,
+              maximum: 100,
+            },
+          },
+        },
+        execute: async (_id, args: { limit?: number }) => {
+          try {
+            const result = await client.listAgents(args.limit);
+            return {
+              content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+              details: { result },
+            };
+          } catch (err) {
+            return {
+              content: [{ type: "text", text: `Failed to list agents: ${String(err)}` }],
+              details: { error: String(err) },
+            };
+          }
+        },
+      }),
+      { name: "agent_list" },
+    );
+  }
+
+  // --------------------------------------------------------------------------
+  // 15. agent_create
+  // --------------------------------------------------------------------------
+  if (isToolEnabled("agent_create")) {
+    api.registerTool((ctx) => ({
+
+        name: "agent_create",
+        description: "Create a new agent. Agents serve as memory namespaces and isolation boundaries.",
+        parameters: {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: "Agent name.",
+            },
+            description: {
+              type: "string",
+              description: "Optional agent description.",
+            },
+          },
+          required: ["name"],
+        },
+        execute: async (_id, args: { name: string; description?: string }) => {
+          try {
+            const result = await client.createAgent(args.name, args.description);
+            return {
+              content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+              details: { result },
+            };
+          } catch (err) {
+            return {
+              content: [{ type: "text", text: `Failed to create agent: ${String(err)}` }],
+              details: { error: String(err) },
+            };
+          }
+        },
+      }),
+      { name: "agent_create" },
+    );
+  }
+
+  // --------------------------------------------------------------------------
+  // 16. agent_get
+  // --------------------------------------------------------------------------
+  if (isToolEnabled("agent_get")) {
+    api.registerTool((ctx) => ({
+
+        name: "agent_get",
+        description: "Get details about a specific agent by ID.",
+        parameters: {
+          type: "object",
+          properties: {
+            id: {
+              type: "string",
+              description: "Agent UUID.",
+            },
+          },
+          required: ["id"],
+        },
+        execute: async (_id, args: { id: string }) => {
+          try {
+            const result = await client.getAgent(args.id);
+            return {
+              content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+              details: { result },
+            };
+          } catch (err) {
+            return {
+              content: [{ type: "text", text: `Failed to get agent: ${String(err)}` }],
+              details: { error: String(err) },
+            };
+          }
+        },
+      }),
+      { name: "agent_get" },
+    );
+  }
+}