memory-braid 0.5.0 → 0.6.1

package/README.md

@@ -488,7 +488,17 @@ Use this preset when:
     "memory-braid": {
       "recall": {
         "maxResults": 8,
-        "injectTopK": 5,
+        "injectTopK": 4,
+        "user": {
+          "enabled": true,
+          "injectTopK": 4
+        },
+        "agent": {
+          "enabled": true,
+          "injectTopK": 2,
+          "minScore": 0.78,
+          "onlyPlanning": true
+        },
         "merge": {
           "rrfK": 60,
           "localWeight": 1,
@@ -500,6 +510,16 @@ Use this preset when:
         "mode": "hybrid",
         "includeAssistant": false,
         "maxItemsPerRun": 6,
+        "assistant": {
+          "enabled": true,
+          "autoCapture": false,
+          "explicitTool": true,
+          "maxItemsPerRun": 2,
+          "minUtilityScore": 0.8,
+          "minNoveltyScore": 0.85,
+          "maxWritesPerSessionWindow": 3,
+          "cooldownMinutes": 5
+        },
         "ml": {
           "provider": "openai",
           "model": "gpt-4o-mini",
@@ -548,8 +568,20 @@ Capture defaults are:
 
 - `capture.enabled`: `true`
 - `capture.mode`: `"local"`
-- `capture.includeAssistant`: `false` (default user-only capture)
+- `capture.includeAssistant`: `false` (legacy alias for `capture.assistant.autoCapture`)
 - `capture.maxItemsPerRun`: `6`
+- `capture.assistant.enabled`: `true`
+- `capture.assistant.autoCapture`: `false`
+- `capture.assistant.explicitTool`: `true`
+- `capture.assistant.maxItemsPerRun`: `2`
+- `capture.assistant.minUtilityScore`: `0.8`
+- `capture.assistant.minNoveltyScore`: `0.85`
+- `capture.assistant.maxWritesPerSessionWindow`: `3`
+- `capture.assistant.cooldownMinutes`: `5`
+- `recall.user.injectTopK`: `5` (legacy `recall.injectTopK` still works)
+- `recall.agent.injectTopK`: `2`
+- `recall.agent.minScore`: `0.78`
+- `recall.agent.onlyPlanning`: `true`
 - `capture.ml.provider`: unset
 - `capture.ml.model`: unset
 - `capture.ml.timeoutMs`: `2500`
@@ -564,14 +596,39 @@ Important behavior:
 - `capture.mode = "local"`: heuristic-only extraction.
 - `capture.mode = "hybrid"`: heuristic extraction + ML enrichment when ML config is set.
 - `capture.mode = "ml"`: ML-first extraction; falls back to heuristic if ML config/call is unavailable.
-- `capture.includeAssistant = false` (default): only `user` messages are considered for capture.
-- `capture.includeAssistant = true`: both `user` and `assistant` messages are considered for capture.
+- New memories are persisted by `workspace + agent`, not by session. `sessionKey` is kept only as metadata and for assistant-learning cooldown/window logic.
+- Recall still performs a legacy dual-read fallback for older session-scoped Mem0 records, without rewriting them.
+- `capture.includeAssistant = false` (default): assistant auto-capture is off.
+- `capture.includeAssistant = true` or `capture.assistant.autoCapture = true`: assistant messages are eligible for strict agent-learning auto-capture.
+- `capture.assistant.explicitTool = true`: exposes the `remember_learning` tool.
+- `recall.user.*` controls injected user memories.
+- `recall.agent.*` controls injected agent learnings.
 - ML calls run only when both `capture.ml.provider` and `capture.ml.model` are set.
 - `timeDecay.enabled = true`: applies temporal decay to Mem0 results using Memory Core's `agents.*.memorySearch.query.hybrid.temporalDecay` settings.
 - If Memory Core temporal decay is disabled, Mem0 decay is skipped even when `timeDecay.enabled = true`.
 - `lifecycle.enabled = true`: tracks captured Mem0 IDs, applies TTL cleanup, and exposes `/memorybraid cleanup`.
 - `lifecycle.reinforceOnRecall = true`: successful recalls refresh lifecycle timestamps, extending TTL survival for frequently used memories.
 
+## Agent learnings
+
+Memory Braid v2 adds explicit and implicit agent learnings.
+
+- `remember_learning` stores compact reusable heuristics, lessons, and strategies for future runs.
+- Use it for operational guidance that helps the agent avoid repeated mistakes or reduce tool cost/noise.
+- Do not use it for long summaries, transient details, or raw reasoning.
+- Assistant auto-capture is still available, but it is stricter than user-memory capture and only persists compact learnings that pass utility, novelty, and cooldown checks.
+
+Recall is now split into two dynamic blocks:
+
+- `<user-memories>`: user facts, preferences, decisions, and tasks.
+- `<agent-learnings>`: reusable agent heuristics, lessons, and strategies.
+
+Cache safety:
+
+- Tool awareness for `remember_learning` is injected through a stable `systemPrompt`.
+- Retrieved memories stay in dynamic `prependContext`, not in the stable prompt body.
+- Agent learnings use low `top-k`, high relevance thresholds, and deterministic formatting to avoid unnecessary prompt churn.
+
 ## Entity extraction defaults
 
 Entity extraction defaults are:

package/openclaw.plugin.json

@@ -30,6 +30,24 @@
         "properties": {
           "maxResults": { "type": "integer", "minimum": 1, "maximum": 50, "default": 8 },
           "injectTopK": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5 },
+          "user": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "enabled": { "type": "boolean", "default": true },
+              "injectTopK": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5 }
+            }
+          },
+          "agent": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "enabled": { "type": "boolean", "default": true },
+              "injectTopK": { "type": "integer", "minimum": 1, "maximum": 20, "default": 2 },
+              "minScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.78 },
+              "onlyPlanning": { "type": "boolean", "default": true }
+            }
+          },
           "merge": {
             "type": "object",
             "additionalProperties": false,
@@ -54,6 +72,20 @@
           },
           "includeAssistant": { "type": "boolean", "default": false },
           "maxItemsPerRun": { "type": "integer", "minimum": 1, "maximum": 50, "default": 6 },
+          "assistant": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "enabled": { "type": "boolean", "default": true },
+              "autoCapture": { "type": "boolean", "default": false },
+              "explicitTool": { "type": "boolean", "default": true },
+              "maxItemsPerRun": { "type": "integer", "minimum": 1, "maximum": 10, "default": 2 },
+              "minUtilityScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.8 },
+              "minNoveltyScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.85 },
+              "maxWritesPerSessionWindow": { "type": "integer", "minimum": 1, "maximum": 20, "default": 3 },
+              "cooldownMinutes": { "type": "integer", "minimum": 0, "maximum": 240, "default": 5 }
+            }
+          },
           "ml": {
             "type": "object",
             "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-braid",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "OpenClaw memory plugin that augments local memory with Mem0 capture and recall.",
   "type": "module",
   "main": "./src/index.ts",

package/src/capture.ts

@@ -17,9 +17,70 @@ function asRecord(value: unknown): Record<string, unknown> {
   return value as Record<string, unknown>;
 }
 
+function extractStructuredTextCandidate(value: unknown, depth = 0): string {
+  if (depth > 5) {
+    return "";
+  }
+  if (typeof value === "string") {
+    return normalizeWhitespace(value);
+  }
+  if (!value || typeof value !== "object") {
+    return "";
+  }
+  if (Array.isArray(value)) {
+    const parts = value
+      .map((entry) => extractStructuredTextCandidate(entry, depth + 1))
+      .filter(Boolean);
+    return normalizeWhitespace(parts.join(" "));
+  }
+
+  const record = value as Record<string, unknown>;
+  const directText = typeof record.text === "string" ? normalizeWhitespace(record.text) : "";
+  if (directText) {
+    return directText;
+  }
+  const caption = typeof record.caption === "string" ? normalizeWhitespace(record.caption) : "";
+  if (caption) {
+    return caption;
+  }
+
+  const nestedCandidates = [
+    record.message,
+    record.data,
+    record.payload,
+    record.update,
+    record.edited_message,
+    record.channel_post,
+    record.callback_query,
+  ];
+  for (const candidate of nestedCandidates) {
+    const extracted = extractStructuredTextCandidate(candidate, depth + 1);
+    if (extracted) {
+      return extracted;
+    }
+  }
+
+  return "";
+}
+
+export function extractStructuredTextFromString(content: string): string | undefined {
+  const normalized = normalizeWhitespace(content);
+  if (!normalized || !/^[{\[]/.test(normalized)) {
+    return undefined;
+  }
+
+  try {
+    const parsed = JSON.parse(normalized) as unknown;
+    const extracted = extractStructuredTextCandidate(parsed);
+    return extracted || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export function extractHookMessageText(content: unknown): string {
   if (typeof content === "string") {
-    return normalizeWhitespace(content);
+    return extractStructuredTextFromString(content) ?? normalizeWhitespace(content);
   }
   if (!Array.isArray(content)) {
     return "";
@@ -32,7 +93,8 @@ export function extractHookMessageText(content: unknown): string {
     }
     const item = block as { type?: unknown; text?: unknown };
     if (item.type === "text" && typeof item.text === "string") {
-      const normalized = normalizeWhitespace(item.text);
+      const normalized =
+        extractStructuredTextFromString(item.text) ?? normalizeWhitespace(item.text);
       if (normalized) {
         parts.push(normalized);
       }
@@ -249,3 +311,67 @@ export function isOversizedAtomicMemory(text: string): boolean {
   const lines = normalized.split(/\r?\n/).filter((line) => line.trim().length > 0);
   return normalized.length > 1600 || lines.length > 18;
 }
+
+const RECAP_PREFIXES = [
+  /^the user\b/i,
+  /^user\b/i,
+  /^usuario\b/i,
+  /^in this (?:turn|conversation)\b/i,
+  /^(?:we|i) (?:discussed|talked about|went over|covered)\b/i,
+  /^(?:summary|recap)\b/i,
+];
+
+const TEMPORAL_REFERENCE_PATTERN =
+  /\b(?:today|tomorrow|yesterday|this turn|this session|earlier in this session|just now|in this chat)\b/i;
+
+export function isLikelyTurnRecap(text: string): boolean {
+  const normalized = normalizeWhitespace(text);
+  if (!normalized) {
+    return false;
+  }
+  if (normalized.length > 260 && /\b(?:asked|wanted|needed|said|requested)\b/i.test(normalized)) {
+    return true;
+  }
+  return RECAP_PREFIXES.some((pattern) => pattern.test(normalized));
+}
+
+function splitIntoSentences(text: string): string[] {
+  return text
+    .split(/(?<=[.!?])\s+/)
+    .map((sentence) => normalizeWhitespace(sentence))
+    .filter(Boolean);
+}
+
+function looksReusableLearning(text: string): boolean {
+  if (text.length < 24 || text.length > 220) {
+    return false;
+  }
+  if (TEMPORAL_REFERENCE_PATTERN.test(text)) {
+    return false;
+  }
+  if (isLikelyTranscriptLikeText(text) || isLikelyTurnRecap(text)) {
+    return false;
+  }
+  return /\b(?:prefer|avoid|use|keep|store|remember|dedupe|inject|search|persist|reject|limit|filter|only|always|never|when)\b/i.test(
+    text,
+  );
+}
+
+export function compactAgentLearning(text: string): string | undefined {
+  const normalized = normalizeWhitespace(text);
+  if (!normalized || isOversizedAtomicMemory(normalized) || isLikelyTranscriptLikeText(normalized)) {
+    return undefined;
+  }
+  if (looksReusableLearning(normalized)) {
+    return normalized;
+  }
+
+  const sentences = splitIntoSentences(normalized);
+  for (const sentence of sentences) {
+    if (looksReusableLearning(sentence)) {
+      return sentence;
+    }
+  }
+
+  return undefined;
+}

package/src/config.ts

@@ -11,6 +11,16 @@ export type MemoryBraidConfig = {
   recall: {
     maxResults: number;
     injectTopK: number;
+    user: {
+      enabled: boolean;
+      injectTopK: number;
+    };
+    agent: {
+      enabled: boolean;
+      injectTopK: number;
+      minScore: number;
+      onlyPlanning: boolean;
+    };
     merge: {
       strategy: "rrf";
       rrfK: number;
@@ -23,6 +33,16 @@ export type MemoryBraidConfig = {
     mode: "local" | "hybrid" | "ml";
     includeAssistant: boolean;
     maxItemsPerRun: number;
+    assistant: {
+      enabled: boolean;
+      autoCapture: boolean;
+      explicitTool: boolean;
+      maxItemsPerRun: number;
+      minUtilityScore: number;
+      minNoveltyScore: number;
+      maxWritesPerSessionWindow: number;
+      cooldownMinutes: number;
+    };
     ml: {
       provider?: "openai" | "anthropic" | "gemini";
       model?: string;
@@ -80,6 +100,16 @@ const DEFAULTS: MemoryBraidConfig = {
   recall: {
     maxResults: 8,
     injectTopK: 5,
+    user: {
+      enabled: true,
+      injectTopK: 5,
+    },
+    agent: {
+      enabled: true,
+      injectTopK: 2,
+      minScore: 0.78,
+      onlyPlanning: true,
+    },
     merge: {
       strategy: "rrf",
       rrfK: 60,
@@ -92,6 +122,16 @@ const DEFAULTS: MemoryBraidConfig = {
     mode: "local",
     includeAssistant: false,
     maxItemsPerRun: 6,
+    assistant: {
+      enabled: true,
+      autoCapture: false,
+      explicitTool: true,
+      maxItemsPerRun: 2,
+      minUtilityScore: 0.8,
+      minNoveltyScore: 0.85,
+      maxWritesPerSessionWindow: 3,
+      cooldownMinutes: 5,
+    },
     ml: {
       provider: undefined,
       model: undefined,
@@ -168,8 +208,11 @@ export function parseConfig(raw: unknown): MemoryBraidConfig {
   const root = asRecord(raw);
   const mem0 = asRecord(root.mem0);
   const recall = asRecord(root.recall);
+  const recallUser = asRecord(recall.user);
+  const recallAgent = asRecord(recall.agent);
   const merge = asRecord(recall.merge);
   const capture = asRecord(root.capture);
+  const captureAssistant = asRecord(capture.assistant);
   const entityExtraction = asRecord(root.entityExtraction);
   const entityStartup = asRecord(entityExtraction.startup);
   const ml = asRecord(capture.ml);
@@ -194,6 +237,16 @@ export function parseConfig(raw: unknown): MemoryBraidConfig {
         ? parsedEntityModel
         : "gpt-4o-mini"
       : parsedEntityModel ?? DEFAULTS.entityExtraction.model;
+  const includeAssistant = asBoolean(
+    capture.includeAssistant,
+    DEFAULTS.capture.includeAssistant,
+  );
+  const legacyInjectTopK = asInt(
+    recall.injectTopK,
+    DEFAULTS.recall.injectTopK,
+    1,
+    20,
+  );
 
   return {
     enabled: asBoolean(root.enabled, DEFAULTS.enabled),
@@ -207,7 +260,35 @@ export function parseConfig(raw: unknown): MemoryBraidConfig {
     },
     recall: {
       maxResults: asInt(recall.maxResults, DEFAULTS.recall.maxResults, 1, 50),
-      injectTopK: asInt(recall.injectTopK, DEFAULTS.recall.injectTopK, 1, 20),
+      injectTopK: legacyInjectTopK,
+      user: {
+        enabled: asBoolean(recallUser.enabled, DEFAULTS.recall.user.enabled),
+        injectTopK: asInt(
+          recallUser.injectTopK,
+          legacyInjectTopK,
+          1,
+          20,
+        ),
+      },
+      agent: {
+        enabled: asBoolean(recallAgent.enabled, DEFAULTS.recall.agent.enabled),
+        injectTopK: asInt(
+          recallAgent.injectTopK,
+          DEFAULTS.recall.agent.injectTopK,
+          1,
+          20,
+        ),
+        minScore: asNumber(
+          recallAgent.minScore,
+          DEFAULTS.recall.agent.minScore,
+          0,
+          1,
+        ),
+        onlyPlanning: asBoolean(
+          recallAgent.onlyPlanning,
+          DEFAULTS.recall.agent.onlyPlanning,
+        ),
+      },
       merge: {
         strategy: "rrf",
         rrfK: asInt(merge.rrfK, DEFAULTS.recall.merge.rrfK, 1, 500),
@@ -218,8 +299,52 @@ export function parseConfig(raw: unknown): MemoryBraidConfig {
     capture: {
       enabled: asBoolean(capture.enabled, DEFAULTS.capture.enabled),
       mode: captureMode,
-      includeAssistant: asBoolean(capture.includeAssistant, DEFAULTS.capture.includeAssistant),
+      includeAssistant,
       maxItemsPerRun: asInt(capture.maxItemsPerRun, DEFAULTS.capture.maxItemsPerRun, 1, 50),
+      assistant: {
+        enabled: asBoolean(
+          captureAssistant.enabled,
+          DEFAULTS.capture.assistant.enabled,
+        ),
+        autoCapture: asBoolean(
+          captureAssistant.autoCapture,
+          includeAssistant,
+        ),
+        explicitTool: asBoolean(
+          captureAssistant.explicitTool,
+          DEFAULTS.capture.assistant.explicitTool,
+        ),
+        maxItemsPerRun: asInt(
+          captureAssistant.maxItemsPerRun,
+          DEFAULTS.capture.assistant.maxItemsPerRun,
+          1,
+          10,
+        ),
+        minUtilityScore: asNumber(
+          captureAssistant.minUtilityScore,
+          DEFAULTS.capture.assistant.minUtilityScore,
+          0,
+          1,
+        ),
+        minNoveltyScore: asNumber(
+          captureAssistant.minNoveltyScore,
+          DEFAULTS.capture.assistant.minNoveltyScore,
+          0,
+          1,
+        ),
+        maxWritesPerSessionWindow: asInt(
+          captureAssistant.maxWritesPerSessionWindow,
+          DEFAULTS.capture.assistant.maxWritesPerSessionWindow,
+          1,
+          20,
+        ),
+        cooldownMinutes: asInt(
+          captureAssistant.cooldownMinutes,
+          DEFAULTS.capture.assistant.cooldownMinutes,
+          0,
+          240,
+        ),
+      },
       ml: {
         provider:
           ml.provider === "openai" || ml.provider === "anthropic" || ml.provider === "gemini"

package/src/extract.ts

@@ -1,6 +1,10 @@
 import { normalizeForHash, normalizeWhitespace, sha256 } from "./chunking.js";
 import type { MemoryBraidConfig } from "./config.js";
-import { isLikelyTranscriptLikeText, isOversizedAtomicMemory } from "./capture.js";
+import {
+  extractStructuredTextFromString,
+  isLikelyTranscriptLikeText,
+  isOversizedAtomicMemory,
+} from "./capture.js";
 import { MemoryBraidLogger } from "./logger.js";
 import type { ExtractedCandidate } from "./types.js";
 
@@ -47,7 +51,7 @@ function isLikelyFeedOrImportedText(text: string): boolean {
 
 function extractMessageText(content: unknown): string {
   if (typeof content === "string") {
-    return normalizeWhitespace(content);
+    return extractStructuredTextFromString(content) ?? normalizeWhitespace(content);
   }
   if (!Array.isArray(content)) {
     return "";
@@ -59,7 +63,8 @@ function extractMessageText(content: unknown): string {
     }
     const item = block as { type?: unknown; text?: unknown };
     if (item.type === "text" && typeof item.text === "string") {
-      const normalized = normalizeWhitespace(item.text);
+      const normalized =
+        extractStructuredTextFromString(item.text) ?? normalizeWhitespace(item.text);
       if (normalized) {
         parts.push(normalized);
       }
@@ -432,7 +437,7 @@ export async function extractCandidates(params: {
   runId?: string;
 }): Promise<ExtractedCandidate[]> {
   const normalized = normalizeMessages(params.messages);
-  const captureFromAssistant = params.cfg.capture.includeAssistant;
+  const captureFromAssistant = params.cfg.capture.assistant.autoCapture;
   const candidatesInput = normalized.filter((message) =>
     captureFromAssistant
       ? message.role === "user" || message.role === "assistant"