@parkgogogo/openclaw-reflection 0.1.5 → 0.1.6

package/README.md

@@ -1,4 +1,4 @@
-# OpenClaw Reflection
+<h1 align="center">OpenClaw Reflection</h1>
 
 <p align="center">
   <img src="./assets/openclaw-reflection-logo.png" alt="OpenClaw Reflection logo" width="180" />
@@ -6,12 +6,14 @@
 
 <p align="center"><strong>Make OpenClaw's native memory system sharper without replacing it.</strong></p>
 
-![OpenClaw Plugin](https://img.shields.io/badge/OpenClaw-Plugin-111111?style=flat-square)
-![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6?style=flat-square)
-![memory_gate 18 cases](https://img.shields.io/badge/memory_gate-18%20benchmark%20cases-2ea043?style=flat-square)
-![write_guardian 14 cases](https://img.shields.io/badge/write_guardian-14%20benchmark%20cases-2ea043?style=flat-square)
+<p align="center">
+  <img alt="OpenClaw Plugin" src="https://img.shields.io/badge/OpenClaw-Plugin-111111?style=flat-square" />
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.x-3178c6?style=flat-square" />
+  <img alt="memory_gate 18 cases" src="https://img.shields.io/badge/memory_gate-18%20benchmark%20cases-2ea043?style=flat-square" />
+  <img alt="write_guardian 14 cases" src="https://img.shields.io/badge/write_guardian-14%20benchmark%20cases-2ea043?style=flat-square" />
+</p>
 
-Chinese version: [README.zh-CN.md](./README.zh-CN.md)
+<p align="center"><a href="./README.zh-CN.md">中文文档</a></p>
 
 OpenClaw Reflection is an additive layer on top of OpenClaw's built-in Markdown memory system. It captures message flow, keeps thread noise out of long-term memory, writes durable knowledge into the same human-readable memory files OpenClaw already uses, and periodically consolidates them so your agent gets sharper over time instead of messier.
 
@@ -112,6 +114,7 @@ Once the gateway restarts, Reflection will begin listening to `message_received`
 - Reflection now writes an independent write_guardian audit log to:
   - `<workspaceDir>/.openclaw-reflection/write-guardian.log.jsonl`
 - When `logLevel` is `debug`, Reflection also overwrites `logs/debug.json` with the latest raw `message_received` callback payload.
+- When `write_guardian` successfully writes durable memory, Reflection reacts to the triggering user message with `📝`.
 - Register command: `reflections`
   - Returns the most recent 10 write_guardian behaviors (written/refused/failed/skipped), including decision, target file, and reason.
 

package/README.zh-CN.md

@@ -1,4 +1,4 @@
-# OpenClaw Reflection
+<h1 align="center">OpenClaw Reflection</h1>
 
 <p align="center">
   <img src="./assets/openclaw-reflection-logo.png" alt="OpenClaw Reflection logo" width="180" />
@@ -8,10 +8,12 @@
 
 英文版： [README.md](./README.md)
 
-![OpenClaw Plugin](https://img.shields.io/badge/OpenClaw-Plugin-111111?style=flat-square)
-![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6?style=flat-square)
-![memory_gate 18 cases](https://img.shields.io/badge/memory_gate-18%20benchmark%20cases-2ea043?style=flat-square)
-![write_guardian 14 cases](https://img.shields.io/badge/write_guardian-14%20benchmark%20cases-2ea043?style=flat-square)
+<p align="center">
+  <img alt="OpenClaw Plugin" src="https://img.shields.io/badge/OpenClaw-Plugin-111111?style=flat-square" />
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.x-3178c6?style=flat-square" />
+  <img alt="memory_gate 18 cases" src="https://img.shields.io/badge/memory_gate-18%20benchmark%20cases-2ea043?style=flat-square" />
+  <img alt="write_guardian 14 cases" src="https://img.shields.io/badge/write_guardian-14%20benchmark%20cases-2ea043?style=flat-square" />
+</p>
 
 OpenClaw Reflection 是叠加在 OpenClaw 原生 Markdown memory 之上的一层增强插件。它负责监听消息流，过滤线程噪音，把真正长期有效的信息写回 OpenClaw 的核心记忆文件，并定期整理这些文件，避免长期使用后越记越乱。
 
@@ -107,6 +109,7 @@ Gateway 重启后，Reflection 就会开始监听 `message_received` 和 `before
 - Reflection 现在会给 write_guardian 单独写一份审计日志：
   - `<workspaceDir>/.openclaw-reflection/write-guardian.log.jsonl`
 - 当 `logLevel` 为 `debug` 时，Reflection 还会把最近一次 `message_received` callback 的原始 payload 覆盖写入 `logs/debug.json`。
+- 当 `write_guardian` 成功写入长期记忆时，Reflection 会给触发这次写入的用户消息补一个 `📝` reaction。
 - 注册命令：`reflections`
   - 返回最近 10 条 write_guardian 行为（written/refused/failed/skipped），包含 decision、目标文件和原因。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parkgogogo/openclaw-reflection",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "OpenClaw plugin that enhances native Markdown memory with filtering, curation, and consolidation",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -20,6 +20,7 @@ import {
   handleBeforeMessageWrite,
   handleMessageReceived,
 } from "./message-handler.js";
+import { OpenClawMessageReactionService } from "./message-reaction.js";
 import { SessionBufferManager } from "./session-manager.js";
 import type {
   LLMService,
@@ -275,6 +276,7 @@ export default function activate(api: PluginAPI): void {
     let memoryGate: MemoryGateAnalyzer | undefined;
     let writeGuardian: WriteGuardian | undefined;
     let writeGuardianAuditLog: WriteGuardianAuditLog | undefined;
+    const reactionService = new OpenClawMessageReactionService(logger);
 
     if (config.memoryGate.enabled && llmService) {
       memoryGate = new MemoryGateAnalyzer(llmService, logger);
@@ -342,7 +344,8 @@ export default function activate(api: PluginAPI): void {
               context,
               memoryGate,
               writeGuardian,
-              config.memoryGate.windowSize
+              config.memoryGate.windowSize,
+              reactionService
             );
           } else {
             logger.warn("PluginLifecycle", "Callback skipped: buffer manager missing", {

package/src/message-handler.ts

@@ -1,5 +1,12 @@
 import type { SessionBufferManager } from "./session-manager.js";
-import type { Logger, ReflectionMessage } from "./types.js";
+import type {
+  Logger,
+  MessageHookContext,
+  MessageReactionInput,
+  MessageReactionService,
+  MessageReceivedHookEvent,
+  ReflectionMessage,
+} from "./types.js";
 import { MemoryGateAnalyzer, type MemoryGateOutput } from "./memory-gate/index.js";
 import { WriteGuardian } from "./write-guardian/index.js";
 import { ulid } from "ulid";
@@ -26,19 +33,6 @@ interface MessageEvent {
   channelId?: string;
 }
 
-interface MessageHookContext {
-  channelId?: string;
-  accountId?: string;
-  conversationId?: string;
-}
-
-interface MessageReceivedHookEvent {
-  from?: string;
-  content?: string;
-  timestamp?: number;
-  metadata?: Record<string, unknown>;
-}
-
 interface BeforeMessageWriteEvent {
   message?: {
     role?: string;
@@ -480,6 +474,7 @@ function createReflectionMessage(
     messageId: event.message?.id,
     from: event.from,
     to: event.to,
+    accountId: event.accountId,
     success: event.success,
   };
 
@@ -507,6 +502,80 @@ function findLatestMessageByRole(
   return "";
 }
 
+function findLatestUserReactionTarget(
+  messages: ReflectionMessage[]
+): MessageReactionInput | null {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message.role !== "user") {
+      continue;
+    }
+
+    const messageId = getNonEmptyString(message.metadata?.messageId);
+    const target = getNonEmptyString(message.metadata?.to);
+    const channelId = getNonEmptyString(message.channelId);
+
+    if (!messageId || !target || !channelId) {
+      continue;
+    }
+
+    return {
+      channelId,
+      accountId: getNonEmptyString(message.metadata?.accountId),
+      target,
+      messageId,
+      emoji: "📝",
+    };
+  }
+
+  return null;
+}
+
+function isReactionService(
+  value: unknown
+): value is MessageReactionService {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "reactToMessage" in value &&
+    typeof (value as { reactToMessage?: unknown }).reactToMessage === "function"
+  );
+}
+
+function resolveHandlerOptions(
+  memoryGateWindowSizeOrReactionService: number | MessageReactionService | undefined,
+  reactionServiceOrWindowSize: MessageReactionService | number | undefined
+): {
+  memoryGateWindowSize: number;
+  reactionService?: MessageReactionService;
+} {
+  const defaultOptions = {
+    memoryGateWindowSize: DEFAULT_MEMORY_GATE_WINDOW_SIZE,
+    reactionService: undefined,
+  } as const;
+
+  if (typeof memoryGateWindowSizeOrReactionService === "number") {
+    return {
+      memoryGateWindowSize: memoryGateWindowSizeOrReactionService,
+      reactionService: isReactionService(reactionServiceOrWindowSize)
+        ? reactionServiceOrWindowSize
+        : undefined,
+    };
+  }
+
+  if (isReactionService(memoryGateWindowSizeOrReactionService)) {
+    return {
+      memoryGateWindowSize:
+        typeof reactionServiceOrWindowSize === "number"
+          ? reactionServiceOrWindowSize
+          : DEFAULT_MEMORY_GATE_WINDOW_SIZE,
+      reactionService: memoryGateWindowSizeOrReactionService,
+    };
+  }
+
+  return defaultOptions;
+}
+
 function isUpdateDecision(
   decision: MemoryGateOutput["decision"]
 ): decision is
@@ -530,7 +599,8 @@ async function triggerMemoryGate(
   memoryGate: MemoryGateAnalyzer,
   writeGuardian: WriteGuardian | undefined,
   logger: Logger,
-  memoryGateWindowSize: number
+  memoryGateWindowSize: number,
+  reactionService?: MessageReactionService
 ): Promise<void> {
   const normalizedWindowSize = Number.isInteger(memoryGateWindowSize)
     ? Math.max(memoryGateWindowSize, 1)
@@ -578,6 +648,11 @@ async function triggerMemoryGate(
             },
             sessionKey
           );
+
+          const reactionTarget = findLatestUserReactionTarget(sessionMessages);
+          if (reactionService && reactionTarget) {
+            await reactionService.reactToMessage(reactionTarget);
+          }
         } else if (writeResult.status === "refused") {
           logger.info(
             "MessageHandler",
@@ -698,8 +773,14 @@ function handleAgentMessage(
   hookContext?: unknown,
   memoryGate?: MemoryGateAnalyzer,
   writeGuardian?: WriteGuardian,
-  memoryGateWindowSize = DEFAULT_MEMORY_GATE_WINDOW_SIZE
+  memoryGateWindowSizeOrReactionService?: number | MessageReactionService,
+  reactionServiceOrWindowSize?: MessageReactionService | number
 ): void {
+  const { memoryGateWindowSize, reactionService } = resolveHandlerOptions(
+    memoryGateWindowSizeOrReactionService,
+    reactionServiceOrWindowSize
+  );
+
   const normalizedEvent = normalizeSentEvent(event, hookContext);
   logHookPayloadDebug(
     logger,
@@ -773,7 +854,8 @@ function handleAgentMessage(
         memoryGate,
         writeGuardian,
         logger,
-        memoryGateWindowSize
+        memoryGateWindowSize,
+        reactionService
       )
     );
   }
@@ -786,7 +868,8 @@ export function handleMessageSent(
   hookContext?: unknown,
   memoryGate?: MemoryGateAnalyzer,
   writeGuardian?: WriteGuardian,
-  memoryGateWindowSize = DEFAULT_MEMORY_GATE_WINDOW_SIZE
+  memoryGateWindowSizeOrReactionService?: number | MessageReactionService,
+  reactionServiceOrWindowSize?: MessageReactionService | number
 ): void {
   handleAgentMessage(
     event,
@@ -796,7 +879,8 @@ export function handleMessageSent(
     hookContext,
     memoryGate,
     writeGuardian,
-    memoryGateWindowSize
+    memoryGateWindowSizeOrReactionService,
+    reactionServiceOrWindowSize
   );
 }
 
@@ -807,7 +891,8 @@ export function handleBeforeMessageWrite(
   hookContext?: unknown,
   memoryGate?: MemoryGateAnalyzer,
   writeGuardian?: WriteGuardian,
-  memoryGateWindowSize = DEFAULT_MEMORY_GATE_WINDOW_SIZE
+  memoryGateWindowSizeOrReactionService?: number | MessageReactionService,
+  reactionServiceOrWindowSize?: MessageReactionService | number
 ): void {
   const normalizedEvent = normalizeBeforeMessageWriteEvent(event, hookContext);
   logHookPayloadDebug(
@@ -834,7 +919,8 @@ export function handleBeforeMessageWrite(
     hookContext,
     memoryGate,
     writeGuardian,
-    memoryGateWindowSize
+    memoryGateWindowSizeOrReactionService,
+    reactionServiceOrWindowSize
   );
 }
 

package/src/message-reaction.ts

@@ -0,0 +1,96 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { Logger, MessageReactionInput, MessageReactionService } from "./types.js";
+
+const execFileAsync = promisify(execFile);
+
+type CommandRunner = (command: string, args: string[]) => Promise<void>;
+
+async function defaultCommandRunner(command: string, args: string[]): Promise<void> {
+  await execFileAsync(command, args);
+}
+
+function getNonEmptyString(value: string | undefined): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}
+
+export class OpenClawMessageReactionService implements MessageReactionService {
+  private readonly logger: Logger;
+  private readonly commandRunner: CommandRunner;
+
+  constructor(
+    logger: Logger,
+    commandRunner: CommandRunner = defaultCommandRunner
+  ) {
+    this.logger = logger;
+    this.commandRunner = commandRunner;
+  }
+
+  async reactToMessage(input: MessageReactionInput): Promise<boolean> {
+    const channelId = getNonEmptyString(input.channelId);
+    const accountId = getNonEmptyString(input.accountId);
+    const target = getNonEmptyString(input.target);
+    const messageId = getNonEmptyString(input.messageId);
+    const emoji = getNonEmptyString(input.emoji);
+
+    if (!channelId || !target || !messageId || !emoji) {
+      this.logger.warn("MessageReaction", "Skipped reaction with incomplete target", {
+        channelId,
+        accountId,
+        target,
+        messageId,
+        emoji,
+      });
+      return false;
+    }
+
+    const args = [
+      "message",
+      "react",
+      "--channel",
+      channelId,
+      ...(accountId ? ["--account", accountId] : []),
+      "--target",
+      target,
+      "--message-id",
+      messageId,
+      "--emoji",
+      emoji,
+    ];
+
+    try {
+      await this.commandRunner("openclaw", args);
+      this.logger.info("MessageReaction", "Applied reaction to message", {
+        channelId,
+        accountId,
+        target,
+        messageId,
+        emoji,
+      });
+      return true;
+    } catch (error) {
+      this.logger.warn("MessageReaction", "Failed to apply reaction to message", {
+        channelId,
+        accountId,
+        target,
+        messageId,
+        emoji,
+        reason: getErrorMessage(error),
+      });
+      return false;
+    }
+  }
+}

package/src/types.ts

@@ -38,10 +38,49 @@ export interface ReflectionMessage {
     from?: string;
     to?: string;
     messageId?: string;
+    accountId?: string;
     success?: boolean;
   };
 }
 
+export interface MessageHookContext {
+  channelId?: string;
+  accountId?: string;
+  conversationId?: string;
+}
+
+export interface MessageReceivedHookMetadata {
+  to?: string;
+  provider?: string;
+  surface?: string;
+  originatingChannel?: string;
+  originatingTo?: string;
+  messageId?: string;
+  senderId?: string;
+  senderName?: string;
+  senderUsername?: string;
+  guildId?: string;
+}
+
+export interface MessageReceivedHookEvent {
+  from?: string;
+  content?: string;
+  timestamp?: number;
+  metadata?: MessageReceivedHookMetadata;
+}
+
+export interface MessageReactionInput {
+  channelId: string;
+  target: string;
+  messageId: string;
+  emoji: string;
+  accountId?: string;
+}
+
+export interface MessageReactionService {
+  reactToMessage(input: MessageReactionInput): Promise<boolean>;
+}
+
 export interface LogEntry {
   timestamp: string;
   level: LogLevel;