memory-braid 0.7.0 → 0.8.0

package/README.md

@@ -2,9 +2,19 @@
 
 Memory Braid is an OpenClaw `kind: "memory"` plugin that augments local memory search (core/QMD) with Mem0.
 
+## Ownership model
+
+Memory Braid is intentionally hybrid, but not with shared ownership.
+
+- OpenClaw prompt context + compaction are the source of truth for the live session.
+- Core/QMD is the source of truth for written documents, notes, and canonical project knowledge.
+- Mem0 is the source of truth for learned cross-session memory such as preferences, recurring decisions, and procedural learnings.
+
+The goal is hybrid retrieval with single ownership per memory class. Memory Braid should not re-own markdown knowledge, and Mem0 should not be treated as the canonical store for documents.
+
 ## Features
 
-- Hybrid recall: local memory + Mem0, merged with weighted RRF.
+- Hybrid recall with split ownership: 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`.
@@ -99,7 +109,9 @@ Migration:
 
 - If you relied on bootstrap/reconcile mirroring, pin to `<0.4.0`.
 - For `0.4.0+`, remove `bootstrap` and `reconcile` from your plugin config.
-- Keep core/QMD as the source for markdown/sessions, and use Memory Braid for capture/mem0 recall/lifecycle.
+- Keep OpenClaw prompt context as the source of truth for the live session.
+- Keep core/QMD as the source of truth for markdown and canonical written knowledge.
+- Use Memory Braid + Mem0 for learned cross-session memory, consolidation, and lifecycle management.
 
 ## Install
 
@@ -110,7 +122,7 @@ On the target machine:
 1. Install from npm:
 
 ```bash
-openclaw plugins install memory-braid@0.7.0
+openclaw plugins install memory-braid@0.8.0
 ```
 
 2. Rebuild native dependencies inside the installed extension:
@@ -233,13 +245,13 @@ Add this under `plugins.entries["memory-braid"].config` in your OpenClaw config:
     "minScore": 0.65,
     "maxEntitiesPerMemory": 8,
     "startup": {
-      "downloadOnStartup": true,
+      "downloadOnStartup": false,
       "warmupText": "John works at Acme in Berlin."
     }
   },
   "consolidation": {
     "enabled": true,
-    "startupRun": true,
+    "startupRun": false,
     "intervalMinutes": 360,
     "opportunisticNewMemoryThreshold": 5,
     "opportunisticMinMinutesSinceLastRun": 30,
@@ -558,7 +570,7 @@ Use this preset when:
         "minScore": 0.65,
         "maxEntitiesPerMemory": 8,
         "startup": {
-          "downloadOnStartup": true,
+          "downloadOnStartup": false,
           "warmupText": "John works at Acme in Berlin."
         }
       },
@@ -669,14 +681,14 @@ Entity extraction defaults are:
 - `entityExtraction.timeoutMs`: `2500`
 - `entityExtraction.minScore`: `0.65`
 - `entityExtraction.maxEntitiesPerMemory`: `8`
-- `entityExtraction.startup.downloadOnStartup`: `true`
+- `entityExtraction.startup.downloadOnStartup`: `false`
 - `entityExtraction.startup.warmupText`: `"John works at Acme in Berlin."`
 
 When enabled:
 
 - Local NER model cache/download path is `<OPENCLAW_STATE_DIR>/memory-braid/models/entity-extraction` (typically `~/.openclaw/memory-braid/models/entity-extraction`).
 - Captured memories get `metadata.entities` and `metadata.entityUris` (canonical IDs like `entity://person/john-doe`).
-- Startup warmup runs for both providers (`downloadOnStartup: true`).
+- Startup warmup is opt-in (`downloadOnStartup: false`) so model prewarm does not land on the critical gateway startup path.
 
 Warmup command:
 

package/openclaw.plugin.json

@@ -129,7 +129,7 @@
             "type": "object",
             "additionalProperties": false,
             "properties": {
-              "downloadOnStartup": { "type": "boolean", "default": true },
+              "downloadOnStartup": { "type": "boolean", "default": false },
               "warmupText": {
                 "type": "string",
                 "default": "John works at Acme in Berlin."
@@ -186,7 +186,7 @@
         "additionalProperties": false,
         "properties": {
           "enabled": { "type": "boolean", "default": true },
-          "startupRun": { "type": "boolean", "default": true },
+          "startupRun": { "type": "boolean", "default": false },
           "intervalMinutes": {
             "type": "integer",
             "minimum": 1,

package/package.json

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

package/src/config.ts

@@ -172,7 +172,7 @@ const DEFAULTS: MemoryBraidConfig = {
     minScore: 0.65,
     maxEntitiesPerMemory: 8,
     startup: {
-      downloadOnStartup: true,
+      downloadOnStartup: false,
       warmupText: "John works at Acme in Berlin.",
     },
   },
@@ -196,7 +196,7 @@ const DEFAULTS: MemoryBraidConfig = {
   },
   consolidation: {
     enabled: true,
-    startupRun: true,
+    startupRun: false,
     intervalMinutes: 360,
     opportunisticNewMemoryThreshold: 5,
     opportunisticMinMinutesSinceLastRun: 30,

package/src/index.ts

@@ -2911,13 +2911,13 @@ const memoryBraidPlugin = {
       }
     });
 
-    api.on("before_agent_start", async (event, ctx) => {
+    api.on("before_prompt_build", async (event, ctx) => {
       const runId = log.newRunId();
       const scope = resolveRuntimeScopeFromHookContext(ctx);
       const persistentScope = resolvePersistentScopeFromHookContext(ctx);
       const legacyScope = resolveLegacySessionScopeFromHookContext(ctx);
       const baseResult = {
-        systemPrompt: REMEMBER_LEARNING_SYSTEM_PROMPT,
+        prependSystemContext: REMEMBER_LEARNING_SYSTEM_PROMPT,
       };
       if (isExcludedAutoMemorySession(ctx.sessionKey)) {
         log.debug("memory_braid.search.skip", {
@@ -3048,7 +3048,7 @@ const memoryBraidPlugin = {
       });
 
       return {
-        systemPrompt: REMEMBER_LEARNING_SYSTEM_PROMPT,
+        prependSystemContext: REMEMBER_LEARNING_SYSTEM_PROMPT,
         prependContext,
       };
     });