memory-braid 0.6.0 → 0.7.0

package/README.md

@@ -5,9 +5,14 @@ Memory Braid is an OpenClaw `kind: "memory"` plugin that augments local memory s
 ## Features
 
 - Hybrid recall: local memory + Mem0, merged with weighted RRF.
+- Layered Mem0 memory: episodic captures, semantic compendium memories, and procedural agent learnings.
 - Capture-first Mem0 memory: plugin writes only captured memories to Mem0 (no markdown/session indexing).
 - Capture pipeline modes: `local`, `hybrid`, `ml`.
+- Deterministic memory selection policy: ML may suggest candidates, but plugin code decides `ignore|episodic|procedural|semantic` using local thresholds and heuristics.
 - Optional entity extraction: local multilingual NER or OpenAI NER with canonical `entity://...` URIs in memory metadata.
+- Lightweight taxonomy on captured and semantic memories: `people`, `places`, `organizations`, `projects`, `tools`, `topics`.
+- Time-aware retrieval for month-style prompts such as `in June`, `this month`, and `last month`.
+- Automatic consolidation loop that promotes repeated episodic memories into semantic compendium memories.
 - Structured debug logs for troubleshooting and tuning.
 - Debug-only LLM usage observability: per-turn cache usage, rolling windows, and rising/stable/improving trend logs.
 
@@ -21,11 +26,14 @@ This release hardens capture and remediation for historical installs.
 - Metadata: new captured memories now include additive provenance fields such as `captureOrigin`, `captureMessageHash`, `captureTurnHash`, `capturePath`, and `pluginCaptureVersion`.
 - Historical installs: no startup mutation is performed automatically. Operators should audit first, then explicitly quarantine or delete suspicious captured memories.
 
-## Remediation commands
+## Command surface
 
-Memory Braid now exposes read-only audit and explicit remediation commands:
+Memory Braid exposes audit, search, consolidation, and remediation commands:
 
 ```bash
+/memorybraid search standups --layer semantic --kind preference
+/memorybraid search "What did we discuss in June?" --layer episodic
+/memorybraid consolidate
 /memorybraid audit
 /memorybraid remediate audit
 /memorybraid remediate quarantine
@@ -36,6 +44,10 @@ Memory Braid now exposes read-only audit and explicit remediation commands:
 
 Notes:
 
+- `search` is Mem0-only and intended for validating plugin-managed memory rather than local markdown memory.
+- `search` supports `--limit`, `--layer`, `--kind`, `--from`, `--to`, and `--include-quarantined`.
+- `consolidate` runs one compendium synthesis pass immediately and reports how many semantic memories were created or updated.
+- New capture metadata includes deterministic selection fields such as `selectionDecision`, `rememberabilityScore`, and `rememberabilityReasons`.
 - Dry-run is the default for remediation commands. Nothing mutates until you pass `--apply`.
 - `audit` reports counts by `sourceType`, `captureOrigin`, and `pluginCaptureVersion`, plus suspicious legacy samples.
 - `quarantine --apply` excludes suspicious captured memories from future Mem0 injection. It records quarantine state locally and also tags Mem0 metadata where supported.
@@ -98,7 +110,7 @@ On the target machine:
 1. Install from npm:
 
 ```bash
-openclaw plugins install memory-braid@0.4.0
+openclaw plugins install memory-braid@0.7.0
 ```
 
 2. Rebuild native dependencies inside the installed extension:
@@ -225,6 +237,17 @@ Add this under `plugins.entries["memory-braid"].config` in your OpenClaw config:
       "warmupText": "John works at Acme in Berlin."
     }
   },
+  "consolidation": {
+    "enabled": true,
+    "startupRun": true,
+    "intervalMinutes": 360,
+    "opportunisticNewMemoryThreshold": 5,
+    "opportunisticMinMinutesSinceLastRun": 30,
+    "minSupportCount": 2,
+    "minRecallCount": 2,
+    "semanticMaxSourceIds": 20,
+    "timeQueryParsing": true
+  },
   "debug": {
     "enabled": true
   }
@@ -283,6 +306,7 @@ Expected events:
 - `memory_braid.capture.extract`
 - `memory_braid.capture.ml` (for `capture.mode=hybrid|ml`)
 - `memory_braid.entity.extract`
+- `memory_braid.capture.selection`
 - `memory_braid.capture.persist`
 
 ## Self-hosting quick guide
@@ -569,6 +593,11 @@ Capture defaults are:
 - `capture.enabled`: `true`
 - `capture.mode`: `"local"`
 - `capture.includeAssistant`: `false` (legacy alias for `capture.assistant.autoCapture`)
+- `capture.selection.minPreferenceDecisionScore`: `0.45`
+- `capture.selection.minFactScore`: `0.52`
+- `capture.selection.minTaskScore`: `0.72`
+- `capture.selection.minOtherScore`: `0.82`
+- `capture.selection.minProceduralScore`: `0.58`
 - `capture.maxItemsPerRun`: `6`
 - `capture.assistant.enabled`: `true`
 - `capture.assistant.autoCapture`: `false`
@@ -588,6 +617,7 @@ Capture defaults are:
 - `timeDecay.enabled`: `false`
 - `lifecycle.enabled`: `false`
 - `lifecycle.captureTtlDays`: `90`
+- `consolidation.minSelectionScore`: `0.56`
 - `lifecycle.cleanupIntervalMinutes`: `360`
 - `lifecycle.reinforceOnRecall`: `true`
 
@@ -679,6 +709,8 @@ Key events:
 - `memory_braid.search.local|mem0|merge|inject|skip`
 - `memory_braid.search.mem0_decay`
 - `memory_braid.capture.extract|ml|persist|skip`
+- `memory_braid.capture.selection`
+- `memory_braid.consolidation.plan|run|supersede`
 - `memory_braid.lifecycle.reinforce|cleanup`
 - `memory_braid.entity.model_load|warmup|extract`
 - `memory_braid.mem0.request|response|error`
@@ -696,6 +728,8 @@ Traceability tips:
   - `mem0AddWithoutId`
   - `entityAnnotatedCandidates`
   - `totalEntitiesAttached`
+- `memory_braid.capture.selection` includes the deterministic routing decision, numeric rememberability score, and reasons used for `ignore|episodic|procedural`.
+- `memory_braid.consolidation.plan` includes the compendium drafts that passed deterministic promotion, including promotion score and reasons.
 - `memory_braid.capture.ml` includes `fallbackUsed` and fallback reasons when ML is unavailable.
 - `memory_braid.entity.extract` includes `entityTypes` and `sampleEntityUris`.
 

package/openclaw.plugin.json

@@ -72,6 +72,17 @@
           },
           "includeAssistant": { "type": "boolean", "default": false },
           "maxItemsPerRun": { "type": "integer", "minimum": 1, "maximum": 50, "default": 6 },
+          "selection": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "minPreferenceDecisionScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.45 },
+              "minFactScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.52 },
+              "minTaskScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.72 },
+              "minOtherScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.82 },
+              "minProceduralScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.58 }
+            }
+          },
           "assistant": {
             "type": "object",
             "additionalProperties": false,
@@ -170,6 +181,42 @@
           "reinforceOnRecall": { "type": "boolean", "default": true }
         }
       },
+      "consolidation": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean", "default": true },
+          "startupRun": { "type": "boolean", "default": true },
+          "intervalMinutes": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 10080,
+            "default": 360
+          },
+          "opportunisticNewMemoryThreshold": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100,
+            "default": 5
+          },
+          "opportunisticMinMinutesSinceLastRun": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1440,
+            "default": 30
+          },
+          "minSupportCount": { "type": "integer", "minimum": 1, "maximum": 50, "default": 2 },
+          "minRecallCount": { "type": "integer", "minimum": 1, "maximum": 100, "default": 2 },
+          "minSelectionScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.56 },
+          "semanticMaxSourceIds": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 200,
+            "default": 20
+          },
+          "timeQueryParsing": { "type": "boolean", "default": true }
+        }
+      },
       "debug": {
         "type": "object",
         "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-braid",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "OpenClaw memory plugin that augments local memory with Mem0 capture and recall.",
   "type": "module",
   "main": "./src/index.ts",
@@ -32,6 +32,7 @@
   },
   "dependencies": {
     "@xenova/transformers": "^2.17.2",
+    "chrono-node": "^2.9.0",
     "mem0ai": "^2.2.3"
   },
   "devDependencies": {

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);
       }

package/src/config.ts

@@ -33,6 +33,13 @@ export type MemoryBraidConfig = {
     mode: "local" | "hybrid" | "ml";
     includeAssistant: boolean;
     maxItemsPerRun: number;
+    selection: {
+      minPreferenceDecisionScore: number;
+      minFactScore: number;
+      minTaskScore: number;
+      minOtherScore: number;
+      minProceduralScore: number;
+    };
     assistant: {
       enabled: boolean;
       autoCapture: boolean;
@@ -79,6 +86,18 @@ export type MemoryBraidConfig = {
     cleanupIntervalMinutes: number;
     reinforceOnRecall: boolean;
   };
+  consolidation: {
+    enabled: boolean;
+    startupRun: boolean;
+    intervalMinutes: number;
+    opportunisticNewMemoryThreshold: number;
+    opportunisticMinMinutesSinceLastRun: number;
+    minSupportCount: number;
+    minRecallCount: number;
+    minSelectionScore: number;
+    semanticMaxSourceIds: number;
+    timeQueryParsing: boolean;
+  };
   debug: {
     enabled: boolean;
     includePayloads: boolean;
@@ -122,6 +141,13 @@ const DEFAULTS: MemoryBraidConfig = {
     mode: "local",
     includeAssistant: false,
     maxItemsPerRun: 6,
+    selection: {
+      minPreferenceDecisionScore: 0.45,
+      minFactScore: 0.52,
+      minTaskScore: 0.72,
+      minOtherScore: 0.82,
+      minProceduralScore: 0.58,
+    },
     assistant: {
       enabled: true,
       autoCapture: false,
@@ -168,6 +194,18 @@ const DEFAULTS: MemoryBraidConfig = {
     cleanupIntervalMinutes: 360,
     reinforceOnRecall: true,
   },
+  consolidation: {
+    enabled: true,
+    startupRun: true,
+    intervalMinutes: 360,
+    opportunisticNewMemoryThreshold: 5,
+    opportunisticMinMinutesSinceLastRun: 30,
+    minSupportCount: 2,
+    minRecallCount: 2,
+    minSelectionScore: 0.56,
+    semanticMaxSourceIds: 20,
+    timeQueryParsing: true,
+  },
   debug: {
     enabled: false,
     includePayloads: false,
@@ -212,6 +250,7 @@ export function parseConfig(raw: unknown): MemoryBraidConfig {
   const recallAgent = asRecord(recall.agent);
   const merge = asRecord(recall.merge);
   const capture = asRecord(root.capture);
+  const captureSelection = asRecord(capture.selection);
   const captureAssistant = asRecord(capture.assistant);
   const entityExtraction = asRecord(root.entityExtraction);
   const entityStartup = asRecord(entityExtraction.startup);
@@ -221,6 +260,7 @@ export function parseConfig(raw: unknown): MemoryBraidConfig {
   const semantic = asRecord(dedupe.semantic);
   const timeDecay = asRecord(root.timeDecay);
   const lifecycle = asRecord(root.lifecycle);
+  const consolidation = asRecord(root.consolidation);
   const debug = asRecord(root.debug);
 
   const mode = mem0.mode === "oss" ? "oss" : "cloud";
@@ -301,6 +341,38 @@ export function parseConfig(raw: unknown): MemoryBraidConfig {
       mode: captureMode,
       includeAssistant,
       maxItemsPerRun: asInt(capture.maxItemsPerRun, DEFAULTS.capture.maxItemsPerRun, 1, 50),
+      selection: {
+        minPreferenceDecisionScore: asNumber(
+          captureSelection.minPreferenceDecisionScore,
+          DEFAULTS.capture.selection.minPreferenceDecisionScore,
+          0,
+          1,
+        ),
+        minFactScore: asNumber(
+          captureSelection.minFactScore,
+          DEFAULTS.capture.selection.minFactScore,
+          0,
+          1,
+        ),
+        minTaskScore: asNumber(
+          captureSelection.minTaskScore,
+          DEFAULTS.capture.selection.minTaskScore,
+          0,
+          1,
+        ),
+        minOtherScore: asNumber(
+          captureSelection.minOtherScore,
+          DEFAULTS.capture.selection.minOtherScore,
+          0,
+          1,
+        ),
+        minProceduralScore: asNumber(
+          captureSelection.minProceduralScore,
+          DEFAULTS.capture.selection.minProceduralScore,
+          0,
+          1,
+        ),
+      },
       assistant: {
         enabled: asBoolean(
           captureAssistant.enabled,
@@ -411,6 +483,56 @@ export function parseConfig(raw: unknown): MemoryBraidConfig {
         DEFAULTS.lifecycle.reinforceOnRecall,
       ),
     },
+    consolidation: {
+      enabled: asBoolean(consolidation.enabled, DEFAULTS.consolidation.enabled),
+      startupRun: asBoolean(consolidation.startupRun, DEFAULTS.consolidation.startupRun),
+      intervalMinutes: asInt(
+        consolidation.intervalMinutes,
+        DEFAULTS.consolidation.intervalMinutes,
+        1,
+        10080,
+      ),
+      opportunisticNewMemoryThreshold: asInt(
+        consolidation.opportunisticNewMemoryThreshold,
+        DEFAULTS.consolidation.opportunisticNewMemoryThreshold,
+        1,
+        100,
+      ),
+      opportunisticMinMinutesSinceLastRun: asInt(
+        consolidation.opportunisticMinMinutesSinceLastRun,
+        DEFAULTS.consolidation.opportunisticMinMinutesSinceLastRun,
+        1,
+        1440,
+      ),
+      minSupportCount: asInt(
+        consolidation.minSupportCount,
+        DEFAULTS.consolidation.minSupportCount,
+        1,
+        50,
+      ),
+      minRecallCount: asInt(
+        consolidation.minRecallCount,
+        DEFAULTS.consolidation.minRecallCount,
+        1,
+        100,
+      ),
+      minSelectionScore: asNumber(
+        consolidation.minSelectionScore,
+        DEFAULTS.consolidation.minSelectionScore,
+        0,
+        1,
+      ),
+      semanticMaxSourceIds: asInt(
+        consolidation.semanticMaxSourceIds,
+        DEFAULTS.consolidation.semanticMaxSourceIds,
+        1,
+        200,
+      ),
+      timeQueryParsing: asBoolean(
+        consolidation.timeQueryParsing,
+        DEFAULTS.consolidation.timeQueryParsing,
+      ),
+    },
     debug: {
       enabled: asBoolean(debug.enabled, DEFAULTS.debug.enabled),
       includePayloads: asBoolean(debug.includePayloads, DEFAULTS.debug.includePayloads),