@parkgogogo/openclaw-reflection 0.1.0

package/src/memory-gate/analyzer.ts

@@ -0,0 +1,191 @@
+import type { JsonSchema, LLMService, Logger } from "../types.js";
+import { MEMORY_GATE_SYSTEM_PROMPT } from "./prompt.js";
+import type {
+  MemoryDecision,
+  MemoryGateInput,
+  MemoryGateOutput,
+} from "./types.js";
+
+const VALID_DECISIONS: ReadonlySet<MemoryDecision> = new Set([
+  "NO_WRITE",
+  "UPDATE_MEMORY",
+  "UPDATE_USER",
+  "UPDATE_SOUL",
+  "UPDATE_IDENTITY",
+  "UPDATE_TOOLS",
+]);
+
+function getNonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}
+
+const MEMORY_GATE_RESPONSE_SCHEMA: JsonSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["decision", "reason"],
+  properties: {
+    decision: {
+      type: "string",
+      enum: [
+        "NO_WRITE",
+        "UPDATE_MEMORY",
+        "UPDATE_USER",
+        "UPDATE_SOUL",
+        "UPDATE_IDENTITY",
+        "UPDATE_TOOLS",
+      ],
+    },
+    reason: { type: "string" },
+    candidate_fact: { type: "string" },
+  },
+};
+
+export class MemoryGateAnalyzer {
+  private llmService: LLMService;
+  private logger: Logger;
+
+  constructor(llmService: LLMService, logger: Logger) {
+    this.llmService = llmService;
+    this.logger = logger;
+  }
+
+  async analyze(input: MemoryGateInput): Promise<MemoryGateOutput> {
+    const prompt = this.buildPrompt(input);
+
+    this.logger.debug("MemoryGateAnalyzer", "Starting memory gate analysis", {
+      recentMessages: input.recentMessages.length,
+      hasCurrentUserMessage: input.currentUserMessage.trim() !== "",
+      hasCurrentAgentReply: input.currentAgentReply.trim() !== "",
+    });
+
+    let response: {
+      decision: MemoryDecision;
+      reason: string;
+      candidate_fact?: string;
+    };
+
+    try {
+      response = await this.llmService.generateObject({
+        systemPrompt: MEMORY_GATE_SYSTEM_PROMPT,
+        userPrompt: prompt,
+        schema: MEMORY_GATE_RESPONSE_SCHEMA,
+      });
+    } catch (error) {
+      const reason = `LLM request failed: ${getErrorMessage(error)}`;
+      this.logger.error("MemoryGateAnalyzer", "Memory gate LLM request failed", {
+        reason,
+      });
+      return {
+        decision: "NO_WRITE",
+        reason,
+      };
+    }
+
+    const output = this.normalizeOutput(response);
+
+    this.logger.info("MemoryGateAnalyzer", "Memory gate decision generated", {
+      decision: output.decision,
+      reason: output.reason,
+      hasCandidateFact: Boolean(output.candidateFact),
+    });
+
+    return output;
+  }
+
+  buildPrompt(input: MemoryGateInput): string {
+    const recentMessagesBlock =
+      input.recentMessages.length === 0
+        ? "(none)"
+        : input.recentMessages
+            .map((item, index) => {
+              const isoTimestamp = new Date(item.timestamp).toISOString();
+              return `${index + 1}. [${isoTimestamp}] ${item.role}: ${item.message}`;
+            })
+            .join("\n");
+
+    return [
+      "Evaluate whether this turn should update memory files.",
+      "Use the current benchmark rules exactly.",
+      "",
+      "Recent messages (oldest to newest):",
+      recentMessagesBlock,
+      "",
+      "Current user message:",
+      input.currentUserMessage,
+      "",
+      "Current agent reply:",
+      input.currentAgentReply,
+      "",
+      "Checklist before deciding:",
+      "- Is this about the user's stable language, collaboration preference, workflow preference, cadence preference, or enduring style preference? If yes, prefer UPDATE_USER.",
+      "- Is this durable shared context, a durable lesson learned, important private context, or a past attempt whose outcome should be remembered, and does not fit USER/SOUL/IDENTITY? If yes, prefer UPDATE_MEMORY.",
+      "- If a past approach failed and the outcome should be remembered, prefer UPDATE_MEMORY even if the user says not to recommend it again.",
+      "- Is this about the assistant's enduring behavioral principle, voice, or boundary across future turns? If yes, prefer UPDATE_SOUL.",
+      "- Direct / non-sycophantic / engineering-focused as the assistant's general manner should prefer UPDATE_SOUL over UPDATE_USER.",
+      "- If the content defines the assistant's general voice, prefer UPDATE_SOUL even if the user would personally like that style too.",
+      "- If it is a general rule for how the assistant should behave, prefer UPDATE_SOUL.",
+      "- If it is mainly about this user's personal working preference, prefer UPDATE_USER.",
+      "- Is this about identity metadata such as name, vibe, or avatar? If yes, prefer UPDATE_IDENTITY.",
+      "- Is this about local tool names, aliases, endpoints, preferred voices, device nicknames, camera names, room names, or environment-specific tool mappings? If yes, prefer UPDATE_TOOLS.",
+      "- If it is a reusable procedure for how to use a tool across environments, or a claim about runtime tool availability, do not use UPDATE_TOOLS.",
+      "- Is this a project fact, architecture decision, active thread, next step, topic update, small talk, temporary emotion, or one-off tactic? If yes, choose NO_WRITE.",
+      "",
+      "For non-NO_WRITE decisions, write candidate_fact as a short canonical English sentence.",
+      'Prefer concise canonical phrasing like "prefers ...", "prefers important check-ins in the morning", "X refers to ...", "Maintain ...", "Name is ...", or "home-server SSH alias refers to devbox.internal".',
+      'For morning cadence cases, prefer exactly "prefers important check-ins in the morning".',
+      "",
+      "Return JSON only as specified in the system prompt.",
+    ].join("\n");
+  }
+
+  private normalizeOutput(parsed: {
+    decision: MemoryDecision;
+    reason: string;
+    candidate_fact?: string;
+  }): MemoryGateOutput {
+    const decision = parsed.decision;
+    if (!VALID_DECISIONS.has(decision)) {
+      return {
+        decision: "NO_WRITE",
+        reason: "Invalid decision returned by memory gate",
+      };
+    }
+
+    const reason = getNonEmptyString(parsed.reason) ?? "No reason provided";
+    const candidateFact = getNonEmptyString(parsed.candidate_fact);
+    const normalizedDecision = decision;
+
+    if (normalizedDecision !== "NO_WRITE" && !candidateFact) {
+      return {
+        decision: "NO_WRITE",
+        reason: "Missing candidate_fact for non-NO_WRITE decision",
+      };
+    }
+
+    if (candidateFact) {
+      return {
+        decision: normalizedDecision,
+        reason,
+        candidateFact,
+      };
+    }
+
+    return {
+      decision: normalizedDecision,
+      reason,
+    };
+  }
+}

package/src/memory-gate/index.ts

@@ -0,0 +1,7 @@
+export { MemoryGateAnalyzer } from "./analyzer.js";
+export { MEMORY_GATE_SYSTEM_PROMPT } from "./prompt.js";
+export type {
+  MemoryDecision,
+  MemoryGateInput,
+  MemoryGateOutput,
+} from "./types.js";

package/src/memory-gate/prompt.ts

@@ -0,0 +1,85 @@
+export const MEMORY_GATE_SYSTEM_PROMPT = `You are the assistant's Memory Gate.
+
+After each turn, output exactly one decision:
+- NO_WRITE
+- UPDATE_MEMORY
+- UPDATE_USER
+- UPDATE_SOUL
+- UPDATE_IDENTITY
+- UPDATE_TOOLS
+
+Current mode:
+- Most turns should be NO_WRITE.
+- Project facts, architecture decisions, active threads, next steps, and topic updates should be NO_WRITE.
+- Small talk, temporary emotions, and one-off tactical instructions should be NO_WRITE.
+
+Use UPDATE_USER for the user's stable preference or trait:
+- language
+- collaboration preference
+- workflow preference
+- personal cadence preference
+- enduring response style preference
+
+If it is mainly about this user's personal working preference, choose UPDATE_USER.
+Direct code review style for this user belongs to UPDATE_USER.
+For cadence-style user preferences, prefer forms like "prefers important check-ins in the morning".
+Do not add extra qualifiers if a simpler cadence sentence works.
+
+Use UPDATE_MEMORY for durable context that should be remembered but is not mainly a user preference, assistant principle, or identity metadata:
+- durable shared context or term mapping
+- durable lesson learned
+- important private context that helps future understanding
+- a past attempt or previous experience whose outcome should be remembered
+- if a past approach failed and that outcome should be remembered, prefer UPDATE_MEMORY even if the user phrases it as "don't recommend this again"
+- use forms like:
+  - "X refers to ..."
+  - "Previous ... became ..."
+  - "User may ..."
+
+Use UPDATE_SOUL only for the assistant's enduring behavioral principle, voice, or boundary across many future turns, even if proposed by the user.
+- If the statement says how the assistant/guardian should behave in general, choose UPDATE_SOUL.
+- Style instructions about the assistant's general manner belong to UPDATE_SOUL.
+- If it is a general rule for how the assistant should behave, choose UPDATE_SOUL.
+- Direct / non-sycophantic / engineering-focused as a general manner belongs to UPDATE_SOUL.
+- If the content defines the assistant's general voice, choose UPDATE_SOUL even if the user would personally like that style too.
+- Memory update policy or write policy belongs to UPDATE_SOUL.
+- If the statement says what the user personally prefers to receive, choose UPDATE_USER.
+
+Use UPDATE_IDENTITY only for identity metadata:
+- name
+- vibe
+- avatar
+
+Use UPDATE_TOOLS only for local tool-specific environment context:
+- local tool names or aliases
+- SSH hosts and aliases
+- preferred TTS voices
+- device nicknames
+- camera or room names
+- local endpoint or mapping notes that help use tools in this environment
+
+Do not use UPDATE_TOOLS for:
+- reusable procedures that should live in a skill
+- general instructions for how a tool works across environments
+- claims about runtime tool availability or what tools exist
+- project facts, user traits, identity metadata, or general long-term memory
+
+For non-NO_WRITE:
+- candidate_fact is required
+- candidate_fact must be a short canonical English sentence
+- use forms like:
+  - UPDATE_USER: "prefers ...", "dislikes ..."
+  - UPDATE_MEMORY: "X refers to ...", "Previous ...", "User may ..."
+  - UPDATE_SOUL: "Maintain ...", "When uncertain ..."
+  - UPDATE_IDENTITY: "Name is ...", "Avatar/style is ...", "Vibe is ..."
+  - UPDATE_TOOLS: "home-server SSH alias refers to ...", "Preferred TTS voice is ..."
+- avoid "User ..."
+- avoid converting "this time" or "this reply" into a stable preference
+- if identity metadata changes only the vibe, still use the form "Avatar/style is ..."
+
+Output JSON only:
+{
+  "decision": "NO_WRITE" | "UPDATE_MEMORY" | "UPDATE_USER" | "UPDATE_SOUL" | "UPDATE_IDENTITY" | "UPDATE_TOOLS",
+  "reason": "brief explanation",
+  "candidate_fact": "candidate fact or patch direction (required for non-NO_WRITE)"
+}`;

package/src/memory-gate/types.ts

@@ -0,0 +1,23 @@
+export type MemoryDecision =
+  | "NO_WRITE"
+  | "UPDATE_MEMORY"
+  | "UPDATE_USER"
+  | "UPDATE_SOUL"
+  | "UPDATE_IDENTITY"
+  | "UPDATE_TOOLS";
+
+export interface MemoryGateOutput {
+  decision: MemoryDecision;
+  reason: string;
+  candidateFact?: string;
+}
+
+export interface MemoryGateInput {
+  recentMessages: Array<{
+    role: "user" | "agent";
+    message: string;
+    timestamp: number;
+  }>;
+  currentUserMessage: string;
+  currentAgentReply: string;
+}