openclaw-memory-decay 0.1.8 → 0.1.10

package/README.md

@@ -86,17 +86,22 @@ openclaw gateway restart
 If you previously installed this plugin from a local checkout via `openclaw plugins install -l .`, migrate to the npm package. Local/path-based installs are now deprecated in favor of the published npm package.
 
 ```bash
-# 1. Install from npm instead
+# 1. Remove the old pre-0.1.8 plugin install if it exists
+openclaw plugins uninstall memory-decay
+
+# 2. Install from npm instead
 openclaw plugins install openclaw-memory-decay
 
-# 2. Restart gateway
+# 3. Restart gateway
 openclaw gateway restart
 
-# 3. Verify
+# 4. Verify
 openclaw plugins list | grep openclaw-memory-decay  # should show: openclaw-memory-decay | loaded
 curl -s http://127.0.0.1:8100/health       # should show: {"status":"ok","current_tick":0}
 ```
 
+If the old install is already gone, `openclaw plugins uninstall memory-decay` will simply report that nothing was removed.
+
 If auto-detection does not recover your backend path after migration, set the interpreter explicitly:
 
 ```bash
@@ -104,6 +109,12 @@ openclaw config set plugins.entries.openclaw-memory-decay.config.pythonPath "~/.
 openclaw gateway restart
 ```
 
+If you are upgrading from an older release, note the plugin id changed from `memory-decay` to `openclaw-memory-decay` in `0.1.8`.
+
+- New installs should use `plugins.entries.openclaw-memory-decay`.
+- Older configs under `plugins.entries.memory-decay.config` are still read as a compatibility fallback.
+- For a clean config, migrate to the new key when convenient.
+
 **Your memories are safe.** The SQLite database (`memories.db`) is not affected by plugin reinstallation or migration to npm install.
 
 To update in the future:
@@ -136,8 +147,8 @@ Add to `~/.openclaw/openclaw.json` under `plugins.entries.openclaw-memory-decay.
 | Option | Default | Description |
 |--------|---------|-------------|
 | `serverPort` | `8100` | Port for the memory-decay HTTP server |
-| `memoryDecayPath` | (auto) | Path to memory-decay-core. Auto-detected from the install-time Python environment if not set |
-| `pythonPath` | `python3` | Path to Python interpreter. Set this explicitly if you use a custom venv path instead of `~/.openclaw/venvs/memory-decay` |
+| `memoryDecayPath` | (auto) | Path to memory-decay-core. Auto-detected at runtime from the documented default venv or from explicit config |
+| `pythonPath` | `python3` | Path to Python interpreter. Set this explicitly if you do not use `~/.openclaw/venvs/memory-decay` |
 | `dbPath` | `~/.openclaw/memory-decay-data/memories.db` | SQLite database location |
 | `autoSave` | `true` | Auto-save every conversation turn at low importance. Set `false` to let the agent decide what to save |
 | `embeddingProvider` | `local` | Embedding provider: `local`, `openai`, or `gemini` |
@@ -263,12 +274,32 @@ openclaw plugins install openclaw-memory-decay
 curl http://127.0.0.1:8100/health
 ```
 
-If the import check fails, install the backend into a virtualenv and either reactivate that venv before reinstalling the plugin or set `pythonPath` explicitly:
+If the import check fails, install the backend into the documented default venv path or set `pythonPath` explicitly:
 ```bash
 python3 -m venv ~/.openclaw/venvs/memory-decay
 ~/.openclaw/venvs/memory-decay/bin/pip install memory-decay
 ```
 
+If `memory-decay` is only installed in your system Python or in some other venv, the plugin may still fail to auto-detect it. In that case, point the plugin at the exact Python you want it to use:
+
+```bash
+openclaw config set plugins.entries.openclaw-memory-decay.config.pythonPath "/absolute/path/to/python"
+openclaw gateway restart
+```
+
+Sanity check the exact interpreter before restarting:
+
+```bash
+/absolute/path/to/python -c "import memory_decay.server; print('ok')"
+```
+
+If you use a different venv path, configure it directly:
+
+```bash
+openclaw config set plugins.entries.openclaw-memory-decay.config.pythonPath "/absolute/path/to/venv/bin/python"
+openclaw gateway restart
+```
+
 ### `error: externally-managed-environment`
 
 Your system Python is PEP 668 managed. Install `memory-decay` into a virtualenv instead of the system interpreter:
@@ -359,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.8",
+  "version": "0.1.10",
   "configSchema": {
     "type": "object",
     "additionalProperties": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-memory-decay",
-  "version": "0.1.8",
+  "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/scripts/detect-python-lib.mjs

@@ -3,6 +3,10 @@ import { existsSync as nodeExistsSync, mkdtempSync, readFileSync, rmSync } from
 import { homedir as nodeHomedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 
+const PYTHON_COMMAND_CANDIDATES = process.platform === "win32"
+  ? ["python"]
+  : ["python3", "python", "python3.13", "python3.12", "python3.11", "python3.10"];
+
 function resolvePythonPath(command, { execFileSync = nodeExecFileSync, isWin = process.platform === "win32" } = {}) {
   if (isAbsolute(command)) {
     return command;
@@ -43,7 +47,7 @@ export function buildPythonCandidates({
     pathCandidates.push(join(root, isWin ? ".venv/Scripts/python.exe" : ".venv/bin/python"));
   }
 
-  const commandCandidates = isWin ? ["python"] : ["python3", "python"];
+  const commandCandidates = isWin ? ["python"] : PYTHON_COMMAND_CANDIDATES;
   return [...new Set([
     ...pathCandidates.filter((candidate) => existsSync(candidate)),
     ...commandCandidates,

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

@@ -20,13 +20,18 @@ interface DetectPythonEnvOptions {
   removeTempDir?: (path: string) => void;
 }
 
+const PYTHON_COMMAND_CANDIDATES = process.platform === "win32"
+  ? ["python"]
+  : ["python3", "python", "python3.13", "python3.12", "python3.11", "python3.10"];
+
 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",
   };
 }
 
@@ -73,7 +78,7 @@ export function buildPythonCandidates({
       join(root, isWin ? ".venv/Scripts/python.exe" : ".venv/bin/python")),
   ].filter((candidate): candidate is string => typeof candidate === "string" && candidate.length > 0 && existsSync(candidate));
 
-  const commandCandidates = isWin ? ["python"] : ["python3", "python"];
+  const commandCandidates = isWin ? ["python"] : PYTHON_COMMAND_CANDIDATES;
   return [...new Set([...pathCandidates, ...commandCandidates])];
 }
 
@@ -92,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,
@@ -102,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" });
@@ -122,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()}`);
   }
 }