memory-braid 0.3.7 → 0.4.0

package/README.md

@@ -5,12 +5,31 @@ Memory Braid is an OpenClaw `kind: "memory"` plugin that augments local memory s
 ## Features
 
 - Hybrid recall: local memory + Mem0, merged with weighted RRF.
-- Install-time bootstrap import: indexes existing `MEMORY.md`, `memory.md`, `memory/**/*.md`, and recent sessions.
-- Periodic reconcile: keeps remote Mem0 chunks updated and deletes stale remote chunks.
+- Capture-first Mem0 memory: plugin writes only captured memories to Mem0 (no markdown/session indexing).
 - Capture pipeline modes: `local`, `hybrid`, `ml`.
 - Optional entity extraction: multilingual NER with canonical `entity://...` URIs in memory metadata.
 - Structured debug logs for troubleshooting and tuning.
 
+## Breaking changes in 0.4.0
+
+Memory Braid `0.4.0` is intentionally simplified to capture/recall-only mode.
+
+- Removed managed indexing features:
+  - `bootstrap` config block removed.
+  - `reconcile` config block removed.
+  - startup bootstrap/reconcile flows removed.
+- Mem0 is now used only for captured memories.
+  - markdown and session indexing is no longer done by this plugin.
+  - local markdown/session retrieval remains in core/QMD via `memory_search`.
+- `/memorybraid stats` now reports capture + lifecycle only (no reconcile section).
+- Legacy Mem0 records with `metadata.sourceType` of `markdown` or `session` are ignored during Mem0 recall merge.
+
+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.
+
 ## Install
 
 ### Install from npm (recommended)
@@ -20,7 +39,7 @@ On the target machine:
 1. Install from npm:
 
 ```bash
-openclaw plugins install memory-braid@0.3.5
+openclaw plugins install memory-braid@0.4.0
 ```
 
 2. Rebuild native dependencies inside the installed extension:
@@ -127,6 +146,7 @@ Add this under `plugins.entries["memory-braid"].config` in your OpenClaw config:
   "capture": {
     "enabled": true,
     "mode": "hybrid",
+    "includeAssistant": false,
     "maxItemsPerRun": 6,
     "ml": {
       "provider": "openai",
@@ -220,26 +240,26 @@ Memory Braid supports two self-hosted setups:
    - `embedder` (provider + credentials/model)
    - `vectorStore` (provider + connection/config)
    - `llm` (provider + model; used by Mem0 OSS internals)
+   - Partial `ossConfig` is safe: Memory Braid deep-merges your values over OSS defaults.
+     - If a section provider changes (for example `embedder.provider: "ollama"`), that section is replaced instead of mixed.
 3. Restart OpenClaw.
 4. Send at least one message to trigger capture/recall.
 5. Check logs for:
    - `memory_braid.startup`
-   - `memory_braid.bootstrap.begin|complete`
-   - `memory_braid.reconcile.begin|complete`
    - `memory_braid.mem0.request|response`
 
 ### Smoke test checklist
 
 1. Enable debug:
    - `plugins.memory-braid.debug.enabled: true`
-2. Start OpenClaw and wait for bootstrap to finish.
-3. Ask a query that should match existing memory (from `MEMORY.md` or recent sessions).
-4. Confirm `memory_search` returns merged results.
-5. Send a preference/decision statement and verify subsequent turns can recall it.
+2. Start OpenClaw.
+3. Send a preference/decision statement.
+4. Confirm later `memory_search` runs return merged local+Mem0 results.
+5. Run `/memorybraid stats` to verify capture counters increase.
 
 ### Notes
 
-- Bootstrap imports existing markdown memory + recent sessions once, then reconcile keeps remote state aligned.
+- Memory Braid 0.4.0 is capture/recall-only by design: markdown and session indexing stay in core/QMD.
 - If self-hosted infra is down, local memory tools continue working; Mem0 side degrades gracefully.
 - For Mem0 platform/API specifics, see official docs: [Mem0 OSS quickstart](https://docs.mem0.ai/open-source/node-quickstart) and [Mem0 API reference](https://docs.mem0.ai/api-reference).
 
@@ -384,7 +404,6 @@ Use this preset when:
 3. Start OpenClaw with `debug.enabled: true` and verify:
    - `memory_braid.startup`
    - `memory_braid.mem0.response` with `mode: "oss"`
-   - `memory_braid.bootstrap.complete`
 
 ## Recommended config
 
@@ -404,23 +423,10 @@ Use this preset when:
           "mem0Weight": 1
         }
       },
-      "bootstrap": {
-        "enabled": true,
-        "includeMarkdown": true,
-        "includeSessions": true,
-        "sessionLookbackDays": 90,
-        "batchSize": 50,
-        "concurrency": 3
-      },
-      "reconcile": {
-        "enabled": true,
-        "intervalMinutes": 30,
-        "batchSize": 100,
-        "deleteStale": true
-      },
       "capture": {
         "enabled": true,
         "mode": "hybrid",
+        "includeAssistant": false,
         "maxItemsPerRun": 6,
         "ml": {
           "provider": "openai",
@@ -443,6 +449,15 @@ Use this preset when:
         "lexical": { "minJaccard": 0.3 },
         "semantic": { "enabled": true, "minScore": 0.92 }
       },
+      "timeDecay": {
+        "enabled": false
+      },
+      "lifecycle": {
+        "enabled": false,
+        "captureTtlDays": 90,
+        "cleanupIntervalMinutes": 360,
+        "reinforceOnRecall": true
+      },
       "debug": {
         "enabled": false,
         "includePayloads": false,
@@ -460,17 +475,29 @@ Capture defaults are:
 
 - `capture.enabled`: `true`
 - `capture.mode`: `"local"`
+- `capture.includeAssistant`: `false` (default user-only capture)
 - `capture.maxItemsPerRun`: `6`
 - `capture.ml.provider`: unset
 - `capture.ml.model`: unset
 - `capture.ml.timeoutMs`: `2500`
+- `timeDecay.enabled`: `false`
+- `lifecycle.enabled`: `false`
+- `lifecycle.captureTtlDays`: `90`
+- `lifecycle.cleanupIntervalMinutes`: `360`
+- `lifecycle.reinforceOnRecall`: `true`
 
 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.
 - 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.
 
 ## Entity extraction defaults
 
@@ -493,6 +520,8 @@ When enabled:
 Warmup command:
 
 - `/memorybraid status`
+- `/memorybraid stats`
+- `/memorybraid cleanup`
 - `/memorybraid warmup`
 - `/memorybraid warmup --force`
 
@@ -516,10 +545,10 @@ Key events:
 
 - `memory_braid.startup`
 - `memory_braid.config`
-- `memory_braid.bootstrap.begin|complete|error`
-- `memory_braid.reconcile.begin|progress|complete|error`
 - `memory_braid.search.local|mem0|merge|inject|skip`
+- `memory_braid.search.mem0_decay`
 - `memory_braid.capture.extract|ml|persist|skip`
+- `memory_braid.lifecycle.reinforce|cleanup`
 - `memory_braid.entity.model_load|warmup|extract`
 - `memory_braid.mem0.request|response|error`
 

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "memory-braid",
   "name": "Memory Braid",
-  "description": "Hybrid memory plugin that augments local core/QMD memory with Mem0 recall, capture, bootstrap import, and reconcile.",
+  "description": "Hybrid memory plugin that augments local core/QMD memory with Mem0 capture and recall.",
   "kind": "memory",
   "configSchema": {
     "type": "object",
@@ -52,6 +52,7 @@
             "enum": ["local", "hybrid", "ml"],
             "default": "local"
           },
+          "includeAssistant": { "type": "boolean", "default": false },
           "maxItemsPerRun": { "type": "integer", "minimum": 1, "maximum": 50, "default": 6 },
           "ml": {
             "type": "object",
@@ -93,29 +94,6 @@
           }
         }
       },
-      "bootstrap": {
-        "type": "object",
-        "additionalProperties": false,
-        "properties": {
-          "enabled": { "type": "boolean", "default": true },
-          "startupMode": { "type": "string", "enum": ["async"], "default": "async" },
-          "includeMarkdown": { "type": "boolean", "default": true },
-          "includeSessions": { "type": "boolean", "default": true },
-          "sessionLookbackDays": { "type": "integer", "minimum": 1, "maximum": 3650, "default": 90 },
-          "batchSize": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 },
-          "concurrency": { "type": "integer", "minimum": 1, "maximum": 16, "default": 3 }
-        }
-      },
-      "reconcile": {
-        "type": "object",
-        "additionalProperties": false,
-        "properties": {
-          "enabled": { "type": "boolean", "default": true },
-          "intervalMinutes": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 30 },
-          "batchSize": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100 },
-          "deleteStale": { "type": "boolean", "default": true }
-        }
-      },
       "dedupe": {
         "type": "object",
         "additionalProperties": false,
@@ -137,6 +115,28 @@
           }
         }
       },
+      "timeDecay": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean", "default": false }
+        }
+      },
+      "lifecycle": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean", "default": false },
+          "captureTtlDays": { "type": "integer", "minimum": 1, "maximum": 3650, "default": 90 },
+          "cleanupIntervalMinutes": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 10080,
+            "default": 360
+          },
+          "reinforceOnRecall": { "type": "boolean", "default": true }
+        }
+      },
       "debug": {
         "type": "object",
         "additionalProperties": false,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memory-braid",
-  "version": "0.3.7",
-  "description": "OpenClaw memory plugin that augments local memory with Mem0, bootstrap import, reconcile, and capture.",
+  "version": "0.4.0",
+  "description": "OpenClaw memory plugin that augments local memory with Mem0 capture and recall.",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {

package/src/chunking.ts

@@ -1,7 +1,4 @@
 import crypto from "node:crypto";
-import fs from "node:fs/promises";
-import path from "node:path";
-import type { ManagedSourceType, ManifestChunk, TargetWorkspace } from "./types.js";
 
 export function sha256(value: string): string {
   return crypto.createHash("sha256").update(value).digest("hex");
@@ -14,267 +11,3 @@ export function normalizeWhitespace(value: string): string {
 export function normalizeForHash(value: string): string {
   return normalizeWhitespace(value).toLowerCase();
 }
-
-function buildChunkKey(params: {
-  workspaceHash: string;
-  agentId: string;
-  sourceType: ManagedSourceType;
-  path: string;
-  index: number;
-  text: string;
-}): string {
-  return sha256(
-    [
-      params.workspaceHash,
-      params.agentId,
-      params.sourceType,
-      params.path,
-      String(params.index),
-      normalizeForHash(params.text),
-    ].join("|"),
-  );
-}
-
-export function chunkText(value: string, chunkSize = 1200, overlap = 180): string[] {
-  const text = value.trim();
-  if (!text) {
-    return [];
-  }
-  const out: string[] = [];
-  let cursor = 0;
-  while (cursor < text.length) {
-    const end = Math.min(text.length, cursor + chunkSize);
-    out.push(text.slice(cursor, end).trim());
-    if (end >= text.length) {
-      break;
-    }
-    cursor = Math.max(cursor + 1, end - overlap);
-  }
-  return out.filter(Boolean);
-}
-
-async function walkMarkdownFiles(dir: string, out: string[]): Promise<void> {
-  const entries = await fs.readdir(dir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (entry.isSymbolicLink()) {
-      continue;
-    }
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      await walkMarkdownFiles(full, out);
-      continue;
-    }
-    if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
-      out.push(full);
-    }
-  }
-}
-
-export async function listCanonicalMarkdownMemoryFiles(workspaceDir: string): Promise<string[]> {
-  const result: string[] = [];
-  const candidates = [path.join(workspaceDir, "MEMORY.md"), path.join(workspaceDir, "memory.md")];
-  for (const candidate of candidates) {
-    try {
-      const stat = await fs.lstat(candidate);
-      if (stat.isFile() && !stat.isSymbolicLink()) {
-        result.push(candidate);
-      }
-    } catch {
-      // ignore
-    }
-  }
-
-  const memoryDir = path.join(workspaceDir, "memory");
-  try {
-    const stat = await fs.lstat(memoryDir);
-    if (stat.isDirectory() && !stat.isSymbolicLink()) {
-      await walkMarkdownFiles(memoryDir, result);
-    }
-  } catch {
-    // ignore
-  }
-
-  return Array.from(new Set(result.map((filePath) => path.resolve(filePath))));
-}
-
-function normalizeSessionMessageText(content: unknown): string | null {
-  if (typeof content === "string") {
-    const normalized = normalizeWhitespace(content);
-    return normalized || null;
-  }
-  if (!Array.isArray(content)) {
-    return null;
-  }
-
-  const parts: string[] = [];
-  for (const block of content) {
-    if (!block || typeof block !== "object") {
-      continue;
-    }
-    const item = block as { type?: unknown; text?: unknown };
-    if (item.type === "text" && typeof item.text === "string") {
-      const normalized = normalizeWhitespace(item.text);
-      if (normalized) {
-        parts.push(normalized);
-      }
-    }
-  }
-  if (parts.length === 0) {
-    return null;
-  }
-  return parts.join(" ");
-}
-
-export async function listRecentSessionFiles(
-  stateDir: string,
-  agentId: string,
-  lookbackDays: number,
-): Promise<string[]> {
-  const dir = path.join(stateDir, "agents", agentId, "sessions");
-  const threshold = Date.now() - lookbackDays * 24 * 60 * 60 * 1000;
-  try {
-    const entries = await fs.readdir(dir, { withFileTypes: true });
-    const files: string[] = [];
-    for (const entry of entries) {
-      if (!entry.isFile() || !entry.name.endsWith(".jsonl")) {
-        continue;
-      }
-      const abs = path.join(dir, entry.name);
-      try {
-        const stat = await fs.stat(abs);
-        if (stat.mtimeMs >= threshold) {
-          files.push(abs);
-        }
-      } catch {
-        // ignore single file failure
-      }
-    }
-    return files;
-  } catch {
-    return [];
-  }
-}
-
-export async function buildMarkdownChunks(target: TargetWorkspace): Promise<ManifestChunk[]> {
-  const files = await listCanonicalMarkdownMemoryFiles(target.workspaceDir);
-  const chunks: ManifestChunk[] = [];
-
-  for (const filePath of files) {
-    let raw = "";
-    let statMtime = Date.now();
-    try {
-      raw = await fs.readFile(filePath, "utf8");
-      const stat = await fs.stat(filePath);
-      statMtime = stat.mtimeMs;
-    } catch {
-      continue;
-    }
-
-    const relPath = path.relative(target.workspaceDir, filePath).replace(/\\/g, "/");
-    const pieces = chunkText(raw);
-    pieces.forEach((piece, index) => {
-      chunks.push({
-        chunkKey: buildChunkKey({
-          workspaceHash: target.workspaceHash,
-          agentId: target.agentId,
-          sourceType: "markdown",
-          path: relPath,
-          index,
-          text: piece,
-        }),
-        contentHash: sha256(normalizeForHash(piece)),
-        sourceType: "markdown",
-        text: piece,
-        path: relPath,
-        workspaceHash: target.workspaceHash,
-        agentId: target.agentId,
-        updatedAt: statMtime,
-      });
-    });
-  }
-
-  return chunks;
-}
-
-export async function buildSessionChunks(
-  target: TargetWorkspace,
-  lookbackDays: number,
-): Promise<ManifestChunk[]> {
-  const files = await listRecentSessionFiles(target.stateDir, target.agentId, lookbackDays);
-  const chunks: ManifestChunk[] = [];
-
-  for (const filePath of files) {
-    let raw = "";
-    let statMtime = Date.now();
-    try {
-      raw = await fs.readFile(filePath, "utf8");
-      const stat = await fs.stat(filePath);
-      statMtime = stat.mtimeMs;
-    } catch {
-      continue;
-    }
-
-    const lines = raw.split("\n");
-    const conversationParts: string[] = [];
-    for (const line of lines) {
-      if (!line.trim()) {
-        continue;
-      }
-      let parsed: unknown;
-      try {
-        parsed = JSON.parse(line);
-      } catch {
-        continue;
-      }
-      if (!parsed || typeof parsed !== "object") {
-        continue;
-      }
-      const record = parsed as { type?: unknown; message?: unknown };
-      if (record.type !== "message") {
-        continue;
-      }
-      const message = record.message as { role?: unknown; content?: unknown } | undefined;
-      if (!message || typeof message.role !== "string") {
-        continue;
-      }
-      if (message.role !== "user" && message.role !== "assistant") {
-        continue;
-      }
-      const text = normalizeSessionMessageText(message.content);
-      if (!text) {
-        continue;
-      }
-      const roleLabel = message.role === "user" ? "User" : "Assistant";
-      conversationParts.push(`${roleLabel}: ${text}`);
-    }
-
-    if (conversationParts.length === 0) {
-      continue;
-    }
-
-    const sessionText = conversationParts.join("\n");
-    const sessionRelPath = path.join("sessions", target.agentId, path.basename(filePath)).replace(/\\/g, "/");
-    const pieces = chunkText(sessionText);
-    pieces.forEach((piece, index) => {
-      chunks.push({
-        chunkKey: buildChunkKey({
-          workspaceHash: target.workspaceHash,
-          agentId: target.agentId,
-          sourceType: "session",
-          path: sessionRelPath,
-          index,
-          text: piece,
-        }),
-        contentHash: sha256(normalizeForHash(piece)),
-        sourceType: "session",
-        text: piece,
-        path: sessionRelPath,
-        workspaceHash: target.workspaceHash,
-        agentId: target.agentId,
-        updatedAt: statMtime,
-      });
-    });
-  }
-
-  return chunks;
-}