openclaw-memory-decay 0.1.9 → 0.1.10

package/README.md

@@ -390,6 +390,67 @@ openclaw gateway restart
 | `~/.openclaw/memory-decay-data/memories.db` | Memory database |
 | `~/.openclaw/workspace/memory/` | Legacy memory files (can migrate) |
 
+## Known Upgrade Issues
+
+These are real migration issues we hit while moving from older releases. If an AI agent is helping with setup, it should check these before assuming the install itself is broken.
+
+### 1. Old `memory-decay` install still exists
+
+Symptom:
+- `duplicate plugin id detected`
+- `plugin id mismatch`
+- both `memory-decay` and `openclaw-memory-decay` appear in `openclaw plugins list`
+
+Fix:
+
+```bash
+openclaw plugins uninstall memory-decay
+openclaw gateway restart
+```
+
+If duplicate warnings still mention `.openclaw-install-stage-*`, remove stale failed-install directories:
+
+```bash
+find ~/.openclaw/extensions -maxdepth 1 -type d -name '.openclaw-install-stage-*' -print
+find ~/.openclaw/extensions -maxdepth 1 -type d -name '.openclaw-install-stage-*' -exec rm -rf {} +
+openclaw gateway restart
+```
+
+### 2. Plugin updated, but port `8100` never comes up
+
+Symptom:
+- `curl http://127.0.0.1:8100/health` times out
+- gateway log says `Could not auto-detect memory-decay installation`
+
+Fix:
+
+```bash
+openclaw config set plugins.entries.openclaw-memory-decay.config.pythonPath "~/.openclaw/venvs/memory-decay/bin/python"
+openclaw config set plugins.entries.openclaw-memory-decay.config.serverPort 8100
+openclaw gateway restart
+```
+
+If you also need to restore the backend root explicitly:
+
+```bash
+openclaw config set plugins.entries.openclaw-memory-decay.config.memoryDecayPath "/absolute/path/to/memory-decay-core"
+openclaw gateway restart
+```
+
+### 3. `memory-decay` is installed, but only in system Python or another venv
+
+Symptom:
+- `pip show memory-decay` looks fine
+- plugin still cannot find `memory_decay.server`
+
+Fix:
+
+```bash
+/absolute/path/to/python -c "import memory_decay.server; print('ok')"
+openclaw config set plugins.entries.openclaw-memory-decay.config.pythonPath "/absolute/path/to/python"
+openclaw gateway restart
+```
+
 ## License
 
 MIT

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-memory-decay",
   "name": "Memory Decay",
   "description": "Human-like memory with decay and reinforcement for OpenClaw agents",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "configSchema": {
     "type": "object",
     "additionalProperties": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-memory-decay",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "type": "module",
   "description": "OpenClaw memory plugin backed by memory-decay engine",
   "main": "./src/index.js",
@@ -17,6 +17,8 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "node --test test/*.test.mjs",
+    "test:integration": "docker build -t memory-decay-test -f Dockerfile .. && docker run --rm memory-decay-test",
     "prepublishOnly": "npm run build",
     "postinstall": "node scripts/detect-python.mjs",
     "setup": "node scripts/link-sdk.mjs"

package/src/index.ts

@@ -4,7 +4,7 @@ import { MemoryDecayClient } from "./client.js";
 import { loadLegacyPluginConfig } from "./legacy-config.js";
 import { MemoryDecayService, type ServiceConfig } from "./service.js";
 import { shouldMigrate, migrateMarkdownMemories } from "./migrator.js";
-import { detectPythonEnv, mergePythonEnv } from "./python-env.js";
+import { detectPythonEnv, mergePythonEnv, REQUIRED_BACKEND_VERSION } from "./python-env.js";
 import { toFreshness } from "./types.js";
 
 const BOOTSTRAP_PROMPT = `## Memory System (memory-decay)
@@ -90,7 +90,7 @@ const memoryDecayPlugin = {
         // Resolve pythonPath + memoryDecayPath: config > .python-env.json (set at install time) > error
         let memoryDecayPath = (cfg.memoryDecayPath as string) ?? "";
         let pythonPath = (cfg.pythonPath as string) ?? "";
-        let detectedEnv: { memoryDecayPath?: string; pythonPath?: string } = {};
+        let detectedEnv: { memoryDecayPath?: string; pythonPath?: string; backendVersion?: string } = {};
         const { dirname, resolve } = await import("node:path");
         const { fileURLToPath } = await import("node:url");
         const pluginRoot = dirname(fileURLToPath(import.meta.url));
@@ -110,6 +110,7 @@ const memoryDecayPlugin = {
           { memoryDecayPath, pythonPath },
           detectedEnv,
         ));
+        const backendVersion = detectedEnv.backendVersion ?? "unknown";
         if (!memoryDecayPath) {
           ctx.logger.error(
             "Could not auto-detect memory-decay installation. " +
@@ -131,9 +132,15 @@ const memoryDecayPlugin = {
           experimentDir: cfg.experimentDir as string | undefined,
         };
 
-        service = new MemoryDecayService(config);
+        service = new MemoryDecayService(config, ctx.logger);
         await service.start();
         ctx.logger.info("Server started");
+        if (backendVersion !== "unknown" && backendVersion !== REQUIRED_BACKEND_VERSION) {
+          ctx.logger.info(
+            `Backend version ${backendVersion} does not match recommended ${REQUIRED_BACKEND_VERSION}. ` +
+            `To update: pip install memory-decay==${REQUIRED_BACKEND_VERSION}`
+          );
+        }
       },
       async stop(ctx) {
         if (service) {

package/src/python-env.ts

@@ -26,11 +26,12 @@ const PYTHON_COMMAND_CANDIDATES = process.platform === "win32"
 
 export function mergePythonEnv(
   configured: PythonEnvLike,
-  detected: PythonEnvLike = {},
-): { memoryDecayPath: string; pythonPath: string } {
+  detected: { memoryDecayPath?: string; pythonPath?: string; backendVersion?: string } = {},
+): { memoryDecayPath: string; pythonPath: string; backendVersion: string } {
   return {
     memoryDecayPath: configured.memoryDecayPath || detected.memoryDecayPath || "",
     pythonPath: configured.pythonPath || detected.pythonPath || "",
+    backendVersion: detected.backendVersion || "unknown",
   };
 }
 
@@ -96,6 +97,8 @@ function resolvePythonPath(
   return execFileSync(resolver, [command], { encoding: "utf8" }).trim().split(/\r?\n/)[0];
 }
 
+export const REQUIRED_BACKEND_VERSION = "0.1.3";
+
 export function detectPythonEnv({
   pluginRoot,
   env = process.env,
@@ -106,7 +109,7 @@ export function detectPythonEnv({
   makeTempDir = () => mkdtempSync(join(tmpdir(), "memory-decay-python-env-")),
   readPathFile = (path) => readFileSync(path, "utf8"),
   removeTempDir = (path) => rmSync(path, { recursive: true, force: true }),
-}: DetectPythonEnvOptions): { memoryDecayPath: string; pythonPath: string } | null {
+}: DetectPythonEnvOptions): { memoryDecayPath: string; pythonPath: string; backendVersion: string } | null {
   for (const candidate of buildPythonCandidates({ pluginRoot, env, isWin, homedir, existsSync })) {
     try {
       execFileSync(candidate, ["-c", "import memory_decay.server"], { stdio: "ignore" });
@@ -126,9 +129,19 @@ export function detectPythonEnv({
       const moduleFile = readPathFile(outputPath).trim();
       removeTempDir(tempDir);
 
+      let backendVersion = "unknown";
+      try {
+        const versionOutput = execFileSync(candidate, [
+          "-c",
+          `import memory_decay; print(getattr(memory_decay, "__version__", "unknown"))`,
+        ], { encoding: "utf8" }).trim();
+        backendVersion = versionOutput || "unknown";
+      } catch {}
+
       return {
         pythonPath: resolvePythonPath(candidate, { execFileSync, isWin }),
         memoryDecayPath: resolveMemoryDecayPath(moduleFile),
+        backendVersion,
       };
     } catch {}
   }

package/src/service.ts

@@ -13,19 +13,34 @@ export interface ServiceConfig {
   experimentDir?: string;
 }
 
+export interface Logger {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+  debug?: (msg: string) => void;
+}
+
 export class MemoryDecayService {
   private process: ChildProcess | null = null;
   private client: MemoryDecayClient;
   private config: ServiceConfig;
+  private logger: Logger;
   private restartCount = 0;
   private maxRestarts = 3;
+  private stderrTail: string[] = [];
+  private stopped = false;
+  private static readonly STDERR_MAX_LINES = 50;
 
-  constructor(config: ServiceConfig) {
+  constructor(config: ServiceConfig, logger: Logger) {
     this.config = config;
+    this.logger = logger;
     this.client = new MemoryDecayClient(config.port);
   }
 
   async start(): Promise<void> {
+    this.stopped = false;
+    this.stderrTail = [];
+
     const args = [
       "-m", "memory_decay.server",
       "--host", "127.0.0.1",
@@ -44,11 +59,37 @@ export class MemoryDecayService {
       stdio: ["ignore", "pipe", "pipe"],
     });
 
-    this.process.on("exit", (code) => {
-      if (code !== 0 && this.restartCount < this.maxRestarts) {
-        this.restartCount++;
-        console.error(`[memory-decay] Server exited with ${code}, restarting (${this.restartCount}/${this.maxRestarts})`);
-        this.start();
+    this.process.stderr?.on("data", (chunk: Buffer) => {
+      for (const line of chunk.toString().split("\n").filter(Boolean)) {
+        this.stderrTail.push(line);
+        if (this.stderrTail.length > MemoryDecayService.STDERR_MAX_LINES) {
+          this.stderrTail.shift();
+        }
+      }
+    });
+
+    this.process.stdout?.on("data", (chunk: Buffer) => {
+      if (this.logger.debug) {
+        this.logger.debug(chunk.toString().trimEnd());
+      }
+    });
+
+    this.process.on("exit", (code, signal) => {
+      if (code !== 0) {
+        const context = this.formatStderrContext();
+        const sig = signal ? ` (signal: ${signal})` : "";
+
+        if (this.restartCount < this.maxRestarts) {
+          this.restartCount++;
+          this.logger.error(
+            `Server exited with code ${code}${sig}, restarting (${this.restartCount}/${this.maxRestarts})${context}`
+          );
+          this.start().catch(() => {});
+        } else {
+          this.logger.error(
+            `Server exited with code ${code}${sig}, max restarts (${this.maxRestarts}) exhausted${context}`
+          );
+        }
       }
     });
 
@@ -56,8 +97,11 @@ export class MemoryDecayService {
   }
 
   async stop(): Promise<void> {
+    this.stopped = true;
     if (this.process) {
       this.maxRestarts = 0;
+      this.process.stdout?.removeAllListeners("data");
+      this.process.stderr?.removeAllListeners("data");
       this.process.kill("SIGTERM");
       this.process = null;
     }
@@ -67,16 +111,24 @@ export class MemoryDecayService {
     return this.client;
   }
 
+  private formatStderrContext(): string {
+    return this.stderrTail.length
+      ? `\nLast stderr:\n  ${this.stderrTail.slice(-10).join("\n  ")}`
+      : "";
+  }
+
   private async waitForHealth(timeoutMs = 15000): Promise<void> {
     const start = Date.now();
     while (Date.now() - start < timeoutMs) {
+      if (this.stopped) return;
       try {
         await this.client.health();
+        this.restartCount = 0;
         return;
       } catch {
         await new Promise((r) => setTimeout(r, 500));
       }
     }
-    throw new Error(`[memory-decay] Server failed to start within ${timeoutMs}ms`);
+    throw new Error(`Server failed to start within ${timeoutMs}ms${this.formatStderrContext()}`);
   }
 }