@bjlee2024/claude-mem 13.4.0

package/openclaw/src/index.ts

@@ -0,0 +1,1092 @@
+
+
+interface PluginLogger {
+  debug?: (message: string) => void;
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+}
+
+interface PluginServiceContext {
+  config: Record<string, unknown>;
+  workspaceDir?: string;
+  stateDir: string;
+  logger: PluginLogger;
+}
+
+interface PluginCommandContext {
+  senderId?: string;
+  channel: string;
+  isAuthorizedSender: boolean;
+  args?: string;
+  commandBody: string;
+  config: Record<string, unknown>;
+}
+
+type PluginCommandResult = string | { text: string } | { text: string; format?: string };
+
+interface BeforeAgentStartEvent {
+  prompt?: string;
+}
+
+interface BeforePromptBuildEvent {
+  prompt: string;
+  messages: unknown[];
+}
+
+interface BeforePromptBuildResult {
+  systemPrompt?: string;
+  prependContext?: string;
+  prependSystemContext?: string;
+  appendSystemContext?: string;
+}
+
+interface ToolResultPersistEvent {
+  toolName?: string;
+  params?: Record<string, unknown>;
+  message?: {
+    content?: Array<{ type: string; text?: string }>;
+  };
+}
+
+interface AgentEndEvent {
+  messages?: Array<{
+    role: string;
+    content: string | Array<{ type: string; text?: string }>;
+  }>;
+}
+
+interface SessionStartEvent {
+  sessionId: string;
+  resumedFrom?: string;
+}
+
+interface AfterCompactionEvent {
+  messageCount: number;
+  tokenCount?: number;
+  compactedCount: number;
+}
+
+interface SessionEndEvent {
+  sessionId: string;
+  messageCount: number;
+  durationMs?: number;
+}
+
+interface MessageReceivedEvent {
+  from: string;
+  content: string;
+  timestamp?: number;
+  metadata?: Record<string, unknown>;
+}
+
+interface EventContext {
+  sessionKey?: string;
+  workspaceDir?: string;
+  agentId?: string;
+}
+
+interface MessageContext {
+  channelId: string;
+  accountId?: string;
+  conversationId?: string;
+}
+
+type EventCallback<T> = (event: T, ctx: EventContext) => void | Promise<void>;
+type PromptBuildCallback = (event: BeforePromptBuildEvent, ctx: EventContext) => BeforePromptBuildResult | Promise<BeforePromptBuildResult | void> | void;
+type MessageEventCallback<T> = (event: T, ctx: MessageContext) => void | Promise<void>;
+
+interface OpenClawPluginApi {
+  id: string;
+  name: string;
+  version?: string;
+  source: string;
+  config: Record<string, unknown>;
+  pluginConfig?: Record<string, unknown>;
+  logger: PluginLogger;
+  registerService: (service: {
+    id: string;
+    start: (ctx: PluginServiceContext) => void | Promise<void>;
+    stop?: (ctx: PluginServiceContext) => void | Promise<void>;
+  }) => void;
+  registerCommand: (command: {
+    name: string;
+    description: string;
+    acceptsArgs?: boolean;
+    requireAuth?: boolean;
+    handler: (ctx: PluginCommandContext) => PluginCommandResult | Promise<PluginCommandResult>;
+  }) => void;
+  on: ((event: "before_prompt_build", callback: PromptBuildCallback) => void) &
+      ((event: "before_agent_start", callback: EventCallback<BeforeAgentStartEvent>) => void) &
+      ((event: "tool_result_persist", callback: EventCallback<ToolResultPersistEvent>) => void) &
+      ((event: "agent_end", callback: EventCallback<AgentEndEvent>) => void) &
+      ((event: "session_start", callback: EventCallback<SessionStartEvent>) => void) &
+      ((event: "session_end", callback: EventCallback<SessionEndEvent>) => void) &
+      ((event: "message_received", callback: MessageEventCallback<MessageReceivedEvent>) => void) &
+      ((event: "after_compaction", callback: EventCallback<AfterCompactionEvent>) => void) &
+      ((event: "gateway_start", callback: EventCallback<Record<string, never>>) => void);
+  runtime: {
+    channel: Record<string, Record<string, (...args: any[]) => Promise<any>>>;
+  };
+}
+
+interface ObservationSSEPayload {
+  id: number;
+  memory_session_id: string;
+  session_id: string;
+  type: string;
+  title: string | null;
+  subtitle: string | null;
+  text: string | null;
+  narrative: string | null;
+  facts: string | null;
+  concepts: string | null;
+  files_read: string | null;
+  files_modified: string | null;
+  project: string | null;
+  prompt_number: number;
+  created_at_epoch: number;
+}
+
+interface SSENewObservationEvent {
+  type: "new_observation";
+  observation: ObservationSSEPayload;
+  timestamp: number;
+}
+
+type ConnectionState = "disconnected" | "connected" | "reconnecting";
+
+interface FeedEmojiConfig {
+  primary?: string;
+  claudeCode?: string;
+  claudeCodeLabel?: string;
+  default?: string;
+  agents?: Record<string, string>;
+}
+
+interface ClaudeMemPluginConfig {
+  syncMemoryFile?: boolean;
+  syncMemoryFileExclude?: string[];
+  project?: string;
+  workerPort?: number;
+  workerHost?: string;
+  observationFeed?: {
+    enabled?: boolean;
+    channel?: string;
+    to?: string;
+    botToken?: string;
+    emojis?: FeedEmojiConfig;
+  };
+}
+
+const MAX_SSE_BUFFER_SIZE = 1024 * 1024; 
+const DEFAULT_WORKER_PORT = 37777;
+const DEFAULT_WORKER_HOST = "127.0.0.1";
+
+const EMOJI_POOL = [
+  "🔧","📐","🔍","💻","🧪","🐛","🛡️","☁️","📦","🎯",
+  "🔮","⚡","🌊","🎨","📊","🚀","🔬","🏗️","📝","🎭",
+];
+
+function poolEmojiForAgent(agentId: string): string {
+  let hash = 0;
+  for (let i = 0; i < agentId.length; i++) {
+    hash = ((hash << 5) - hash + agentId.charCodeAt(i)) | 0;
+  }
+  return EMOJI_POOL[Math.abs(hash) % EMOJI_POOL.length];
+}
+
+const DEFAULT_PRIMARY_EMOJI = "🦞";
+const DEFAULT_CLAUDE_CODE_EMOJI = "⌨️";
+const DEFAULT_CLAUDE_CODE_LABEL = "Claude Code Session";
+const DEFAULT_FALLBACK_EMOJI = "🦀";
+
+function buildGetSourceLabel(
+  emojiConfig: FeedEmojiConfig | undefined
+): (project: string | null | undefined) => string {
+  const primary = emojiConfig?.primary ?? DEFAULT_PRIMARY_EMOJI;
+  const claudeCode = emojiConfig?.claudeCode ?? DEFAULT_CLAUDE_CODE_EMOJI;
+  const claudeCodeLabel = emojiConfig?.claudeCodeLabel ?? DEFAULT_CLAUDE_CODE_LABEL;
+  const fallback = emojiConfig?.default ?? DEFAULT_FALLBACK_EMOJI;
+  const pinnedAgents = emojiConfig?.agents ?? {};
+
+  return function getSourceLabel(project: string | null | undefined): string {
+    if (!project) return fallback;
+    if (project.startsWith("openclaw-")) {
+      const agentId = project.slice("openclaw-".length);
+      if (!agentId) return `${primary} openclaw`;
+      const emoji = pinnedAgents[agentId] || poolEmojiForAgent(agentId);
+      return `${emoji} ${agentId}`;
+    }
+    if (project === "openclaw") {
+      return `${primary} openclaw`;
+    }
+    const trimmedLabel = claudeCodeLabel.trim();
+    if (!trimmedLabel) {
+      return `${claudeCode} ${project}`;
+    }
+    return `${claudeCode} ${trimmedLabel} (${project})`;
+  };
+}
+
+let _workerHost = DEFAULT_WORKER_HOST;
+
+function workerBaseUrl(port: number): string {
+  return `http://${_workerHost}:${port}`;
+}
+
+const CIRCUIT_BREAKER_THRESHOLD = 3;
+const CIRCUIT_BREAKER_COOLDOWN_MS = 30_000;
+
+type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+
+let _circuitState: CircuitState = "CLOSED";
+let _circuitFailures = 0;
+let _circuitOpenedAt = 0;
+let _halfOpenProbeInFlight = false;
+
+function circuitAllow(logger: PluginLogger): boolean {
+  if (_circuitState === "CLOSED") return true;
+  if (_circuitState === "OPEN") {
+    if (Date.now() - _circuitOpenedAt >= CIRCUIT_BREAKER_COOLDOWN_MS) {
+      _circuitState = "HALF_OPEN";
+      logger.info("[claude-mem] Circuit breaker: probing worker connection");
+      if (_halfOpenProbeInFlight) return false;
+      _halfOpenProbeInFlight = true;
+      return true;
+    }
+    return false;
+  }
+  if (_halfOpenProbeInFlight) return false;
+  _halfOpenProbeInFlight = true;
+  return true;
+}
+
+function circuitOnSuccess(logger: PluginLogger): void {
+  if (_circuitState !== "CLOSED") {
+    logger.info("[claude-mem] Worker connection restored — circuit closed");
+  }
+  _circuitState = "CLOSED";
+  _circuitFailures = 0;
+  _halfOpenProbeInFlight = false;
+}
+
+function circuitOnFailure(logger: PluginLogger): void {
+  _halfOpenProbeInFlight = false;
+  _circuitFailures++;
+  if (
+    _circuitState === "HALF_OPEN" ||
+    (_circuitState === "CLOSED" && _circuitFailures >= CIRCUIT_BREAKER_THRESHOLD)
+  ) {
+    _circuitState = "OPEN";
+    _circuitOpenedAt = Date.now();
+    logger.warn(
+      `[claude-mem] Worker unreachable — disabling requests for ${CIRCUIT_BREAKER_COOLDOWN_MS / 1000}s`
+    );
+  }
+}
+
+function circuitReset(): void {
+  _circuitState = "CLOSED";
+  _circuitFailures = 0;
+  _circuitOpenedAt = 0;
+  _halfOpenProbeInFlight = false;
+}
+
+async function workerPost(
+  port: number,
+  path: string,
+  body: Record<string, unknown>,
+  logger: PluginLogger
+): Promise<Record<string, unknown> | null> {
+  if (!circuitAllow(logger)) return null;
+  try {
+    const response = await fetch(`${workerBaseUrl(port)}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+      circuitOnFailure(logger);
+      logger.warn(`[claude-mem] Worker POST ${path} returned ${response.status}`);
+      return null;
+    }
+    circuitOnSuccess(logger);
+    return (await response.json()) as Record<string, unknown>;
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    circuitOnFailure(logger);
+    if (_circuitState !== "OPEN") {
+      logger.warn(`[claude-mem] Worker POST ${path} failed: ${message}`);
+    }
+    return null;
+  }
+}
+
+function workerPostFireAndForget(
+  port: number,
+  path: string,
+  body: Record<string, unknown>,
+  logger: PluginLogger
+): void {
+  if (!circuitAllow(logger)) return;
+  fetch(`${workerBaseUrl(port)}${path}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  }).then((response) => {
+    if (!response.ok) {
+      circuitOnFailure(logger);
+      logger.warn(`[claude-mem] Worker POST ${path} returned ${response.status}`);
+      return;
+    }
+    circuitOnSuccess(logger);
+  }).catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    circuitOnFailure(logger);
+    if (_circuitState !== "OPEN") {
+      logger.warn(`[claude-mem] Worker POST ${path} failed: ${message}`);
+    }
+  });
+}
+
+async function workerGetText(
+  port: number,
+  path: string,
+  logger: PluginLogger
+): Promise<string | null> {
+  if (!circuitAllow(logger)) return null;
+  try {
+    const response = await fetch(`${workerBaseUrl(port)}${path}`);
+    if (!response.ok) {
+      circuitOnFailure(logger);
+      logger.warn(`[claude-mem] Worker GET ${path} returned ${response.status}`);
+      return null;
+    }
+    circuitOnSuccess(logger);
+    return await response.text();
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    circuitOnFailure(logger);
+    if (_circuitState !== "OPEN") {
+      logger.warn(`[claude-mem] Worker GET ${path} failed: ${message}`);
+    }
+    return null;
+  }
+}
+
+async function workerGetJson(
+  port: number,
+  path: string,
+  logger: PluginLogger
+): Promise<Record<string, unknown> | null> {
+  const text = await workerGetText(port, path, logger);
+  if (!text) return null;
+
+  try {
+    return JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    logger.warn(`[claude-mem] Worker GET ${path} returned non-JSON response`);
+    return null;
+  }
+}
+
+function formatObservationMessage(
+  observation: ObservationSSEPayload,
+  getSourceLabel: (project: string | null | undefined) => string,
+): string {
+  const title = observation.title || "Untitled";
+  const source = getSourceLabel(observation.project);
+  let message = `${source}\n**${title}**`;
+  if (observation.subtitle) {
+    message += `\n${observation.subtitle}`;
+  }
+  return message;
+}
+
+const CHANNEL_SEND_MAP: Record<string, { namespace: string; functionName: string }> = {
+  telegram: { namespace: "telegram", functionName: "sendMessageTelegram" },
+  whatsapp: { namespace: "whatsapp", functionName: "sendMessageWhatsApp" },
+  discord: { namespace: "discord", functionName: "sendMessageDiscord" },
+  slack: { namespace: "slack", functionName: "sendMessageSlack" },
+  signal: { namespace: "signal", functionName: "sendMessageSignal" },
+  imessage: { namespace: "imessage", functionName: "sendMessageIMessage" },
+  line: { namespace: "line", functionName: "sendMessageLine" },
+};
+
+async function sendDirectTelegram(
+  botToken: string,
+  chatId: string,
+  text: string,
+  logger: PluginLogger
+): Promise<void> {
+  try {
+    const response = await fetch(`https://api.telegram.org/bot${botToken}/sendMessage`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        chat_id: chatId,
+        text,
+        parse_mode: "Markdown",
+      }),
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      logger.warn(`[claude-mem] Direct Telegram send failed (${response.status}): ${body}`);
+    }
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.warn(`[claude-mem] Direct Telegram send error: ${message}`);
+  }
+}
+
+function sendToChannel(
+  api: OpenClawPluginApi,
+  channel: string,
+  to: string,
+  text: string,
+  botToken?: string
+): Promise<void> {
+  if (botToken && channel === "telegram") {
+    return sendDirectTelegram(botToken, to, text, api.logger);
+  }
+
+  const mapping = CHANNEL_SEND_MAP[channel];
+  if (!mapping) {
+    api.logger.warn(`[claude-mem] Unsupported channel type: ${channel}`);
+    return Promise.resolve();
+  }
+
+  const channelApi = api.runtime.channel[mapping.namespace];
+  if (!channelApi) {
+    api.logger.warn(`[claude-mem] Channel "${channel}" not available in runtime`);
+    return Promise.resolve();
+  }
+
+  const senderFunction = channelApi[mapping.functionName];
+  if (!senderFunction) {
+    api.logger.warn(`[claude-mem] Channel "${channel}" has no ${mapping.functionName} function`);
+    return Promise.resolve();
+  }
+
+  const args: unknown[] = channel === "whatsapp"
+    ? [to, text, { verbose: false }]
+    : [to, text];
+
+  return senderFunction(...args).catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error);
+    api.logger.error(`[claude-mem] Failed to send to ${channel}: ${message}`);
+  });
+}
+
+async function connectToSSEStream(
+  api: OpenClawPluginApi,
+  port: number,
+  channel: string,
+  to: string,
+  abortController: AbortController,
+  setConnectionState: (state: ConnectionState) => void,
+  getSourceLabel: (project: string | null | undefined) => string,
+  botToken?: string
+): Promise<void> {
+  let backoffMs = 1000;
+  const maxBackoffMs = 30000;
+
+  while (!abortController.signal.aborted) {
+    try {
+      setConnectionState("reconnecting");
+      api.logger.info(`[claude-mem] Connecting to SSE stream at ${workerBaseUrl(port)}/stream`);
+
+      const response = await fetch(`${workerBaseUrl(port)}/stream`, {
+        signal: abortController.signal,
+        headers: { Accept: "text/event-stream" },
+      });
+
+      if (!response.ok) {
+        throw new Error(`SSE stream returned HTTP ${response.status}`);
+      }
+
+      if (!response.body) {
+        throw new Error("SSE stream response has no body");
+      }
+
+      setConnectionState("connected");
+      backoffMs = 1000;
+      api.logger.info("[claude-mem] Connected to SSE stream");
+
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+
+        if (buffer.length > MAX_SSE_BUFFER_SIZE) {
+          api.logger.warn("[claude-mem] SSE buffer overflow, clearing buffer");
+          buffer = "";
+        }
+
+        const frames = buffer.split("\n\n");
+        buffer = frames.pop() || "";
+
+        for (const frame of frames) {
+          const dataLines = frame
+            .split("\n")
+            .filter((line) => line.startsWith("data:"))
+            .map((line) => line.slice(5).trim());
+          if (dataLines.length === 0) continue;
+
+          const jsonStr = dataLines.join("\n");
+          if (!jsonStr) continue;
+
+          try {
+            const parsed = JSON.parse(jsonStr);
+            if (parsed.type === "new_observation" && parsed.observation) {
+              const event = parsed as SSENewObservationEvent;
+              const message = formatObservationMessage(event.observation, getSourceLabel);
+              await sendToChannel(api, channel, to, message, botToken);
+            }
+          } catch (parseError: unknown) {
+            const errorMessage = parseError instanceof Error ? parseError.message : String(parseError);
+            api.logger.warn(`[claude-mem] Failed to parse SSE frame: ${errorMessage}`);
+          }
+        }
+      }
+    } catch (error: unknown) {
+      if (abortController.signal.aborted) {
+        break;
+      }
+      setConnectionState("reconnecting");
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      api.logger.warn(`[claude-mem] SSE stream error: ${errorMessage}. Reconnecting in ${backoffMs / 1000}s`);
+    }
+
+    if (abortController.signal.aborted) break;
+
+    await new Promise((resolve) => setTimeout(resolve, backoffMs));
+    backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
+  }
+
+  setConnectionState("disconnected");
+}
+
+export default function claudeMemPlugin(api: OpenClawPluginApi): void {
+  const userConfig = (api.pluginConfig || {}) as ClaudeMemPluginConfig;
+  const workerPort = userConfig.workerPort || DEFAULT_WORKER_PORT;
+  _workerHost = userConfig.workerHost || DEFAULT_WORKER_HOST;
+  const baseProjectName = userConfig.project || "openclaw";
+  const getSourceLabel = buildGetSourceLabel(userConfig.observationFeed?.emojis);
+
+  function getProjectName(ctx: EventContext): string {
+    if (ctx.agentId) {
+      return `openclaw-${ctx.agentId}`;
+    }
+    return baseProjectName;
+  }
+
+  const sessionIds = new Map<string, string>();
+  const canonicalSessionKeys = new Map<string, string>();
+  const sessionAliasesByCanonicalKey = new Map<string, Set<string>>();
+  const recentPromptInits = new Map<string, number>();
+  const syncMemoryFile = userConfig.syncMemoryFile !== false; 
+  const syncMemoryFileExclude = new Set(userConfig.syncMemoryFileExclude || []);
+
+  function getContentSessionId(sessionKey?: string): string {
+    const key = sessionKey || "default";
+    if (!sessionIds.has(key)) {
+      sessionIds.set(key, `openclaw-${key}-${Date.now()}`);
+    }
+    return sessionIds.get(key)!;
+  }
+
+  function shouldInjectContext(ctx?: EventContext): boolean {
+    if (!syncMemoryFile) return false;
+    const agentId = ctx?.agentId;
+    if (agentId && syncMemoryFileExclude.has(agentId)) return false;
+    return true;
+  }
+
+  type SessionTrackingContext = {
+    sessionKey?: string;
+    workspaceDir?: string;
+    channelId?: string;
+    conversationId?: string;
+  };
+
+  function getSessionAliases(ctx: SessionTrackingContext): string[] {
+    const aliases = new Set<string>();
+    for (const rawKey of [ctx.sessionKey, ctx.conversationId, ctx.channelId]) {
+      const key = typeof rawKey === "string" ? rawKey.trim() : "";
+      if (key) aliases.add(key);
+    }
+    if (aliases.size === 0) aliases.add("default");
+    return Array.from(aliases);
+  }
+
+  function rememberSessionContext(ctx: SessionTrackingContext): { canonicalKey: string; contentSessionId: string } {
+    const aliases = getSessionAliases(ctx);
+    let canonicalKey = aliases.find((alias) => canonicalSessionKeys.has(alias));
+    canonicalKey = canonicalKey ? canonicalSessionKeys.get(canonicalKey)! : aliases[0];
+    let aliasSet = sessionAliasesByCanonicalKey.get(canonicalKey);
+    if (!aliasSet) {
+      aliasSet = new Set([canonicalKey]);
+      sessionAliasesByCanonicalKey.set(canonicalKey, aliasSet);
+    }
+    for (const alias of aliases) {
+      aliasSet.add(alias);
+      canonicalSessionKeys.set(alias, canonicalKey);
+    }
+    const contentSessionId = getContentSessionId(canonicalKey);
+    for (const alias of aliasSet) {
+      sessionIds.set(alias, contentSessionId);
+    }
+    return { canonicalKey, contentSessionId };
+  }
+
+  function shouldSkipDuplicatePromptInit(contentSessionId: string, project: string, prompt: string): boolean {
+    const now = Date.now();
+    for (const [key, timestamp] of recentPromptInits) {
+      if (now - timestamp > 2000) recentPromptInits.delete(key);
+    }
+    const cacheKey = `${contentSessionId}::${project}::${prompt}`;
+    const lastSeenAt = recentPromptInits.get(cacheKey);
+    recentPromptInits.set(cacheKey, now);
+    return typeof lastSeenAt === "number" && now - lastSeenAt <= 2000;
+  }
+
+  function clearSessionContext(ctx: SessionTrackingContext): void {
+    const aliases = getSessionAliases(ctx);
+    const canonicalKey = aliases
+      .map((alias) => canonicalSessionKeys.get(alias))
+      .find(Boolean) || aliases[0];
+    const knownAliases = sessionAliasesByCanonicalKey.get(canonicalKey) || new Set([canonicalKey, ...aliases]);
+    for (const alias of knownAliases) {
+      canonicalSessionKeys.delete(alias);
+      sessionIds.delete(alias);
+    }
+    sessionAliasesByCanonicalKey.delete(canonicalKey);
+    sessionIds.delete(canonicalKey);
+  }
+
+  const CONTEXT_CACHE_TTL_MS = 60_000;
+  const contextCache = new Map<string, { text: string; fetchedAt: number }>();
+
+  async function getContextForPrompt(ctx?: EventContext): Promise<string | null> {
+    const projects = [baseProjectName];
+    const agentProject = ctx ? getProjectName(ctx) : null;
+    if (agentProject && agentProject !== baseProjectName) {
+      projects.push(agentProject);
+    }
+    const cacheKey = projects.join(",");
+
+    const cached = contextCache.get(cacheKey);
+    if (cached && Date.now() - cached.fetchedAt < CONTEXT_CACHE_TTL_MS) {
+      return cached.text;
+    }
+
+    const contextText = await workerGetText(
+      workerPort,
+      `/api/context/inject?projects=${encodeURIComponent(cacheKey)}`,
+      api.logger
+    );
+    if (contextText && contextText.trim().length > 0) {
+      const trimmed = contextText.trim();
+      contextCache.set(cacheKey, { text: trimmed, fetchedAt: Date.now() });
+      return trimmed;
+    }
+    return null;
+  }
+
+  // Centralized session-init POST. session_start, after_compaction, and
+  // before_agent_start each call this; the 2s dedup guard
+  // (shouldSkipDuplicatePromptInit) collapses the redundant inits a single
+  // user-message flow produces into one prompt record, while still ensuring a
+  // session is initialized even on flows that never reach before_agent_start.
+  async function initSessionOnce(ctx: EventContext, promptText: string, via: string): Promise<void> {
+    const { contentSessionId } = rememberSessionContext(ctx);
+    const projectName = getProjectName(ctx);
+
+    if (shouldSkipDuplicatePromptInit(contentSessionId, projectName, promptText)) {
+      api.logger.info(`[claude-mem] Skipping duplicate prompt init: contentSessionId=${contentSessionId} project=${projectName} via=${via}`);
+      return;
+    }
+
+    await workerPost(workerPort, "/api/sessions/init", {
+      contentSessionId,
+      project: projectName,
+      prompt: promptText,
+    }, api.logger);
+
+    api.logger.info(`[claude-mem] Session initialized via ${via}: contentSessionId=${contentSessionId} project=${projectName}`);
+  }
+
+  api.on("session_start", async (_event, ctx) => {
+    await initSessionOnce(ctx, "session start", "session_start");
+  });
+
+  api.on("message_received", async (event, ctx) => {
+    const { canonicalKey, contentSessionId } = rememberSessionContext(ctx);
+    api.logger.info(`[claude-mem] Message received — prompt capture deferred to before_agent_start: session=${canonicalKey} contentSessionId=${contentSessionId} hasContent=${Boolean(event.content)}`);
+  });
+
+  api.on("after_compaction", async (_event, ctx) => {
+    await initSessionOnce(ctx, "after compaction", "after_compaction");
+  });
+
+  api.on("before_agent_start", async (event, ctx) => {
+    await initSessionOnce(ctx, event.prompt || "agent run", "before_agent_start");
+  });
+
+  api.on("before_prompt_build", async (_event, ctx) => {
+    if (!shouldInjectContext(ctx)) return;
+
+    const contextText = await getContextForPrompt(ctx);
+    if (contextText) {
+      api.logger.info(`[claude-mem] Context injected via system prompt for agent=${ctx.agentId ?? "unknown"}`);
+      return { appendSystemContext: contextText };
+    }
+  });
+
+  api.on("tool_result_persist", (event, ctx) => {
+    api.logger.info(`[claude-mem] tool_result_persist fired: tool=${event.toolName ?? "unknown"} agent=${ctx.agentId ?? "none"} session=${ctx.sessionKey ?? "none"}`);
+    const toolName = event.toolName;
+    if (!toolName) return;
+
+    if (toolName.startsWith("memory_")) return;
+
+    const { canonicalKey, contentSessionId } = rememberSessionContext(ctx);
+
+    let toolResponseText = "";
+    const content = event.message?.content;
+    if (Array.isArray(content)) {
+      toolResponseText = content
+        .filter((block) => (block.type === "tool_result" || block.type === "text") && "text" in block)
+        .map((block) => String(block.text))
+        .join("\n");
+    }
+
+    const MAX_TOOL_RESPONSE_LENGTH = 1000;
+    if (toolResponseText.length > MAX_TOOL_RESPONSE_LENGTH) {
+      toolResponseText = toolResponseText.slice(0, MAX_TOOL_RESPONSE_LENGTH);
+    }
+
+    // Fall back to the process cwd when the event carries no workspaceDir, so a
+    // missing ctx field never silently drops a captured observation.
+    const workspaceDir = ctx.workspaceDir || process.cwd();
+    if (!ctx.workspaceDir) {
+      api.logger.info(`[claude-mem] tool_result_persist missing workspaceDir; using process.cwd(): session=${canonicalKey} tool=${toolName}`);
+    }
+
+    workerPostFireAndForget(workerPort, "/api/sessions/observations", {
+      contentSessionId,
+      tool_name: toolName,
+      tool_input: event.params || {},
+      tool_response: toolResponseText,
+      cwd: workspaceDir,
+    }, api.logger);
+  });
+
+  api.on("agent_end", async (event, ctx) => {
+    const { contentSessionId } = rememberSessionContext(ctx);
+
+    let lastAssistantMessage = "";
+    if (Array.isArray(event.messages)) {
+      for (let i = event.messages.length - 1; i >= 0; i--) {
+        const message = event.messages[i];
+        if (message?.role === "assistant") {
+          if (typeof message.content === "string") {
+            lastAssistantMessage = message.content;
+          } else if (Array.isArray(message.content)) {
+            lastAssistantMessage = message.content
+              .filter((block) => block.type === "text")
+              .map((block) => block.text || "")
+              .join("\n");
+          }
+          break;
+        }
+      }
+    }
+
+    await workerPost(workerPort, "/api/sessions/summarize", {
+      contentSessionId,
+      last_assistant_message: lastAssistantMessage,
+    }, api.logger);
+  });
+
+  api.on("session_end", async (_event, ctx) => {
+    clearSessionContext(ctx);
+    api.logger.info(`[claude-mem] Session tracking cleaned up`);
+  });
+
+  api.on("gateway_start", async () => {
+    circuitReset();
+    sessionIds.clear();
+    contextCache.clear();
+    recentPromptInits.clear();
+    canonicalSessionKeys.clear();
+    sessionAliasesByCanonicalKey.clear();
+    api.logger.info("[claude-mem] Gateway started — session tracking reset");
+  });
+
+  let sseAbortController: AbortController | null = null;
+  let connectionState: ConnectionState = "disconnected";
+  let connectionPromise: Promise<void> | null = null;
+
+  api.registerService({
+    id: "claude-mem-observation-feed",
+    start: async (_ctx) => {
+      if (sseAbortController) {
+        sseAbortController.abort();
+        if (connectionPromise) {
+          await connectionPromise;
+          connectionPromise = null;
+        }
+      }
+
+      const feedConfig = userConfig.observationFeed;
+
+      if (!feedConfig?.enabled) {
+        api.logger.info("[claude-mem] Observation feed disabled");
+        return;
+      }
+
+      if (!feedConfig.channel || !feedConfig.to) {
+        api.logger.warn("[claude-mem] Observation feed misconfigured — channel or target missing");
+        return;
+      }
+
+      api.logger.info(`[claude-mem] Observation feed starting — channel: ${feedConfig.channel}, target: ${feedConfig.to}`);
+
+      sseAbortController = new AbortController();
+      connectionPromise = connectToSSEStream(
+        api,
+        workerPort,
+        feedConfig.channel,
+        feedConfig.to,
+        sseAbortController,
+        (state) => { connectionState = state; },
+        getSourceLabel,
+        feedConfig.botToken
+      );
+    },
+    stop: async (_ctx) => {
+      if (sseAbortController) {
+        sseAbortController.abort();
+        sseAbortController = null;
+      }
+      if (connectionPromise) {
+        await connectionPromise;
+        connectionPromise = null;
+      }
+      connectionState = "disconnected";
+      api.logger.info("[claude-mem] Observation feed stopped — SSE connection closed");
+    },
+  });
+
+  function summarizeSearchResults(items: unknown[], limit = 5): string {
+    if (!Array.isArray(items) || items.length === 0) {
+      return "No results found.";
+    }
+
+    return items
+      .slice(0, limit)
+      .map((item, index) => {
+        const row = item as Record<string, unknown>;
+        const title = String(row.title || row.subtitle || row.text || "Untitled");
+        const project = row.project ? ` [${String(row.project)}]` : "";
+        return `${index + 1}. ${title}${project}`;
+      })
+      .join("\n");
+  }
+
+  function parseLimit(arg: string | undefined, fallback = 10): number {
+    const parsed = Number(arg);
+    if (!Number.isFinite(parsed)) return fallback;
+    return Math.max(1, Math.min(50, Math.trunc(parsed)));
+  }
+
+  api.registerCommand({
+    name: "claude_mem_feed",
+    description: "Show or toggle Claude-Mem observation feed status",
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      const feedConfig = userConfig.observationFeed;
+
+      if (!feedConfig) {
+        return { text: "Observation feed not configured. Add observationFeed to your plugin config." };
+      }
+
+      const arg = ctx.args?.trim();
+
+      if (arg === "on") {
+        api.logger.info("[claude-mem] Feed enable requested via command");
+        return { text: "Feed enable requested. Update observationFeed.enabled in your plugin config to persist." };
+      }
+
+      if (arg === "off") {
+        api.logger.info("[claude-mem] Feed disable requested via command");
+        return { text: "Feed disable requested. Update observationFeed.enabled in your plugin config to persist." };
+      }
+
+      return { text: [
+        "Claude-Mem Observation Feed",
+        `Enabled: ${feedConfig.enabled ? "yes" : "no"}`,
+        `Channel: ${feedConfig.channel || "not set"}`,
+        `Target: ${feedConfig.to || "not set"}`,
+        `Connection: ${connectionState}`,
+      ].join("\n") };
+    },
+  });
+
+  api.registerCommand({
+    name: "claude-mem-search",
+    description: "Search Claude-Mem observations by query",
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      const raw = ctx.args?.trim() || "";
+      if (!raw) {
+        return "Usage: /claude-mem-search <query> [limit]";
+      }
+
+      const pieces = raw.split(/\s+/);
+      const maybeLimit = pieces[pieces.length - 1];
+      const hasTrailingLimit = /^\d+$/.test(maybeLimit);
+      const limit = hasTrailingLimit ? parseLimit(maybeLimit, 10) : 10;
+      const query = hasTrailingLimit ? pieces.slice(0, -1).join(" ") : raw;
+
+      const data = await workerGetJson(
+        workerPort,
+        `/api/search/observations?query=${encodeURIComponent(query)}&limit=${limit}`,
+        api.logger,
+      );
+
+      if (!data) {
+        return "Claude-Mem search failed (worker unavailable or invalid response).";
+      }
+
+      const items = Array.isArray(data.items) ? data.items : [];
+      return [
+        `Claude-Mem Search: \"${query}\"`,
+        summarizeSearchResults(items, limit),
+      ].join("\n");
+    },
+  });
+
+  api.registerCommand({
+    name: "claude-mem-recent",
+    description: "Show recent Claude-Mem context for a project",
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      const raw = ctx.args?.trim() || "";
+      const parts = raw ? raw.split(/\s+/) : [];
+      const maybeLimit = parts.length > 0 ? parts[parts.length - 1] : "";
+      const hasTrailingLimit = /^\d+$/.test(maybeLimit);
+      const limit = hasTrailingLimit ? parseLimit(maybeLimit, 3) : 3;
+      const project = hasTrailingLimit ? parts.slice(0, -1).join(" ") : raw;
+
+      const params = new URLSearchParams();
+      params.set("limit", String(limit));
+      if (project) params.set("project", project);
+
+      const data = await workerGetJson(
+        workerPort,
+        `/api/context/recent?${params.toString()}`,
+        api.logger,
+      );
+
+      if (!data) {
+        return "Claude-Mem recent context failed (worker unavailable or invalid response).";
+      }
+
+      const summaries = Array.isArray(data.session_summaries) ? data.session_summaries : [];
+      const observations = Array.isArray(data.recent_observations) ? data.recent_observations : [];
+
+      return [
+        "Claude-Mem Recent Context",
+        `Project: ${project || "(auto)"}`,
+        `Session summaries: ${summaries.length}`,
+        `Recent observations: ${observations.length}`,
+        summarizeSearchResults(observations, Math.min(5, observations.length || 5)),
+      ].join("\n");
+    },
+  });
+
+  api.registerCommand({
+    name: "claude-mem-timeline",
+    description: "Find best memory match and show nearby timeline events",
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      const raw = ctx.args?.trim() || "";
+      if (!raw) {
+        return "Usage: /claude-mem-timeline <query> [depthBefore] [depthAfter]";
+      }
+
+      const parts = raw.split(/\s+/);
+      let depthAfter = 5;
+      let depthBefore = 5;
+
+      if (parts.length >= 2 && /^\d+$/.test(parts[parts.length - 1])) {
+        depthAfter = parseLimit(parts.pop(), 5);
+      }
+      if (parts.length >= 2 && /^\d+$/.test(parts[parts.length - 1])) {
+        depthBefore = parseLimit(parts.pop(), 5);
+      }
+
+      const query = parts.join(" ");
+      const params = new URLSearchParams({
+        query,
+        mode: "auto",
+        depth_before: String(depthBefore),
+        depth_after: String(depthAfter),
+      });
+
+      const data = await workerGetJson(
+        workerPort,
+        `/api/timeline/by-query?${params.toString()}`,
+        api.logger,
+      );
+
+      if (!data) {
+        return "Claude-Mem timeline lookup failed (worker unavailable or invalid response).";
+      }
+
+      const timeline = Array.isArray(data.timeline) ? data.timeline : [];
+      const anchor = data.anchor ? String(data.anchor) : "(none)";
+
+      return [
+        `Claude-Mem Timeline: \"${query}\"`,
+        `Anchor: ${anchor}`,
+        summarizeSearchResults(timeline, 8),
+      ].join("\n");
+    },
+  });
+
+  api.registerCommand({
+    name: "claude_mem_status",
+    description: "Check Claude-Mem worker health and session status",
+    handler: async () => {
+      const healthText = await workerGetText(workerPort, "/api/health", api.logger);
+      if (!healthText) {
+        return { text: `Claude-Mem worker unreachable at port ${workerPort}` };
+      }
+
+      try {
+        const health = JSON.parse(healthText);
+        return { text: [
+          "Claude-Mem Worker Status",
+          `Status: ${health.status || "unknown"}`,
+          `Port: ${workerPort}`,
+          `Active sessions: ${sessionIds.size}`,
+          `Observation feed: ${connectionState}`,
+        ].join("\n") };
+      } catch {
+        return { text: `Claude-Mem worker responded but returned unexpected data` };
+      }
+    },
+  });
+
+  api.logger.info(`[claude-mem] OpenClaw plugin loaded — v1.0.0 (worker: ${_workerHost}:${workerPort})`);
+}